@boyingliu01/xp-gate 0.26.0 → 0.27.1

package/bin/xp-gate.js

@@ -19,15 +19,127 @@ const { bootstrap } = require('../lib/bootstrap.js');
 const { updateHooks } = require('../lib/update-hooks.js');
 const gateRunner = require('../lib/gate-runner.js');
 
+// #392-#6: a user-supplied path embedded in a shell command string lets cmd.exe
+// interpret metacharacters (& | ^ < > % ! " and newline) and execute injected
+// commands. On POSIX a bare spawn (shell:false) passes argv as discrete,
+// uninterpreted bytes, so nothing is injectable. On win32 a `.cmd` wrapper such
+// as npx.cmd cannot be launched without a shell (CreateProcess raises EINVAL),
+// so we must shell out through cmd.exe -- and we only do so AFTER rejecting any
+// argument that carries a cmd metacharacter. Rejection, not escaping, is the
+// safe defense: a path containing a metachar is refused outright rather than
+// risk a quoting mistake. This guard must stay in front of every launcher.
+// \r joins \n: cmd treats a stray carriage return as a command separator too
+// (Delphi walkthrough R1, MN-01).
+const CMD_METACHAR_RE = /[&|^<>%!"\n\r]/;
+
+// The ONLY place a child process may be launched with an engaged shell.
+// Named so a static grep stays readable, and pinned by check-alignment-cli
+// .test.mjs: no other launcher in this file may enable a shell.
+const SHELL_ON_WINDOWS_ONLY = process.platform === 'win32';
+
+function firstUnsafeArg(argv) {
+  for (const arg of argv) {
+    if (typeof arg === 'string' && CMD_METACHAR_RE.test(arg)) return arg;
+  }
+  return undefined;
+}
+
+function quoteForCmdShell(arg) {
+  // With an engaged shell node concatenates file+args into one cmd.exe command
+  // string WITHOUT quoting (DEP0190), so an argument carrying a space would
+  // split into multiple argv elements downstream. Double-quoting is safe here
+  // ONLY because every caller has already run firstUnsafeArg: the character "
+  // that could break out of the quote is on the rejection list.
+  return `"${arg}"`;
+}
+
+function spawnNpx(tsxArgs) {
+  const { spawnSync } = require('child_process');
+  // Reject any user-supplied argument that could be interpreted by cmd.exe.
+  // Every element of tsxArgs beyond the fixed tokens (-y tsx <script>) is a
+  // user path; a metachar there is refused, not quoted, per #392-#6.
+  const unsafe = firstUnsafeArg(tsxArgs);
+  if (unsafe) {
+    console.error(`check-alignment: refusing path containing a shell metacharacter: ${unsafe}`);
+    return { status: 1 };
+  }
+  const isWin = process.platform === 'win32';
+  // The shell engages on win32 only, and is only safe because every user
+  // argument above is guaranteed metachar-free; each token additionally gets
+  // cmd quoting so spaces survive (see quoteForCmdShell).
+  // Guarded IO: a failed spawn must surface as a result, not crash the CLI.
+  const argv = ['-y', 'tsx', ...tsxArgs];
+  let result;
+  try {
+    result = spawnSync(isWin ? 'npx.cmd' : 'npx', isWin ? argv.map(quoteForCmdShell) : argv, {
+      stdio: 'inherit',
+      shell: SHELL_ON_WINDOWS_ONLY,
+    });
+  } catch (err) {
+    return { status: 1, error: err };
+  }
+  return result || { status: 1 };
+}
+
 function handleUIReview() {
-  const { execSync } = require('child_process');
   const uiReviewPath = path.join(__dirname, '..', 'lib', 'ui-review.ts');
+  const result = spawnNpx([uiReviewPath]);
+  process.exitCode = result.error ? 1 : (result.status === 0 ? 0 : 1);
+}
+
+function runAlignmentInProcess(specPath, testDirs, outputPath, jsonMode, runFullAlignment) {
+  const { execFileSync } = require('child_process');
+  if (!runFullAlignment) {
+    // Loaded lazily by the caller inside the tsx guard; kept optional so an
+    // in-repo direct call still works.
+    ({ runFullAlignment } = require('../lib/test-alignment.ts'));
+  }
+  let headCommit = 'unknown';
   try {
-    execSync(`npx -y tsx "${uiReviewPath}"`, { stdio: 'inherit' });
-    process.exit(0);
+    headCommit = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() || 'unknown';
   } catch (err) {
-    process.exit(1);
+    headCommit = 'unknown';
   }
+  let report;
+  try {
+    report = runFullAlignment({
+      specPath,
+      testDirs: testDirs || undefined,
+      headCommit,
+      outputPath: outputPath || undefined,
+    });
+  } catch (err) {
+    console.error('check-alignment failed:', err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  if (jsonMode) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log('Status:', report.alignment_status);
+    console.log('Score:', report.score);
+    console.log('Misaligned:', report.misaligned_tests.length);
+  }
+  // exitCode-style contract (#392 review): never process.exit() right after a
+  // JSON print — buffered stdout must flush. Returning the code and letting the
+  // dispatcher end the turn naturally is what keeps --json output complete.
+  return report.alignment_status === 'PASS' ? 0 : 1;
+}
+
+function runAlignmentViaNpx(runnerPath, specPath, testDirs, outputPath, jsonMode) {
+  // User-supplied paths travel as discrete argv elements routed through
+  // spawnNpx, which refuses any argument carrying a cmd metacharacter before a
+  // shell can see it (#392-#6). The runner script path is a fixed internal path.
+  const argv = [runnerPath, '--spec', specPath];
+  if (testDirs) argv.push('--tests', testDirs[0]);
+  if (outputPath) argv.push('--output', outputPath);
+  if (jsonMode) argv.push('--json');
+  const result = spawnNpx(argv);
+  if (result.error) {
+    console.error('check-alignment: unable to load the alignment engine (tsx unavailable).');
+    console.error(result.error.message);
+    return 1;
+  }
+  return result.status === 0 ? 0 : 1;
 }
 
 async function runAlignmentCheck(subargs) {
@@ -42,32 +154,43 @@ async function runAlignmentCheck(subargs) {
 
   const jsonMode = subargs.includes('--json');
 
-  // Load TS module via tsx
-  const { execSync } = require('child_process');
-  const alignmentPath = path.join(__dirname, '..', 'lib', 'test-alignment.ts');
+  // Injection guard (#392-#6) runs BEFORE any launcher, including the
+  // in-process fast path: a metachar path must be refused identically on both
+  // platforms (Delphi walkthrough R1, MJ-02 — behavioral, not shape-only).
+  for (const value of [specPath, ...(testDirs || []), outputPath].filter(v => v !== undefined)) {
+    const unsafe = firstUnsafeArg([value]);
+    if (unsafe) {
+      console.error(`check-alignment: refusing path containing a shell metacharacter: ${unsafe}`);
+      return 1;
+    }
+  }
+
+  const runnerPath = path.join(__dirname, '..', 'lib', 'check-alignment-runner.cjs');
 
+  // Primary: run the engine in-process via tsx/cjs (fast path, works in-repo
+  // where tsx is a devDependency). Fall back to `npx -y tsx` when tsx is not
+  // resolvable, which happens in the published global install (the package
+  // ships zero runtime deps per the zero-install contract). npx self-provisions
+  // tsx on demand, so the published command stays functional without adding a dep.
+  //
+  // The try guards ONLY the tsx loader's module-load step. The engine call sits
+  // outside it: an engine-level failure is a real bug that must surface, not be
+  // silently swallowed and misattributed to "tsx unavailable" by the fallback.
+  // Delphi walkthrough R2 CI-02: require('../lib/test-alignment.ts') also needs
+  // the loader, so it belongs INSIDE the guard — if the .ts file itself cannot
+  // load, the npx fallback re-attempts it under a provisioned tsx instead of
+  // crashing with an unhandled exception. Engine EXECUTION stays outside.
+  let runFullAlignment;
   try {
-    execSync(`npx tsx -e "
-      import { runFullAlignment } from '${alignmentPath}';
-      const report = runFullAlignment({
-        specPath: '${specPath}',
-        testDirs: ${JSON.stringify(testDirs || null)},
-        headCommit: require('child_process').execSync('git rev-parse HEAD 2>/dev/null || echo unknown').toString().trim(),
-        outputPath: ${outputPath ? `'${outputPath}'` : 'undefined'},
-      });
-      if (${jsonMode}) {
-        console.log(JSON.stringify(report, null, 2));
-      } else {
-        console.log('Status:', report.alignment_status);
-        console.log('Score:', report.score);
-        console.log('Misaligned:', report.misaligned_tests.length);
-      }
-      process.exit(report.alignment_status === 'PASS' ? 0 : 1);
-    "`, { stdio: 'inherit' });
+    require('tsx/cjs');
+    ({ runFullAlignment } = require('../lib/test-alignment.ts'));
   } catch (err) {
-    return 1;
+    if (!err || (err.code !== 'MODULE_NOT_FOUND' && !/Cannot find module/.test(String(err && err.message)))) {
+      throw err;
+    }
+    return runAlignmentViaNpx(runnerPath, specPath, testDirs, outputPath, jsonMode);
   }
-  return 0;
+  return runAlignmentInProcess(specPath, testDirs, outputPath, jsonMode, runFullAlignment);
 }
 
 const COMMANDS = {
@@ -154,7 +277,7 @@ const COMMANDS = {
       }
       return doctor(subargs).then(code => process.exit(code));
     },
-    usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force]] | --json | --format json  (the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks)'
+    usage: 'xp-gate doctor [--fix [--install-tools] | --sync-hooks [--force] | --refresh-env] | --json | --format json  (the two machine-readable modes print one JSON document and refuse --fix/--sync-hooks; --refresh-env is read-only so it combines with them)'
   },
   'ui-review': {
     description: 'Run UI review for non-sprint developers (generates .ui-gate-result.json)',
@@ -188,7 +311,17 @@ const COMMANDS = {
   },
   'check-alignment': {
     description: 'Run test-specification alignment check (deterministic, no LLM)',
-    run: subargs => runAlignmentCheck(subargs).then(code => process.exit(code)),
+    run: subargs => runAlignmentCheck(subargs).then(code => {
+      // exitCode, not process.exit(): the in-process --json document must flush
+      // its buffered stdout before the process ends (#392 review, MJ-01).
+      process.exitCode = code;
+    }).catch(err => {
+      // A quality gate must fail with a deterministic exit code and a real
+      // message — never an unhandled rejection whose code depends on Node's
+      // default mode (Delphi walkthrough R2, MJ-02).
+      console.error('check-alignment: unexpected failure:', err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+    }),
     usage: 'xp-gate check-alignment [--spec <path>] [--tests <dir>] [--json] [--output <path>]'
   },
   'upgrade': {

package/hooks/pre-commit

@@ -179,11 +179,15 @@ run_in_subdir() {
   
   if [ -n "$PROJECT_SUBDIR" ] && [ "$PROJECT_SUBDIR" != "." ]; then
     # Run command in subdirectory, then return to original directory
-    pushd "$PROJECT_SUBDIR" > /dev/null 2>&1
-    eval "$cmd"
-    local exit_code=$?
-    popd > /dev/null 2>&1
-    return $exit_code
+    # #392-#10: guard cd/pushd so a missing directory cannot run the gate in
+    # the wrong cwd.
+    if pushd "$PROJECT_SUBDIR" > /dev/null 2>&1; then
+      eval "$cmd"
+      local exit_code=$?
+      popd > /dev/null 2>&1
+      return $exit_code
+    fi
+    return 1
   else
     # Run in current directory
     eval "$cmd"
@@ -984,10 +988,14 @@ IN_PROJECT_SUBDIR=0
 _lang_count=$(echo "$PROJECT_LANGS" | wc -w)
 if [ -n "$PROJECT_SUBDIR" ] && [ "$PROJECT_SUBDIR" != "." ] && [ "$PROJECT_LANG" != "documentation-only" ] && [ "$_lang_count" -le 1 ]; then
   ORIGINAL_DIR=$(pwd)
-  cd "$PROJECT_SUBDIR"
-  IN_PROJECT_SUBDIR=1
-  echo "Working in: $PROJECT_SUBDIR/"
-  echo ""
+  # #392-#10: guard cd so a missing subdir cannot run gates in the wrong cwd.
+  if cd "$PROJECT_SUBDIR" 2>/dev/null; then
+    IN_PROJECT_SUBDIR=1
+    echo "Working in: $PROJECT_SUBDIR/"
+    echo ""
+  else
+    echo "WARN: could not enter $PROJECT_SUBDIR — continuing at repo root" >&2
+  fi
 fi
 
 # ============================================================================
@@ -1639,7 +1647,16 @@ else
   echo "Running jscpd for Go duplicate code detection..."
   FILES_TO_CHECK=$(echo "$CHANGED_FILES" | grep "\.go$" | head -20)
   if [ -n "$FILES_TO_CHECK" ]; then
-    jscpd $FILES_TO_CHECK 2>&1 | head -10
+    # #392-#9: capture jscpd's real exit code via temp file instead of piping
+    # through head (which would swallow the exit status under pipefail analysis).
+    GO_JSCPD_TMP=$(mktemp)
+    jscpd $FILES_TO_CHECK > "$GO_JSCPD_TMP" 2>&1
+    JSCPD_GO_EXIT=$?
+    head -10 "$GO_JSCPD_TMP"
+    rm -f "$GO_JSCPD_TMP"
+    if [ "$JSCPD_GO_EXIT" -ne 0 ]; then
+      echo "⚠️  jscpd (Go) exited with code $JSCPD_GO_EXIT"
+    fi
   fi
   echo "✅ PASSED - Go duplicate code check completed."
     ;;

package/lib/__tests__/check-alignment-cli.test.mjs

@@ -0,0 +1,77 @@
+/**
+ * @test check-alignment CLI
+ * @intent Guard the #392-#6 injection fix and the zero-install fallback path:
+ *         (1) no spawn/exec call in bin/xp-gate.js may enable a shell (which on
+ *         win32 would let cmd.exe interpret metacharacters embedded in
+ *         user-supplied paths); (2) the published runner emits a complete,
+ *         parseable --json document instead of truncating it on process.exit().
+ * @covers AC-392-06 (injection), zero-install contract (fallback)
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const BIN = join(here, '..', '..', 'bin', 'xp-gate.js');
+const RUNNER = join(here, '..', 'check-alignment-runner.cjs');
+
+describe('check-alignment CLI injection surface (#392-#6)', () => {
+  it('bin/xp-gate.js rejects shell metacharacters before any launch', () => {
+    const src = readFileSync(BIN, 'utf8');
+    // The injection guard must be in front of every subprocess launch: any
+    // argument carrying a cmd.exe metacharacter is refused outright, never
+    // escaped, before a shell can see it (#392-#6, Delphi R1-C). This holds on
+    // both platforms -- on win32 a .cmd wrapper needs cmd.exe (EINVAL without
+    // one), so the metachar guard is the only thing that makes shelling safe.
+    expect(src).toMatch(/CMD_METACHAR_RE/);
+    expect(src).toMatch(/firstUnsafeArg/);
+    // The metachar class must cover the cmd.exe separators/redirection.
+    expect(src).toMatch(/CMD_METACHAR_RE\s*=.*[&|^<>%!]/);
+    // Any shell a launcher may engage must be gated on the metachar rejection
+    // having run first, and never enabled unconditionally on win32. The single
+    // sanctioned engagement is the named SHELL_ON_WINDOWS_ONLY constant.
+    expect(src).not.toMatch(/shell\s*:\s*(?:true|process\.platform)/);
+    expect(src).toMatch(/shell:\s*SHELL_ON_WINDOWS_ONLY/);
+    // execSync interpolates argv into a command string via a shell, so it is
+    // banned; execFileSync is fine only for hardcoded binaries with non-user
+    // argv (git rev-parse HEAD). The launchers below are the user-input path.
+    expect(src).not.toMatch(/\bexecSync\s*\(/);
+  });
+
+  it('a metacharacter path is refused end to end before any launch (MJ-02)', () => {
+    // Behavioral, not shape: invoke the real CLI with a --spec whose path
+    // carries a cmd metacharacter and assert the documented refusal — exit 1
+    // plus the "refusing" message, never a spawned engine.
+    const evil = join(here, 'evil&echo.spec.yaml');
+    const result = spawnSync(process.execPath, [BIN, 'check-alignment', '--spec', evil, '--json'], {
+      encoding: 'utf8',
+      timeout: 60000,
+    });
+    expect(result.status).toBe(1);
+    expect(`${result.stderr}${result.stdout}`).toMatch(/metacharacter|refus/i);
+  }, 90000);
+});
+
+describe('check-alignment runner output integrity', () => {
+  it('emits a complete parseable JSON document with --json', () => {
+    const spec = join(here, 'test-alignment.test.ts');
+    const result = spawnSync(process.execPath, [RUNNER, '--spec', spec, '--json'], {
+      encoding: 'utf8',
+    });
+    expect(result.error).toBeUndefined();
+    // The whole stdout stream must be one valid JSON document. A process.exit()
+    // immediately after console.log would truncate it on some platforms.
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed).toHaveProperty('alignment_status');
+    expect(parsed).toHaveProperty('score');
+    expect(parsed).toHaveProperty('head_commit');
+  });
+
+  it('fails fast with exit code 1 when --spec is missing', () => {
+    const result = spawnSync(process.execPath, [RUNNER], { encoding: 'utf8' });
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('--spec <path> is required');
+  });
+});

package/lib/__tests__/doctor-469-hook-env.test.js

@@ -17,11 +17,16 @@ const describeWin = isWindows ? describe : describe.skip;
 // Walkthrough FC-02: a bare `return` inside it() silently reports PASS on a
 // runner without bash — a false-green in the very suite that guards against
 // false greens. Bash-gated tests must SKIP loudly instead.
-const { execSync } = require('child_process');
-const BASH_AVAILABLE = (() => {
-  try { execSync('bash --version', { stdio: 'ignore' }); return true; } catch { return false; }
+// On Windows a bare PATH 'bash' may resolve to the WSL System32 stub, whose
+// argv handling drops `-c` positional args — probing through it answers for
+// the wrong environment (the exact #469 failure class). Resolve the same
+// authoritative bash the hooks get: checkBash().
+const { checkBash } = require('../detect-deps.js');
+const BASH_PROBE = (() => {
+  const b = checkBash();
+  return b.ok ? b.path : null;
 })();
-const itWithBash = BASH_AVAILABLE ? it : it.skip;
+const itWithBash = BASH_PROBE ? it : it.skip;
 
 describe('doctor hook-env probing (#469)', () => {
   function mod() {
@@ -30,7 +35,7 @@ describe('doctor hook-env probing (#469)', () => {
 
   itWithBash('AC-469-01: a tool the hook env sees is reported with its hook-env path', async () => {
     const { probeToolInHookEnv } = mod();
-    const bashPath = isWindows ? 'bash' : '/bin/sh';
+    const bashPath = isWindows ? BASH_PROBE : '/bin/sh';
     const p = await probeToolInHookEnv(isWindows ? 'node' : 'sh', bashPath);
     expect(typeof p).toBe('string');
     expect(p.length).toBeGreaterThan(0);
@@ -39,7 +44,7 @@ describe('doctor hook-env probing (#469)', () => {
   itWithBash('AC-469-01: a tool absent from the hook env returns null — no fall-through', async () => {
     const { detectCliToolAsync } = mod();
     const result = await detectCliToolAsync('definitely-not-a-real-tool-xyz-469', isWindows, {
-      bashPath: 'bash',
+      bashPath: BASH_PROBE,
     });
     // With bash present there is NO fall-through: `where` finding nothing is
     // irrelevant here, the hook env verdict is final.
@@ -56,7 +61,7 @@ describe('doctor hook-env probing (#469)', () => {
 
   itWithBash('AC-469-01: an installed tool is visible through the hook-env tier', async () => {
     const { detectCliToolAsync } = mod();
-    const result = await detectCliToolAsync('node', true, { bashPath: 'bash' });
+    const result = await detectCliToolAsync('node', true, { bashPath: BASH_PROBE });
     expect(result.available).toBe(true);
     // The hook-env path is POSIX form on Windows — cmd.exe cannot run it.
     if (isWindows) expect(result.path.startsWith('/')).toBe(true);

package/lib/__tests__/doctor-exec-retry.test.js

@@ -0,0 +1,152 @@
+/**
+ * @test REQ-DOCTOR retry-on-empty-stream guard
+ * @intent On win32, cmd.exe (exec's shell) can deliver exit 0 with an EMPTY
+ *         stdout+stderr when many spawns are in flight — doctor read that as
+ *         "Not found" and red-flagged Node/Git/hooksPath on a healthy machine.
+ *         execWithTimeout must retry an empty-but-successful probe before
+ *         reporting it, and must NOT retry real failures or real output.
+ * @covers AC-DOCTOR-RETRY-01
+ */
+const path = require('path');
+const { describe, it, expect, afterEach } = await import('vitest');
+
+const cpPath = require.resolve('child_process');
+
+function stubExec(behaviors) {
+  // doctor builds its async exec at load time via util.promisify(exec), which
+  // binds Node's INTERNAL custom promisify implementation — replacing the plain
+  // `exec` property afterwards is invisible to it (measured: stub fired 0-1
+  // times while the real cmd.exe child ran). The only patch point that holds
+  // across a fresh require is util.promisify itself.
+  const util = require('util');
+  const originalPromisify = util.promisify;
+  const calls = [];
+  util.promisify = function (fn) {
+    if (fn && fn.name === 'exec') {
+      stubWasConsumed = true;
+      return (cmd, opts = {}) => {
+        const attempt = calls.length;
+        calls.push(cmd);
+        return new Promise((resolve, reject) => {
+          behaviors[attempt]((err, stdout, stderr) => {
+            if (err) reject(err);
+            else resolve({ stdout, stderr });
+          }, attempt);
+        });
+      };
+    }
+    return originalPromisify.call(util, fn);
+  };
+  return {
+    calls,
+    restore: () => { util.promisify = originalPromisify; },
+  };
+}
+
+// Node couples exec to promisify via a custom symbol; if a future runtime drops
+// that coupling the name-based stub above silently stops intercepting and the
+// real cmd.exe child runs. Each test flips this to true from inside its own
+// stubbed load (never inherited from an earlier test), so afterEach can fail
+// loudly instead of passing vacuously.
+let stubWasConsumed = false;
+
+describe('execWithTimeout empty-stream retry (#525 follow-up)', () => {
+  let stub = null;
+  afterEach(() => {
+    if (stub) { stub.restore(); stub = null; }
+    // Fail loudly if the fn.name === 'exec' stub never intercepted this test's
+    // doctor load — that would mean Node dropped the exec/promisify custom-
+    // symbol coupling and the assertions ran against real cmd.exe children.
+    expect(stubWasConsumed, `stub did not intercept the doctor load in this test`).toBe(true);
+    stubWasConsumed = false;
+  });
+
+  function freshDoctor() {
+    const doctorPath = require.resolve('../doctor.js');
+    delete require.cache[doctorPath];
+    return require(doctorPath).execWithTimeout;
+  }
+
+  it('AC-DOCTOR-RETRY-01: retries an exit-0 empty-stdout probe and keeps its own timeout', async () => {
+    stub = stubExec([
+      (cb) => cb(null, '', ''),            // the lost-stream failure mode
+      (cb) => cb(null, 'v24.19.0\n', ''),  // the same probe, stream intact
+    ]);
+    const execWithTimeout = freshDoctor();
+    const result = await execWithTimeout('node --version', { stdio: ['ignore', 'pipe', 'pipe'] });
+    expect(stub.calls.length).toBe(2);
+    expect(result).toEqual({ stdout: 'v24.19.0', stderr: '' });
+  });
+
+  it('AC-DOCTOR-RETRY-01: returns null after exhausting attempts on a persistently empty probe', async () => {
+    stub = stubExec([
+      (cb) => cb(null, '', ''),
+      (cb) => cb(null, '', ''),
+      (cb) => cb(null, '', ''),
+      (cb) => cb(null, 'unexpected fourth attempt', ''),
+    ]);
+    const execWithTimeout = freshDoctor();
+    const result = await execWithTimeout('node --version', {});
+    // win32: 3 attempts then null; other platforms: single attempt, still null.
+    expect(result).toBeNull();
+    expect(stub.calls.length).toBe(process.platform === 'win32' ? 3 : 1);
+  });
+
+  it('AC-DOCTOR-RETRY-01: does not retry when the probe produced output', async () => {
+    stub = stubExec([(cb) => cb(null, 'git version 2.54.0\n', '')]);
+    const execWithTimeout = freshDoctor();
+    const result = await execWithTimeout('git --version', {});
+    expect(stub.calls.length).toBe(1);
+    expect(result.stdout).toContain('git version');
+  });
+
+  it('AC-DOCTOR-RETRY-01: does not retry a failing command', async () => {
+    stub = stubExec([(cb) => cb(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }), '', '')]);
+    const execWithTimeout = freshDoctor();
+    const result = await execWithTimeout('definitely-not-a-tool --version', {});
+    expect(stub.calls.length).toBe(1);
+    expect(result).toBeNull();
+  });
+
+  it('AC-DOCTOR-RETRY-01: attempts:1 opts a side-effecting call out of the retry', async () => {
+    stub = stubExec([
+      (cb) => cb(null, '', ''),
+      (cb) => cb(null, 'unexpected second attempt', ''),
+    ]);
+    const execWithTimeout = freshDoctor();
+    const result = await execWithTimeout('some-mutating-command', { attempts: 1 });
+    expect(stub.calls.length).toBe(1);
+    expect(result).toBeNull();
+  });
+
+  it('AC-DOCTOR-RETRY-01: the attempts option is consumed, not forwarded to exec', async () => {
+    let forwarded = null;
+    stub = stubExec([(cb) => { cb(null, 'ok\n', ''); }]);
+    // Capture what doctor hands to the promisified exec by re-stubbing with an
+    // options recorder: stubExec's behaviors receive only the callback, so
+    // assert forwarding through a second fresh module with a capturing wrapper.
+    const util = require('util');
+    const originalPromisify = util.promisify;
+    const execWithTimeout = (() => {
+      util.promisify = function (fn) {
+        if (fn && fn.name === 'exec') {
+          stubWasConsumed = true;
+          return (cmd, opts = {}) => {
+            forwarded = opts;
+            return Promise.resolve({ stdout: 'ok\n', stderr: '' });
+          };
+        }
+        return originalPromisify.call(util, fn);
+      };
+      const doctorPath = require.resolve('../doctor.js');
+      delete require.cache[doctorPath];
+      const f = require(doctorPath).execWithTimeout;
+      util.promisify = originalPromisify;
+      return f;
+    })();
+    const result = await execWithTimeout('git --version', { attempts: 2, timeout: 999 });
+    expect(result.stdout).toBe('ok');
+    expect(forwarded.attempts).toBeUndefined();
+    expect(forwarded.timeout).toBe(999);
+  });
+});

package/lib/__tests__/doctor-module-resolution-parity.test.js

@@ -51,13 +51,22 @@ function matchBlock(source, pattern, label) {
 }
 
 function bashBin() {
-  const candidate = process.env.XP_GATE_BASH_BIN || 'bash';
-  const probe = spawnSync(candidate, ['-c', 'echo ok'], { encoding: 'utf8' });
-  // A missing runner must fail loudly, never read as a passing guard.
-  if (probe.status !== 0 || probe.error) {
-    throw new Error(`bash runner unavailable (${candidate}): ${probe.error ? probe.error.message : `exit ${probe.status}`}`);
+  if (process.env.XP_GATE_BASH_BIN) {
+    const probe = spawnSync(process.env.XP_GATE_BASH_BIN, ['-c', 'echo ok'], { encoding: 'utf8' });
+    if (probe.status !== 0 || probe.error) {
+      throw new Error(`bash runner unavailable (${process.env.XP_GATE_BASH_BIN}): ${probe.error ? probe.error.message : `exit ${probe.status}`}`);
+    }
+    return process.env.XP_GATE_BASH_BIN;
+  }
+  // Resolve the authoritative bash the hooks actually get. On Windows a bare
+  // PATH 'bash' may be the WSL System32 stub, whose `-c` scripts receive an
+  // empty $1 and resolve nothing — a vacuous resolver run, not a passing one.
+  const { checkBash } = require('../detect-deps.js');
+  const b = checkBash();
+  if (!b.ok) {
+    throw new Error(`bash runner unavailable: ${b.message || 'checkBash failed'}`);
   }
-  return candidate;
+  return b.path;
 }
 
 /**

package/lib/__tests__/doctor-tui-skill-freshness.test.js

@@ -32,12 +32,20 @@ describe('doctor-tui skill freshness (#439)', () => {
   // HOME has no platform marker, so detectPlatform() resolves to opencode.
   function installSkill(name, content) {
     const dir = path.join(tmpHome, '.config', 'opencode', 'skills', name);
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, 'SKILL.md'), content);
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'SKILL.md'), content);
+    } catch (err) {
+      throw new Error(`failed to install test skill ${name}: ${err && err.message}`);
+    }
   }
 
   function readBundled(name) {
-    return fs.readFileSync(path.join(bundledSkillsDir, name, 'SKILL.md'), 'utf8');
+    try {
+      return fs.readFileSync(path.join(bundledSkillsDir, name, 'SKILL.md'), 'utf8');
+    } catch (err) {
+      throw new Error(`failed to read bundled skill ${name}: ${err && err.message}`);
+    }
   }
 
   /** Same bytes, opposite line endings — the only difference a fresh install can have. */
@@ -134,7 +142,11 @@ describe('doctor-tui skill freshness (#439)', () => {
       .readdirSync(bundledSkillsDir, { withFileTypes: true })
       .filter((d) => d.isDirectory())
       .map((d) => d.name);
-    expect(skills.length).toBeGreaterThanOrEqual(13);
+    // Sanity floor only: the substantive assertion below is that every bundled
+    // skill declares a version. #522 removed clipboard-vision, dropping the
+    // bundle from 13 to 12 skills, so the floor tracks the current bundle size
+    // instead of a stale magic number (Delphi Round 1, finding A-Critical).
+    expect(skills.length).toBeGreaterThanOrEqual(12);
     const missing = skills.filter((name) => {
       const md = path.join(bundledSkillsDir, name, 'SKILL.md');
       return !/^version:\s*\d+\.\d+\.\d+/m.test(fs.readFileSync(md, 'utf8'));