@boyingliu01/xp-gate 0.26.0 → 0.27.1

package/lib/__tests__/test-alignment.test.ts

@@ -325,6 +325,43 @@ test('multiple assertions', () => {
     expect(result.tests[0].assertions).toBeGreaterThanOrEqual(4);
     expect(result.totalAssertions).toBeGreaterThanOrEqual(4);
   });
+
+  it('AC-FIXTURE-ASSERT: should count assertions per-test, not per-file (#392)', async () => {
+    // Regression for #392-#1: assertion counting must be scoped to the test
+    // body, otherwise totalAssertions is inflated by fileCount x perFileCount.
+    const testTs = `
+/**
+ * @test REQ-MULTI-001 First test
+ * @intent Assertion counting is per-test
+ * @covers AC-FIXTURE-MULTI-01
+ */
+test('first test', () => {
+  expect(a()).toBe(1);
+  expect(b()).toBe(2);
+});
+
+/**
+ * @test REQ-MULTI-002 Second test
+ * @intent Assertion counting is per-test
+ * @covers AC-FIXTURE-MULTI-02
+ */
+test('second test', () => {
+  expect(c()).toBe(3);
+});
+`;
+    const testFile = writeTempFile('multi-assert.test.ts', testTs);
+    const result = parseTestFiles([testFile]);
+
+    expect(result.tests).toHaveLength(2);
+    // countAssertions counts matching *patterns*, so `expect(x).toBe(y)` yields
+    // 2 (one `expect(` + one `toBe(`). First test body has 2 such assertions
+    // => 4; second has 1 => 2. The key regression: each test counts ONLY its own
+    // body (total 6), never the whole file (3 expect + 3 toBe = 6 per test,
+    // which would inflate totalAssertions to 12 under the old per-file bug).
+    expect(result.tests[0].assertions).toBe(4);
+    expect(result.tests[1].assertions).toBe(2);
+    expect(result.totalAssertions).toBe(6);
+  });
 });
 
 // ============================================================================

package/lib/__tests__/windows-bash-probe.test.js

