fix(setup): route gen:skill-docs through bun_cmd; drop tail -3 pipe that masks bun failures

Two surgical fixes called out by @jbetala7 on #1883, carved out as the
focused fast-merge PR they asked for.

1. link_codex_skill_dirs, link_factory_skill_dirs, and
   link_opencode_skill_dirs called literal `bun run gen:skill-docs ...`
   instead of routing through `bun_cmd`, the wrapper installed by
   prepare_bun_for_windows_compile. On a non-ASCII Windows username the
   literal call would exit non-zero; the next line checks if the output
   directory exists and prints a soft warning, masking the failure.

2. The gbrain-detected SKILL.md regen ran
   `bun_cmd run gen:skill-docs:user --host claude 2>&1 | tail -3`. The
   pipe makes the subshell's exit status `tail`'s (always 0), swallowing
   bun's failure so the `|| log "warning..."` clause right after never
   fires regardless of whether bun succeeded.

Tests exercise the exit-code path, not source-grep: stub bun_cmd to fail,
run the actual shell pattern, assert the `|| log` clause fires only on
the fixed shape and does NOT fire on the buggy shape with the pipe.

Author: DavidMiserak

CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## [1.56.2.0] - 2026-06-07
+
+## **Two `setup` bugs you couldn't see. One swallowed `bun` failures, one silently broke Codex/Factory/OpenCode skill regen on a non-ASCII Windows username.**
+
+Both were originally found during the phase-reorder review on #1883 and asked
+to be carved out for a focused, fast-merge PR. This is that PR. Just the
+fixes, no restructuring.
+
+The `bun_cmd` wrapper exists for one reason: on Windows with a non-ASCII
+username, `prepare_bun_for_windows_compile` copies bun to an ASCII path and
+points `BUN_CMD` at it, because the system `bun` can't always handle a path
+through `C:\Users\<unicode>\`. Three skill-doc generation calls in
+`link_codex_skill_dirs`, `link_factory_skill_dirs`, and
+`link_opencode_skill_dirs` bypassed the wrapper and called literal `bun run`,
+so on a non-ASCII Windows username the regen exited non-zero. The next line
+checks if the output directory was created, prints a "warning" with a
+manual-recovery command, and continues — masking the failure as a soft
+warning when it was actually the wrapper being skipped.
+
+The gbrain-detected regen call had a subtler bug. `bun_cmd run
+gen:skill-docs:user --host claude 2>&1 | tail -3` pipes through `tail` so
+the subshell's exit status is `tail`'s, not bun's. `tail` always succeeds,
+so the `|| log "warning..."` clause right after never fired regardless of
+whether bun succeeded. Removing the pipe restores the warning path.
+
+### The numbers that matter
+
+Source: `bun test test/setup-bun-cmd-and-pipe-bugs.test.ts` on this branch.
+
+| Metric | Before | After | Δ |
+|--------|--------|-------|---|
+| `link_*_skill_dirs` honor `BUN_CMD` override | no | yes | 3 call sites fixed |
+| `gen:skill-docs:user` warning fires on bun failure | no | yes | exit-code path restored |
+| Functional tests exercising the exit-code path | 0 | 5 | reviewer-requested over source-grep |
+
+The tests don't grep source. They stub `bun_cmd` to fail, run the exact
+shell pattern from `setup`, and assert the `|| log` clause does fire on the
+fixed shape and does NOT fire on the buggy shape. The reviewer on #1883
+specifically asked for this over a source-string check.
+
+### What this means for you
+
+If you install gstack with a non-ASCII Windows username, your Codex,
+Factory Droid, and OpenCode skill docs will now actually regenerate
+instead of silently failing. If you have gbrain installed and the
+post-detect SKILL.md regen ever fails, you'll see the warning instead
+of a silent skip. Nothing to configure.
+
+### Itemized changes
+
+#### Fixed
+
+- `link_codex_skill_dirs`, `link_factory_skill_dirs`, and
+  `link_opencode_skill_dirs` now route `gen:skill-docs` through `bun_cmd`
+  (the wrapper that honors `BUN_CMD`) instead of literal `bun run`. The
+  literal form bypassed the Windows non-ASCII path workaround, so on a
+  Windows username with non-ASCII characters the regen exited non-zero
+  silently. (setup:714, 919, 951)
+- The gbrain-detected SKILL.md regen no longer pipes `gen:skill-docs:user`
+  through `tail -3`. The pipe made `tail`'s exit status the subshell's,
+  swallowing bun's failure so the trailing `|| log "warning..."` guard
+  never fired. (setup:1297)
+
+#### For contributors
+
+- `test/setup-bun-cmd-and-pipe-bugs.test.ts` — 5 functional tests:
+  - 2 prove the exit-code semantics of the `| tail -3` removal by running
+    the actual shell pattern with a stubbed-to-fail `bun_cmd` and asserting
+    the `||` clause fires only without the pipe.
+  - 2 prove the `bun_cmd` wrapper honors `BUN_CMD` via a sentinel script,
+    and that all three `link_*_skill_dirs` helpers route through it.
+  - 1 anchors on the live `gbrain detected` block in `setup` (source-anchored,
+    not line-number) to confirm no pipe before the `||` guard.
+
+  These are real exit-code-path tests, not source-string grep — addressing
+  the specific concern raised on #1883.
+
+Credit: bugs identified by @jbetala7 during review on #1883.
+
 ## [1.56.1.0] - 2026-06-03
 
 ## **`/sync-gbrain` can no longer delete your repo. Cleanup now refuses any directory it cannot prove it created.**

VERSION

@@ -1 +1 @@
-1.56.1.0
+1.56.2.0

setup

@@ -711,7 +711,7 @@ link_codex_skill_dirs() {
 
   if [ ! -d "$agents_dir" ]; then
     echo "  Generating .agents/ skill docs..."
-    ( cd "$gstack_dir" && bun run gen:skill-docs --host codex )
+    ( cd "$gstack_dir" && bun_cmd run gen:skill-docs --host codex )
   fi
 
   if [ ! -d "$agents_dir" ]; then
@@ -916,7 +916,7 @@ link_factory_skill_dirs() {
 
   if [ ! -d "$factory_dir" ]; then
     echo "  Generating .factory/ skill docs..."
-    ( cd "$gstack_dir" && bun run gen:skill-docs --host factory )
+    ( cd "$gstack_dir" && bun_cmd run gen:skill-docs --host factory )
   fi
 
   if [ ! -d "$factory_dir" ]; then
@@ -948,7 +948,7 @@ link_opencode_skill_dirs() {
 
   if [ ! -d "$opencode_dir" ]; then
     echo "  Generating .opencode/ skill docs..."
-    ( cd "$gstack_dir" && bun run gen:skill-docs --host opencode )
+    ( cd "$gstack_dir" && bun_cmd run gen:skill-docs --host opencode )
   fi
 
   if [ ! -d "$opencode_dir" ]; then
@@ -1294,7 +1294,7 @@ if [ -x "$DETECT_BIN" ]; then
       log "gbrain detected — regenerating Claude SKILL.md with brain-aware blocks (~250 token overhead per planning skill)..."
       (
         cd "$SOURCE_GSTACK_DIR"
-        bun_cmd run gen:skill-docs:user --host claude 2>&1 | tail -3
+        bun_cmd run gen:skill-docs:user --host claude
       ) || log "  warning: gen:skill-docs:user failed — run 'bun run gen:skill-docs:user' manually if you want brain-aware blocks"
     else
       log "gbrain not detected — brain-aware blocks suppressed in planning-skill SKILL.md files (zero token overhead)."

test/setup-bun-cmd-and-pipe-bugs.test.ts

@@ -0,0 +1,122 @@
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const SETUP_SRC = fs.readFileSync(path.join(ROOT, 'setup'), 'utf-8');
+
+// Run a bash snippet, return {stdout, stderr, status}.
+function runBash(script: string): { stdout: string; stderr: string; status: number } {
+  const r = spawnSync('bash', ['-c', script], { encoding: 'utf-8' });
+  return { stdout: r.stdout || '', stderr: r.stderr || '', status: r.status ?? -1 };
+}
+
+describe('setup: gen:skill-docs:user exit-code propagation (pipe-masking fix)', () => {
+  // The bug: `cmd 2>&1 | tail -3` makes the subshell exit status `tail`'s,
+  // so `(...) || log "warning"` never fires when `cmd` fails. The fix removes
+  // the pipe. These tests RUN the pattern (not grep source) to prove the
+  // exit-code semantics actually change.
+
+  test('without pipe: failing bun_cmd triggers the || warning clause', () => {
+    const r = runBash(`
+      set +e
+      bun_cmd() { return 1; }      # stub: gen:skill-docs:user failed
+      log() { echo "LOG:$*"; }
+      (
+        cd /tmp
+        bun_cmd run gen:skill-docs:user --host claude
+      ) || log "  warning: gen:skill-docs:user failed"
+    `);
+    expect(r.stdout).toContain('LOG:  warning: gen:skill-docs:user failed');
+  });
+
+  test('with pipe (the bug shape): failing bun_cmd does NOT trigger the warning', () => {
+    const r = runBash(`
+      set +e
+      bun_cmd() { return 1; }      # stub: gen:skill-docs:user failed
+      log() { echo "LOG:$*"; }
+      (
+        cd /tmp
+        bun_cmd run gen:skill-docs:user --host claude 2>&1 | tail -3
+      ) || log "  warning: gen:skill-docs:user failed"
+    `);
+    expect(r.stdout).not.toContain('LOG:  warning');
+  });
+
+  test('setup: the live gbrain regen block has no pipe before the || guard', () => {
+    // Slice the exact block from setup and confirm the fix is in place
+    // without resorting to a fragile line-number check.
+    const start = SETUP_SRC.indexOf('gbrain detected — regenerating');
+    expect(start).toBeGreaterThan(-1);
+    const end = SETUP_SRC.indexOf('|| log', start);
+    expect(end).toBeGreaterThan(start);
+    const block = SETUP_SRC.slice(start, end);
+    expect(block).toContain('bun_cmd run gen:skill-docs:user --host claude');
+    // The bug shape: `... | tail -N` between the call and the `|| log` guard.
+    expect(block).not.toMatch(/gen:skill-docs:user[^\n]*\|\s*tail/);
+  });
+});
+
+describe('setup: bun_cmd routing in link_*_skill_dirs (Windows non-ASCII path fix)', () => {
+  // The bug: `bun run ...` bypasses the BUN_CMD wrapper installed by
+  // prepare_bun_for_windows_compile. On a non-ASCII Windows username,
+  // BUN_CMD points to an ASCII-path copy of bun and the literal `bun`
+  // on PATH may not work. Test by stubbing BUN_CMD to a sentinel that
+  // writes a marker file, and proving the wrapper path actually invokes it.
+
+  test('bun_cmd wrapper invokes $BUN_CMD (not literal bun on PATH)', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-buncmd-'));
+    const marker = path.join(tmp, 'invoked');
+    const sentinel = path.join(tmp, 'fake-bun');
+    fs.writeFileSync(sentinel, `#!/usr/bin/env bash\necho "ARGS:$*" > "${marker}"\n`);
+    fs.chmodSync(sentinel, 0o755);
+
+    const r = runBash(`
+      set -e
+      BUN_CMD="${sentinel}"
+      bun_cmd() { "$BUN_CMD" "$@"; }
+      ( cd /tmp && bun_cmd run gen:skill-docs --host codex )
+    `);
+
+    expect(r.status).toBe(0);
+    expect(fs.existsSync(marker)).toBe(true);
+    expect(fs.readFileSync(marker, 'utf-8').trim()).toBe('ARGS:run gen:skill-docs --host codex');
+
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test('setup: the three link_*_skill_dirs helpers all use bun_cmd, not literal bun', () => {
+    // Extract each helper body and check the gen:skill-docs invocation
+    // inside it. Source-anchored (not line-number) and not a global grep,
+    // so we only assert about the actual code path the bug fix touches.
+    for (const fn of [
+      'link_codex_skill_dirs',
+      'link_factory_skill_dirs',
+      'link_opencode_skill_dirs',
+    ]) {
+      const start = SETUP_SRC.indexOf(`${fn}() {`);
+      expect(start).toBeGreaterThan(-1);
+      const end = SETUP_SRC.indexOf('\n}\n', start);
+      expect(end).toBeGreaterThan(start);
+      const body = SETUP_SRC.slice(start, end);
+      // Must call through the wrapper.
+      expect(body).toMatch(/bun_cmd run gen:skill-docs/);
+      // Bug shape: a literal `bun run gen:skill-docs` in executable position
+      // (skipping any comment / warning-string mentions that aren't being run).
+      const lines = body.split('\n').filter((l) => {
+        const t = l.trim();
+        if (!t || t.startsWith('#')) return false;
+        // Strings inside echo/warning messages don't execute bun.
+        if (/echo\s+['"]/.test(t)) return false;
+        return true;
+      });
+      for (const l of lines) {
+        // `bun_cmd run ...` is fine; a bare `bun run ...` is the bug.
+        const stripped = l.replace(/bun_cmd run/g, '');
+        expect(stripped).not.toMatch(/\bbun run gen:skill-docs/);
+      }
+    }
+  });
+});