@boyingliu01/xp-gate 0.27.0 → 0.27.2

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__/sprint-audit.test.js

@@ -1,207 +1,207 @@
-/**
- * Tests for sprint-audit CLI command (Layer 2)
- * @test REQ-338 Sprint audit — final completeness check
- * @intent Verify sprint-audit correctly checks phase coverage, artifacts, consistency
- * @covers AC-AUDIT-01 (SKIP when no sprint-state.json)
- * @covers AC-AUDIT-02 (PASS when 6/6 completed)
- * @covers AC-AUDIT-03 (PASS_WITH_WARNINGS when 4-5/6 completed)
- * @covers AC-AUDIT-04 (FAIL when <4/6 completed)
- * @covers AC-AUDIT-05 (FAIL on state inconsistency)
- * @covers AC-AUDIT-06 (--json flag outputs JSON)
- * @covers AC-AUDIT-07 (report persisted to audit-report.json)
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { handleSprintAudit } from '../sprint-audit.js';
-
-describe('sprint-audit', () => {
-  let tmpDir;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-audit-test-'));
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  function writeState(state) {
-    const stateDir = path.join(tmpDir, '.sprint-state');
-    fs.mkdirSync(stateDir, { recursive: true });
-    fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), JSON.stringify(state));
-  }
-
-  function makeState(overrides = {}) {
-    return {
-      _schema_version: 1,
-      id: 'sprint-test-audit',
-      task_description: 'Test audit feature',
-      phase: 6,
-      status: 'completed',
-      started_at: '2026-07-22T10:00:00Z',
-      phase_history: [],
-      isolation: { branch: 'sprint/test-audit', worktree_path: null },
-      outputs: {},
-      ...overrides,
-    };
-  }
-
-  function makePhaseHistory(completedPhases) {
-    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
-    return completedPhases.map((p, i) => ({
-      phase: p,
-      phase_name: phaseNames[p - 1],
-      status: 'completed',
-      started_at: `2026-07-22T10:${String(i).padStart(2, '0')}:00Z`,
-      completed_at: `2026-07-22T10:${String(i).padStart(2, '0')}:30Z`,
-      duration_seconds: 30,
-    }));
-  }
-
-  describe('handleSprintAudit()', () => {
-    it('returns 0 and shows help with --help', async () => {
-      const code = await handleSprintAudit(['--help']);
-      expect(code).toBe(0);
-    });
-
-    it('returns SKIP (exit 0) when no sprint-state.json exists', async () => {
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('No sprint-state.json'));
-      logSpy.mockRestore();
-    });
-
-    it('returns PASS when 6/6 phases completed', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      // Check output contains PASS
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('PASS');
-      expect(output).toContain('6/6');
-      logSpy.mockRestore();
-    });
-
-    it('returns PASS_WITH_WARNINGS when 5/6 completed', async () => {
-      writeState(makeState({ phase: 5, phase_history: makePhaseHistory([1, 2, 3, 4, 5]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('PASS_WITH_WARNINGS');
-      logSpy.mockRestore();
-    });
-
-    it('returns PASS_WITH_WARNINGS when 4/6 completed', async () => {
-      writeState(makeState({ phase: 4, phase_history: makePhaseHistory([1, 2, 3, 4]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('PASS_WITH_WARNINGS');
-      logSpy.mockRestore();
-    });
-
-    it('returns FAIL when <4/6 completed', async () => {
-      writeState(makeState({ phase: 3, phase_history: makePhaseHistory([1, 2, 3]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(1);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('FAIL');
-      logSpy.mockRestore();
-    });
-
-    it('returns FAIL on state inconsistency (phase vs phase_history)', async () => {
-      const history = makePhaseHistory([1, 2, 3, 4, 5, 6]);
-      writeState(makeState({ phase: 3, phase_history: history })); // phase=3 but last entry is 6
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(1);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('State inconsistency');
-      logSpy.mockRestore();
-    });
-
-    it('outputs JSON when --json flag is set', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      const result = JSON.parse(output);
-      expect(result.verdict).toBe('PASS');
-      expect(result.coverage.completed).toBe(6);
-      logSpy.mockRestore();
-    });
-
-    it('counts skipped phases as completed in coverage', async () => {
-      const history = makePhaseHistory([1, 2, 3, 4, 5]);
-      history.push({
-        phase: 6, phase_name: 'CLOSE', status: 'skipped',
-        started_at: '2026-07-22T10:05:00Z', completed_at: '2026-07-22T10:05:00Z', duration_seconds: 0,
-      });
-      writeState(makeState({ phase: 6, phase_history: history }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      const result = JSON.parse(output);
-      expect(result.coverage.completed).toBe(6);
-      expect(result.verdict).toBe('PASS');
-      logSpy.mockRestore();
-    });
-
-    it('warns about missing summary files for completed phases', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-      // No phase-outputs directory → all summaries missing
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      const result = JSON.parse(output);
-      expect(result.warnings.length).toBeGreaterThan(0);
-      expect(result.warnings.some(w => w.includes('summary missing'))).toBe(true);
-      logSpy.mockRestore();
-    });
-
-    it('persists audit report to audit-report.json', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      await handleSprintAudit(['--dir', tmpDir]);
-      logSpy.mockRestore();
-
-      const reportPath = path.join(tmpDir, '.sprint-state', 'audit-report.json');
-      expect(fs.existsSync(reportPath)).toBe(true);
-      const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
-      expect(report.verdict).toBe('PASS');
-      expect(report.sprint_id).toBe('sprint-test-audit');
-    });
-
-    it('handles corrupted sprint-state.json gracefully', async () => {
-      const stateDir = path.join(tmpDir, '.sprint-state');
-      fs.mkdirSync(stateDir, { recursive: true });
-      fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), 'not-valid-json');
-
-      const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(1);
-      expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse'));
-      errSpy.mockRestore();
-    });
-  });
-});
+/**
+ * Tests for sprint-audit CLI command (Layer 2)
+ * @test REQ-338 Sprint audit — final completeness check
+ * @intent Verify sprint-audit correctly checks phase coverage, artifacts, consistency
+ * @covers AC-AUDIT-01 (SKIP when no sprint-state.json)
+ * @covers AC-AUDIT-02 (PASS when 6/6 completed)
+ * @covers AC-AUDIT-03 (PASS_WITH_WARNINGS when 4-5/6 completed)
+ * @covers AC-AUDIT-04 (FAIL when <4/6 completed)
+ * @covers AC-AUDIT-05 (FAIL on state inconsistency)
+ * @covers AC-AUDIT-06 (--json flag outputs JSON)
+ * @covers AC-AUDIT-07 (report persisted to audit-report.json)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { handleSprintAudit } from '../sprint-audit.js';
+
+describe('sprint-audit', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-audit-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeState(state) {
+    const stateDir = path.join(tmpDir, '.sprint-state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), JSON.stringify(state));
+  }
+
+  function makeState(overrides = {}) {
+    return {
+      _schema_version: 1,
+      id: 'sprint-test-audit',
+      task_description: 'Test audit feature',
+      phase: 6,
+      status: 'completed',
+      started_at: '2026-07-22T10:00:00Z',
+      phase_history: [],
+      isolation: { branch: 'sprint/test-audit', worktree_path: null },
+      outputs: {},
+      ...overrides,
+    };
+  }
+
+  function makePhaseHistory(completedPhases) {
+    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+    return completedPhases.map((p, i) => ({
+      phase: p,
+      phase_name: phaseNames[p - 1],
+      status: 'completed',
+      started_at: `2026-07-22T10:${String(i).padStart(2, '0')}:00Z`,
+      completed_at: `2026-07-22T10:${String(i).padStart(2, '0')}:30Z`,
+      duration_seconds: 30,
+    }));
+  }
+
+  describe('handleSprintAudit()', () => {
+    it('returns 0 and shows help with --help', async () => {
+      const code = await handleSprintAudit(['--help']);
+      expect(code).toBe(0);
+    });
+
+    it('returns SKIP (exit 0) when no sprint-state.json exists', async () => {
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('No sprint-state.json'));
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS when 6/6 phases completed', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      // Check output contains PASS
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS');
+      expect(output).toContain('6/6');
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS_WITH_WARNINGS when 5/6 completed', async () => {
+      writeState(makeState({ phase: 5, phase_history: makePhaseHistory([1, 2, 3, 4, 5]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS_WITH_WARNINGS');
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS_WITH_WARNINGS when 4/6 completed', async () => {
+      writeState(makeState({ phase: 4, phase_history: makePhaseHistory([1, 2, 3, 4]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS_WITH_WARNINGS');
+      logSpy.mockRestore();
+    });
+
+    it('returns FAIL when <4/6 completed', async () => {
+      writeState(makeState({ phase: 3, phase_history: makePhaseHistory([1, 2, 3]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('FAIL');
+      logSpy.mockRestore();
+    });
+
+    it('returns FAIL on state inconsistency (phase vs phase_history)', async () => {
+      const history = makePhaseHistory([1, 2, 3, 4, 5, 6]);
+      writeState(makeState({ phase: 3, phase_history: history })); // phase=3 but last entry is 6
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('State inconsistency');
+      logSpy.mockRestore();
+    });
+
+    it('outputs JSON when --json flag is set', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.verdict).toBe('PASS');
+      expect(result.coverage.completed).toBe(6);
+      logSpy.mockRestore();
+    });
+
+    it('counts skipped phases as completed in coverage', async () => {
+      const history = makePhaseHistory([1, 2, 3, 4, 5]);
+      history.push({
+        phase: 6, phase_name: 'CLOSE', status: 'skipped',
+        started_at: '2026-07-22T10:05:00Z', completed_at: '2026-07-22T10:05:00Z', duration_seconds: 0,
+      });
+      writeState(makeState({ phase: 6, phase_history: history }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.coverage.completed).toBe(6);
+      expect(result.verdict).toBe('PASS');
+      logSpy.mockRestore();
+    });
+
+    it('warns about missing summary files for completed phases', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+      // No phase-outputs directory → all summaries missing
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.warnings.length).toBeGreaterThan(0);
+      expect(result.warnings.some(w => w.includes('summary missing'))).toBe(true);
+      logSpy.mockRestore();
+    });
+
+    it('persists audit report to audit-report.json', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      await handleSprintAudit(['--dir', tmpDir]);
+      logSpy.mockRestore();
+
+      const reportPath = path.join(tmpDir, '.sprint-state', 'audit-report.json');
+      expect(fs.existsSync(reportPath)).toBe(true);
+      const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+      expect(report.verdict).toBe('PASS');
+      expect(report.sprint_id).toBe('sprint-test-audit');
+    });
+
+    it('handles corrupted sprint-state.json gracefully', async () => {
+      const stateDir = path.join(tmpDir, '.sprint-state');
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), 'not-valid-json');
+
+      const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse'));
+      errSpy.mockRestore();
+    });
+  });
+});

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

@@ -6,10 +6,10 @@
  *         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
+ * @covers AC-WINBASH-01, AC-WINBASH-02
  */
 const { describe, it, expect } = await import('vitest');