@@ -0,0 +1,123 @@
+/**
+ * @test REQ-windows-bash probe behavior
+ * @intent resolveWindowsBashCandidates must accept only a bash that round-trips
+ *         `-c` positional argv AND reports MINGW/MSYS/CYGWIN via uname — the WSL
+ *         System32 stub (Linux uname, dropped $1) is rejected even when PATH
+ *         leads with it. Behavior is exercised through an injected fake spawner,
+ *         so no real interpreter configuration is assumed on the host (#469
+ *         follow-up, Delphi walkthrough R1 MN-06).
+ * @covers AC-WINBASH-01, AC-WINBASH-02
+ */
+const { describe, it, expect } = await import('vitest');
+const { resolveWindowsBashCandidates, checkBashVersion } = require('../detect-deps.js');
+
+// The candidate loop reads `where bash` from the host; tests inject both the
+// discovery runner and the probe spawner, so results are deterministic on any
+// machine regardless of what interpreter configuration it happens to have.
+function fakeWhere(whereOutput) {
+  return (cmd) => {
+    if (/^where bash/.test(cmd)) {
+      if (whereOutput instanceof Error) throw whereOutput;
+      return whereOutput || '';
+    }
+    throw new Error(`unexpected execSync: ${cmd}`);
+  };
+}
+
+function fakeSpawn(behaviors) {
+  const probed = [];
+  const fn = (candidate) => {
+    probed.push(candidate);
+    const b = behaviors[candidate];
+    if (b instanceof Error) throw b;
+    // Unknown candidates model a missing file: no stdout at all.
+    return { stdout: b !== undefined ? b : '' };
+  };
+  fn.probed = probed;
+  return fn;
+}
+
+describe('resolveWindowsBashCandidates (win32 authoritative bash)', () => {
+  it('AC-WINBASH-01: rejects a WSL stub whose $1 is empty and uname is Linux', () => {
+    // The resolver must find nothing rather than settle for the stub — and on
+    // current Windows the System32 stub is skipped by name without even being
+    // spawned (cold-launch stall); this world uses a non-System32 stub to keep
+    // testing the output-based rejection path itself.
+    const spawn = fakeSpawn({ 'C:\\wsl-stub\\bash.exe': '[ ]\nLinux\n' });
+    expect(resolveWindowsBashCandidates(spawn, fakeWhere('C:\\wsl-stub\\bash.exe\r\n'))).toBeNull();
+  });
+
+  it('AC-WINBASH-01: accepts the first candidate with argv round-trip + MINGW uname', () => {
+    const spawn = fakeSpawn({
+      'C:\\a\\bash.exe': '[]\nLinux\n', // drops $1 → reject
+      'C:\\b\\bash.exe': '[XPGATE_ARGV_PROBE]\nMINGW64_NT-10.0\n', // accept
+    });
+    const result = resolveWindowsBashCandidates(spawn, fakeWhere('C:\\a\\bash.exe\r\nC:\\b\\bash.exe\r\n'));
+    expect(result).toBe('C:\\b\\bash.exe');
+    // Known Git paths are probed BEFORE PATH discoveries (cold WSL launches
+    // stall the event loop for seconds), so a/b keep their relative order but
+    // trail the hardcoded fallbacks.
+    expect(spawn.probed.slice(-2)).toEqual(['C:\\a\\bash.exe', 'C:\\b\\bash.exe']);
+  });
+
+  it('AC-WINBASH-02: probes known Git paths before PATH discoveries', () => {
+    // Regression for the doctor fan-out starvation: System32\bash.exe leads
+    // `where bash` on WSL machines and its cold launch blocks ~3.4s. It must
+    // never be spawned at all — neither from where-output nor as any fallback.
+    const spawn = fakeSpawn({
+      'C:\\Program Files\\Git\\bin\\bash.exe': '[XPGATE_ARGV_PROBE]\nMSYS_NT-10.0\n',
+    });
+    const { result } = (() => ({
+      result: resolveWindowsBashCandidates(spawn, fakeWhere('C:\\Windows\\System32\\bash.exe\r\n')),
+    }))();
+    expect(result).toBe('C:\\Program Files\\Git\\bin\\bash.exe');
+    expect(spawn.probed).not.toContain('C:\\Windows\\System32\\bash.exe');
+  });
+
+  it('AC-WINBASH-01: a Linux uname with intact argv still fails the platform test', () => {
+    // A real WSL bash answers [XPGATE_ARGV_PROBE] correctly under some
+    // invocations but its filesystem view cannot run these hooks — uname wins.
+    const spawn = fakeSpawn({ 'C:\\wsl\\bash.exe': '[XPGATE_ARGV_PROBE]\nLinux\n' });
+    expect(resolveWindowsBashCandidates(spawn, fakeWhere('C:\\wsl\\bash.exe\r\n'))).toBeNull();
+  });
+
+  it('AC-WINBASH-01: a throwing candidate is skipped, not fatal', () => {
+    const spawn = fakeSpawn({
+      'C:\\gone\\bash.exe': new Error('ENOENT'),
+      'C:\\msys64\\usr\\bin\\bash.exe': '[XPGATE_ARGV_PROBE]\nMSYS_NT-10.0\n',
+    });
+    const result = resolveWindowsBashCandidates(spawn, fakeWhere(new Error('where unavailable')));
+    expect(result).toBe('C:\\msys64\\usr\\bin\\bash.exe');
+  });
+
+  it('AC-WINBASH-02: WSL stubs are skipped by name regardless of separators or case', () => {
+    // The filter normalizes slashes and ignores case/drive: forward-slash and
+    // lowercase variants of the same stub must still produce NO spawn call.
+    // The AppX alias lives under <Windows>\SystemApps\Microsoft.WSL_* — a
+    // user's own install merely NAMED ...\WindowsApps\... is NOT the stub and
+    // must still be probed (output-based rejection covers it).
+    const spawn = fakeSpawn({});
+    resolveWindowsBashCandidates(spawn, fakeWhere(
+      'c:/windows/sysnative/bash.exe\r\nC:\\WINDOWS\\System32\\bash.exe\r\nC:\\Windows\\SysWOW64\\bash.exe\r\nC:\\Users\\me\\AppData\\Local\\Microsoft\\WindowsApps\\bash.exe\r\n'
+    ));
+    expect(spawn.probed.filter(p => /system32|sysnative|syswow64|appdata\\local\\microsoft\\windowsapps/i.test(p.replace(/\//g, '\\')))).toEqual([]);
+    const userOwned = fakeSpawn({});
+    resolveWindowsBashCandidates(userOwned, fakeWhere('D:\\Tools\\WindowsApps\\bash.exe\r\n'));
+    expect(userOwned.probed).toContain('D:\\Tools\\WindowsApps\\bash.exe');
+  });
+
+  it('AC-WINBASH-01: checkBashVersion returns the bash VERSION tuple, not the uname line', () => {
+    // Contract regression (walkthrough R5 MJ-01/FC-02): doctor prints "GNU
+    // bash, version <field>" — the field must be the version number.
+    const spawn = (file, args) => ({
+      stdout: 'MINGW64_NT-10.0-26300\nGNU bash, version 5.3.9(1)-release (x86_64-pc-cygwin)\n',
+    });
+    expect(checkBashVersion(spawn, 'C:\\bash.exe')).toBe('5.3.9(1)-release');
+  });
+
+  it('AC-WINBASH-01: checkBashVersion degrades to unknown, never a crash, on odd output', () => {
+    expect(checkBashVersion(() => ({ stdout: '' }), 'C:\\bash.exe')).toBe('unknown');
+    expect(checkBashVersion(() => ({ stdout: 'MINGW64_NT-10.0\n' }), 'C:\\bash.exe')).toBe('unknown');
+    expect(checkBashVersion(() => { throw new Error('spawn failed'); }, 'C:\\bash.exe')).toBe('unknown');
+  });
+});

package/lib/check-alignment-runner.cjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * check-alignment-runner.cjs — Thin argv shim for test-alignment.ts
+ *
+ * Bridges the `xp-gate check-alignment` CLI to the TypeScript engine without
+ * shell-command interpolation of user-supplied paths (#392-#6).
+ *
+ * It is designed to be launched EITHER way:
+ *   1. In-repo (fast path): `node` loads this file after xp-gate.js already
+ *      called `require('tsx/cjs')`, so requiring `./test-alignment.ts` works.
+ *   2. Published global install (zero-install path): `npx -y tsx` runs this
+ *      file, and npx self-provisions tsx on demand (never a package dep), so
+ *      `./test-alignment.ts` loads even though the package ships zero deps.
+ *
+ * All user-supplied paths are passed as discrete argv elements, never embedded
+ * into a shell command string, preserving the #392-#6 injection fix.
+ */
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+// --- argv parsing ----------------------------------------------------------
+function argValue(argv, flag) {
+  const idx = argv.indexOf(flag);
+  return idx >= 0 && idx + 1 < argv.length ? argv[idx + 1] : undefined;
+}
+function argFlag(argv, flag) {
+  return argv.includes(flag);
+}
+
+const specPath = argValue(process.argv, '--spec');
+const testDirsArg = argValue(process.argv, '--tests');
+const outputPath = argValue(process.argv, '--output');
+const jsonMode = argFlag(process.argv, '--json');
+
+if (!specPath) {
+  console.error('check-alignment: --spec <path> is required');
+  process.exit(1);
+}
+
+const testDirs = testDirsArg ? [testDirsArg] : undefined;
+
+let headCommit = 'unknown';
+try {
+  headCommit = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() || 'unknown';
+} catch (err) {
+  headCommit = 'unknown';
+}
+
+const { runFullAlignment } = require('./test-alignment.ts');
+
+let report;
+try {
+  report = runFullAlignment({
+    specPath,
+    testDirs,
+    headCommit,
+    outputPath: outputPath || undefined,
+  });
+} catch (err) {
+  console.error('check-alignment failed:', err instanceof Error ? err.message : String(err));
+  process.exit(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);
+}
+// Set exitCode instead of process.exit() so buffered stdout (notably the
+// --json document) flushes fully before the process terminates (#392 review).
+process.exitCode = report.alignment_status === 'PASS' ? 0 : 1;

package/lib/detect-deps.js

@@ -270,12 +270,143 @@ function getSkillsDirs(platform) {
   return profile.skillsDirs;
 }
 
+/**
+ * Resolve a bash that can actually run the hooks.
+ *
+ * On Windows, `bash` on PATH is ambiguous: WSL installs C:\Windows\System32\
+ * bash.exe (a Linux interpreter whose filesystem view does not contain the
+ * Windows temp dirs the tooling passes to it), and its argv handling silently
+ * drops the positional arguments a `-c` script expects ($1 empty → scripts
+ * source nothing and "succeed" vacuously). Git for Windows ships the MSYS bash
+ * the hooks are written for. Probe candidates with an argv round-trip plus an
+ * uname check — only an MSYS/MINGW/CYGWIN bash counts on win32; a plain
+ * "bash --version" success proves nothing.
+ * @returns {string|null}
+ */
+function probeWindowsBash() {
+  const { spawnSync } = require('child_process');
+  // `where` runs through the same module so tests can fake discovery + probe.
+  const { execSync: localExecSync } = require('child_process');
+  return resolveWindowsBashCandidates(spawnSync, localExecSync);
+}
+
+// Candidate list + probe loop split out for behavior tests: a fake spawner can
+// simulate the WSL stub (echoes Linux / drops $1) vs an MSYS bash without any
+// real interpreter on PATH (Delphi walkthrough R1, MN-06).
+function resolveWindowsBashCandidates(spawnProbe, whereExecSync) {
+  const _execSync = whereExecSync || execSync;
+  const candidates = [];
+  // Well-known interpreters FIRST. Two reasons, both measured on win32:
+  // 1. A cold WSL launch (System32\bash.exe leads `where bash` when WSL is
+  //    installed) blocks its spawnSync for ~3.4s. checkBash runs inside
+  //    doctor's parallel fan-out, and that synchronous stall starves the
+  //    event loop past EXEC_TIMEOUT_MS — node/git then falsely report
+  //    "Not found" while spawning them standalone takes ~300ms.
+  // 2. The known Git paths ARE the answer we are looking for; probing them
+  //    first also skips pointless launches of stubs we would reject anyway.
+  candidates.push(
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe',
+    'C:\\msys64\\usr\\bin\\bash.exe',
+    'C:\\cygwin64\\bin\\bash.exe'
+  );
+  try {
+    const found = _execSync('where bash', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    for (const line of found.split(/\r?\n/)) {
+      const p = line.trim();
+      // Skip the WSL launcher outright: uname would reject it, and a cold
+      // launch costs seconds (see above). WindowsApps\bash.exe is the same
+      // WSL stub family (it just errors differently when WSL is absent).
+      if (!p) continue;
+      // Match on normalized separators: forward slashes, mixed case, or a
+      // non-C drive would otherwise slip a WSL stub past the filter and back
+      // into the multi-second cold-launch stall.
+      const norm = p.replace(/\//g, '\\');
+      // The WSL launcher appears as System32/Sysnative/SysWOW64\bash.exe, the
+      // AppX alias <Windows>\SystemApps\Microsoft.WSL_*\bash.exe, and the
+      // per-user AppX execution alias ...\AppData\Local\Microsoft\WindowsApps\
+      // bash.exe. A user's own install merely NAMED ...\WindowsApps\... (not
+      // under Microsoft\) is NOT the stub and stays in the list.
+      if (/\\windowsapps\\bash\.exe$/i.test(norm)
+        && (/\\systemapps\\/i.test(norm) || /\\appdata\\local\\microsoft\\windowsapps\\/i.test(norm))) continue;
+      // The WSL stub lives in the matching-arch System32 view: 64-bit
+      // C:\Windows\System32\bash.exe AND the 32-bit emulation redirect target
+      // C:\Windows\SysWOW64\bash.exe (where reports either depending on the
+      // bitness of the caller).
+      if (/\\windows\\system32\\bash\.exe$/i.test(norm) || /\\windows\\sysnative\\bash\.exe$/i.test(norm) || /\\windows\\syswow64\\bash\.exe$/i.test(norm)) continue;
+      if (!candidates.includes(p)) candidates.push(p);
+    }
+  } catch { /* where unavailable */ }
+  for (const candidate of candidates) {
+    try {
+      const r = spawnProbe(candidate, ['-c', 'echo "[$1]"; uname -s', 'sh', 'XPGATE_ARGV_PROBE'], {
+        encoding: 'utf8',
+        timeout: 5000,
+        windowsHide: true,
+      });
+      const out = String((r && r.stdout) || '');
+      if (out.includes('[XPGATE_ARGV_PROBE]') && /(MINGW|MSYS|CYGWIN)/i.test(out)) {
+        return candidate;
+      }
+    } catch { /* next candidate */ }
+  }
+  return null;
+}
+
 /**
  * Check if bash is available on the system.
  * XP-Gate hooks are bash scripts — Windows users need Git Bash installed.
- * @returns {{ok: boolean, path?: string, message?: string}}
+ * @returns {{ok: boolean, path?: string, version?: string, message?: string}}
  */
+// Split out for behavior tests: checkBashVersion takes the resolved bash path
+// and a spawner so the version-field contract (a bash VERSION tuple, not the
+// uname string) is assertable without a real interpreter on the host.
+function checkBashVersion(spawnProbe, winBash) {
+  let version = 'unknown';
+  try {
+    // --version through the SAME probe-style argv as the candidate loop:
+    // Git Bash's login startup (`bash --version`) costs ~1.7s, and checkBash
+    // sits on hot paths (doctor fan-out, every gate-runner launch) where a
+    // synchronous stall starves concurrent execs past their timeouts. The
+    // -c form is non-login (~300ms). uname proves the MSYS family AND bash
+    // --version inside it still yields the real bash version number — the
+    // `version` field must stay a bash version, not the uname string. No
+    // sed in the command: the parse lives in JS below, so a stripped MSYS
+    // install without sed cannot silently degrade to "unknown".
+    // NOTE the cp. prefix: this module binds only execSync at file scope,
+    // and checkBash sits outside probeWindowsBash's local spawnSync binding
+    // — a bare spawnSync here is a ReferenceError swallowed by the catch,
+    // which used to pin the detail line at "unknown" forever.
+    const result = spawnProbe(winBash, ['-c', 'uname -s; bash --version', 'sh'], { encoding: 'utf8', timeout: 5000 });
+    const out = String((result && result.stdout) || '').trim();
+    // Keep the field in the same shape checkEnv prints for every other tool
+    // ("GNU bash, version X.Y.Z(...)"): doctor prefixes "GNU bash, version ",
+    // so hand back the bare version tuple, not the whole line.
+    const versionLine = out.split('\n').find(line => /version/.test(line));
+    const match = versionLine && versionLine.match(/version\s+(\S+)/);
+    if (match) version = match[1];
+  } catch { /* keep unknown */ }
+  return version;
+}
+
 function checkBash() {
+  // On Windows resolve explicitly: PATH may lead with the WSL System32 stub,
+  // which cannot execute these hooks (wrong filesystem view, dropped $1).
+  if (process.platform === 'win32') {
+    const winBash = probeWindowsBash();
+    if (winBash) {
+      const version = checkBashVersion((...args) => require('child_process').spawnSync(...args), winBash);
+      return { ok: true, path: winBash, version };
+    }
+    return {
+      ok: false,
+      message: 'bash not found. Windows users must install [Git for Windows](https://git-scm.com/download/win).\n' +
+        '   During installation, ensure "Git Bash Here" is checked — this adds bash.exe to PATH.\n' +
+        '   After installation, restart your terminal and run `npm install` again.'
+    };
+  }
   try {
     // Try 'bash' first (works on Linux/macOS and when Git Bash is in PATH)
     const result = execSync('bash --version', {
@@ -289,17 +420,11 @@ function checkBash() {
       version: versionMatch ? versionMatch[1] : 'unknown'
     };
   } catch (e) {
-    // On Windows with Git Bash, try common locations
+    // POSIX fallback: common absolute locations
     const bashPaths = [
-      // Git for Windows
-      'C:\\Program Files\\Git\\bin\\bash.exe',
-      'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
-      'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-      'C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe',
-      // MSYS2
-      'C:\\msys64\\usr\\bin\\bash.exe',
-      // Cygwin
-      'C:\\cygwin64\\bin\\bash.exe',
+      '/bin/bash',
+      '/usr/bin/bash',
+      '/usr/local/bin/bash',
     ];
 
     for (const bashPath of bashPaths) {
@@ -319,15 +444,7 @@ function checkBash() {
       }
     }
 
-    // Windows-specific guidance
-    if (process.platform === 'win32') {
-      return {
-        ok: false,
-        message: 'bash not found. Windows users must install [Git for Windows](https://git-scm.com/download/win).\n' +
-          '   During installation, ensure "Git Bash Here" is checked — this adds bash.exe to PATH.\n' +
-          '   After installation, restart your terminal and run `npm install` again.'
-      };
-    }
+    // Windows is handled above; this fallback only runs on POSIX now.
 
     return {
       ok: false,
@@ -505,6 +622,8 @@ function compareVersions(a, b) {
 module.exports = {
   checkDeps,
   checkBash,
+  checkBashVersion,
+  resolveWindowsBashCandidates,
   autoInstallDeps,
   detectPlatform,
   getSkillsDirs,

package/lib/doctor.js

@@ -104,18 +104,52 @@ function noteSandboxAttribution(err) {
 }
 
 async function execWithTimeout(cmd, opts = {}) {
-  try {
-    const { stdout, stderr } = await execAsync(cmd, {
-      ...opts,
-      timeout: opts.timeout || EXEC_TIMEOUT_MS,
-    });
-    return { stdout: stdout.trim(), stderr: stderr.trim() };
-  } catch (err) {
-    // #525: a bare null here reads as "tool missing" and has already cost a
-    // misdiagnosis round. Name the sandbox once when it is the sandbox.
-    noteSandboxAttribution(err);
-    return null;
+  // Win32 false-negative guard. Under cmd.exe (exec's shell), a spawned probe
+  // can exit 0 while its stdout never reaches us — measured on this machine:
+  // `node --version` returns exit 0 with an EMPTY stream when many spawns are
+  // in flight at once (doctor's parallel fan-out), while the same command
+  // standalone prints fine in ~300ms. The old code read that empty stream as
+  // "Not found" and red-flagged Node/Git/hooksPath. A version/config probe is
+  // idempotent, so quiet retries distinguish the lost stream from a tool that
+  // genuinely fails. Contract: every caller here runs an IDEMPOTENT probe
+  // (`--version`, `config --get`, `rev-parse`) — a future side-effecting call
+  // site must pass { attempts: 1 } to opt out of the retry below. The option
+  // is consumed here and never forwarded to exec.
+  // Scope note: only the exit-0-with-empty-stream shape is retried. A probe
+  // that exits non-zero is a REAL failure verdict (cmd.exe reports a missing
+  // tool as exit 1 + "'x' is not recognized"), and re-running it would only
+  // burn time, so that path still returns null immediately.
+  const { attempts, ...execOpts } = opts;
+  const maxAttempts = process.platform === 'win32' ? (attempts || 3) : 1;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const { stdout, stderr } = await execAsync(cmd, {
+        ...execOpts,
+        timeout: execOpts.timeout || EXEC_TIMEOUT_MS,
+      });
+      if (!stdout.trim() && !stderr.trim()) {
+        // Exit-0-but-empty: nothing usable came back. Retry while attempts
+        // remain; report null once they are exhausted, so every caller's
+        // existing null check ("probe produced nothing") applies — an empty
+        // non-null result would read as a present tool with no version.
+        if (attempt + 1 < maxAttempts) {
+          await new Promise(resolve => setTimeout(resolve, 50));
+          continue;
+        }
+        return null;
+      }
+      return { stdout: stdout.trim(), stderr: stderr.trim() };
+    } catch (err) {
+      // #525: a bare null here reads as "tool missing" and has already cost a
+      // misdiagnosis round. Name the sandbox once when it is the sandbox.
+      noteSandboxAttribution(err);
+      return null;
+    }
   }
+  // Exhausted all attempts with exit-0-but-empty streams: report null so every
+  // caller's existing null check ("probe produced nothing usable") applies —
+  // an empty non-null result would read as a present tool with no version.
+  return null;
 }
 
 /**

package/lib/gate-runner.js

@@ -18,15 +18,22 @@ const path = require('node:path');
  * behaves exactly as it does inside the commit hook.
  */
 function runGateAdapter(scriptPath, cwd = process.cwd()) {
+  let bashCommand = 'bash';
   if (process.platform === 'win32') {
-    try {
-      execSync('bash --version', { stdio: 'pipe', timeout: 5000 });
-    } catch {
+    // PATH may lead with the WSL System32 stub, which cannot run these hooks
+    // (Linux filesystem view, and `-c` scripts receive an empty $1 through it).
+    // checkBash probes for an MSYS/MINGW bash that round-trips argv correctly.
+    const { checkBash } = require('./detect-deps.js');
+    const bash = checkBash();
+    if (!bash.ok) {
       console.log('⚠️  This gate requires bash to run shell scripts.');
-      console.log('   On Windows, install Git for Windows (includes Git Bash) or enable WSL.');
+      // No WSL suggestion: these hooks need Git Bash specifically — the WSL
+      // bash is rejected by the probe above (Linux filesystem view, dropped $1).
+      console.log('   On Windows, install Git for Windows (https://git-scm.com/download/win).');
       console.log('   Alternatively, install the required tool directly and run the gate again.');
       return;
     }
+    bashCommand = bash.path;
   }
   const scriptDir = path.dirname(scriptPath);
   const commonScript = [
@@ -62,7 +69,7 @@ function runGateAdapter(scriptPath, cwd = process.cwd()) {
   // execFileSync avoids an extra /bin/sh layer, so bash receives the script as a
   // single argv arg (no shell-metacharacter injection through the path).
   execFileSync(
-    'bash',
+    bashCommand,
     ['--noprofile', '--norc', '-c', wrap, 'xp-gate', commonScript, nowMsScript, scriptPath, process.execPath],
     { stdio: 'inherit', cwd }
   );

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-16T00:33:22.006Z",
+  "checked_at": "2026-10-16T16:19:41.473Z",
   "source": "network"
 }

package/lib/sprint-status.js

@@ -345,8 +345,11 @@ async function handleSprintStatus(args = []) {
 
   if (dirIdx >= 0 && dirIdx + 1 < args.length) {
     searchDir = path.resolve(args[dirIdx + 1]);
-    // Path traversal protection: must be under cwd
-    if (!searchDir.startsWith(process.cwd())) {
+    // Path traversal protection: must be under cwd. Use path.relative instead
+    // of a prefix match so a sibling like `<cwd>2` cannot bypass the check
+    // (#392-#5).
+    const rel = path.relative(process.cwd(), searchDir);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
       console.error('Error: --dir path must be under current working directory');
       return 1;
     }