-const { resolveWindowsBashCandidates } = require('../detect-deps.js');
+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
@@ -39,10 +39,12 @@ function fakeSpawn(behaviors) {
 
 describe('resolveWindowsBashCandidates (win32 authoritative bash)', () => {
   it('AC-WINBASH-01: rejects a WSL stub whose $1 is empty and uname is Linux', () => {
-    const spawn = fakeSpawn({ 'C:\\Windows\\System32\\bash.exe': '[ ]\nLinux\n' });
-    // No MSYS candidate exists in this world (hardcoded fallbacks report no
-    // stdout), so the resolver must find nothing rather than settle for the stub.
-    expect(resolveWindowsBashCandidates(spawn, fakeWhere('C:\\Windows\\System32\\bash.exe\r\n'))).toBeNull();
+    // 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', () => {
@@ -52,7 +54,24 @@ describe('resolveWindowsBashCandidates (win32 authoritative bash)', () => {
     });
     const result = resolveWindowsBashCandidates(spawn, fakeWhere('C:\\a\\bash.exe\r\nC:\\b\\bash.exe\r\n'));
     expect(result).toBe('C:\\b\\bash.exe');
-    expect(spawn.probed.slice(0, 2)).toEqual(['C:\\a\\bash.exe', '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', () => {
@@ -70,4 +89,35 @@ describe('resolveWindowsBashCandidates (win32 authoritative bash)', () => {
     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');
+  });
 });