@opengsd/gsd-pi 1.2.0-dev.84c56d87 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/tests/exec-graceful-kill.test.ts

@@ -0,0 +1,193 @@
+// Project/App: gsd-pi
+// File Purpose: Deterministic timing tests for the exec-sandbox graceful-kill
+// ladder + hard-deadline force-resolve (S04/T02).
+//
+// T01 extended runExecSandbox's timeout path to a graceful
+// SIGTERM -> grace -> SIGKILL ladder (via killProcessTree) plus a caller-side
+// force-resolve hard deadline so a non-closing ("D-state") child can never hang
+// the awaiting promise. A true D-state child is non-portable, so we simulate the
+// exact symptom deterministically:
+//   1. A SIGTERM-cooperative child (trap 'exit 0' TERM) closes promptly on the
+//      first SIGTERM — proving the ladder resolves via `close` well before the
+//      force-resolve deadline.
+//   2. A SIGTERM-ignoring (trap '' TERM) child combined with a LARGE
+//      kill_grace_ms (so SIGKILL never fires in-window) and a SHORT
+//      force_resolve_delay_ms — the only way the promise can settle is the
+//      hard deadline, proving the no-hang guarantee.
+//
+// Unlike the sync bash path (which throws on force-resolve), runExecSandbox
+// always RESOLVES; force-resolve calls finalize(null, "SIGKILL") and preserves
+// timed_out === true so the agent can still distinguish a graceful timeout exit
+// from a forced kill.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { EXEC_DEFAULTS, runExecSandbox, type ExecSandboxOptions } from '../exec-sandbox.ts';
+
+const isWin = process.platform === 'win32';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-exec-gracekill-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function baseOpts(base: string, overrides: Partial<ExecSandboxOptions> = {}): ExecSandboxOptions {
+  return {
+    baseDir: base,
+    clamp_timeout_ms: EXEC_DEFAULTS.clampTimeoutMs,
+    default_timeout_ms: 10_000,
+    stdout_cap_bytes: 1_024,
+    stderr_cap_bytes: 1_024,
+    digest_chars: 120,
+    env_allowlist: EXEC_DEFAULTS.envAllowlist,
+    ...overrides,
+  };
+}
+
+// Wall-clock guard: reject if the call has not settled by `ms`. Proves no-hang
+// independently of the assertions on timing/markers.
+function wallClockGuard<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      const t = setTimeout(() => reject(new Error(`Call did not settle within ${ms}ms (hang)`)), ms);
+      if (typeof t === 'object' && 'unref' in t) t.unref();
+    }),
+  ]);
+}
+
+// Clean up a detached child (and its process group) that a large kill_grace_ms
+// intentionally leaves alive past the force-resolve deadline.
+function cleanupByPidFile(pidFile: string): void {
+  if (!existsSync(pidFile)) return;
+  const pid = Number.parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+  if (!Number.isFinite(pid) || pid <= 0) return;
+  if (isWin) return; // best-effort; test is skipped on win32
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // already gone
+    }
+  }
+}
+
+test(
+  'runExecSandbox: SIGTERM-cooperative child exits promptly within grace on timeout',
+  { skip: isWin ? 'Unix-primary graceful semantics' : false, timeout: 20_000 },
+  async (t) => {
+    const base = freshBase();
+    t.after(() => cleanup(base));
+
+    const KILL_GRACE_MS = 5_000;
+    const FORCE_RESOLVE_DELAY_MS = 8_000; // grace + hard-deadline; must NOT be reached
+    const TIMEOUT_MS = 300;
+
+    // Child traps SIGTERM and exits 0, then sleeps long. The first SIGTERM from
+    // the ladder ends it immediately -> `close` fires -> finalize via close,
+    // well before the force-resolve deadline.
+    const script = `trap 'exit 0' TERM; sleep 30`;
+
+    const result = await wallClockGuard(
+      runExecSandbox(
+        { runtime: 'bash', script, timeout_ms: TIMEOUT_MS },
+        baseOpts(base, {
+          kill_grace_ms: KILL_GRACE_MS,
+          force_resolve_delay_ms: FORCE_RESOLVE_DELAY_MS,
+        }),
+      ),
+      15_000,
+    );
+
+    // timed_out is preserved even though the child exited cooperatively.
+    assert.equal(result.timed_out, true, 'timeout fired so timed_out must be true');
+    // Proves SIGTERM (close) resolved it, NOT the force-resolve deadline:
+    // a force-resolve would land at ~TIMEOUT_MS + FORCE_RESOLVE_DELAY_MS (~8.3s).
+    assert.ok(
+      result.duration_ms < KILL_GRACE_MS,
+      `expected prompt close well under grace (${KILL_GRACE_MS}ms), got ${result.duration_ms}ms`,
+    );
+    // A clean SIGTERM-trapped exit resolves via `close` with an exit code,
+    // not the force-resolve sentinel (exit_code null / signal SIGKILL).
+    assert.notEqual(
+      result.signal,
+      'SIGKILL',
+      'cooperative child must not be force-resolved as SIGKILL',
+    );
+    assert.equal(result.force_resolved, false, 'a cooperative close must not be flagged as force-resolved');
+  },
+);
+
+test(
+  'runExecSandbox: SIGTERM-ignoring (non-closing) child force-resolves via hard deadline without hanging',
+  { skip: isWin ? 'Unix-primary graceful semantics; force-resolve covered on POSIX' : false, timeout: 20_000 },
+  async (t) => {
+    const base = freshBase();
+    const pidFile = join(base, 'child.pid');
+    t.after(() => {
+      cleanupByPidFile(pidFile);
+      cleanup(base);
+    });
+
+    // Timing seams: SIGKILL never fires in-window (grace huge), so the only way
+    // the promise can settle is the hard deadline -> proves the caller-side
+    // force-resolve.
+    const KILL_GRACE_MS = 30_000;
+    const FORCE_RESOLVE_DELAY_MS = 800;
+    // Generous timeout so the SIGTERM trap is reliably installed before the kill
+    // fires, even under heavy parallel test load. A too-tight timeout can race
+    // the shell's startup: the kill lands before `trap '' TERM` runs, SIGTERM
+    // takes its default action, the child closes on SIGTERM, and the
+    // force-resolve path never runs (flaky 'SIGTERM' instead of 'SIGKILL').
+    const TIMEOUT_MS = 1_500;
+
+    // Install the SIGTERM trap FIRST (before any other command) so the shell is
+    // already immune by the time the kill fires; then record the detached
+    // shell's PID (process-group leader) for cleanup. The shell loops forever
+    // holding its stdout pipe open -> `close` never fires in-window -> the
+    // caller's hard deadline must force-resolve.
+    const script = `trap '' TERM; echo $$ > '${pidFile}'; while true; do sleep 1; done`;
+
+    const start = Date.now();
+    const result = await wallClockGuard(
+      runExecSandbox(
+        { runtime: 'bash', script, timeout_ms: TIMEOUT_MS },
+        baseOpts(base, {
+          kill_grace_ms: KILL_GRACE_MS,
+          force_resolve_delay_ms: FORCE_RESOLVE_DELAY_MS,
+        }),
+      ),
+      8_000,
+    );
+    const elapsed = Date.now() - start;
+
+    // (a) Did not hang and settled well before the SIGKILL grace would fire.
+    assert.ok(
+      elapsed < KILL_GRACE_MS,
+      `expected force-resolve before SIGKILL grace (${KILL_GRACE_MS}ms), took ${elapsed}ms`,
+    );
+    // (b) Settled in the force-resolve band: >= timeout (kill initiated) and
+    //     roughly timeout + force_resolve_delay (generous CI slack, but kept below
+    //     the 8000ms wallClockGuard so the upper bound is actually reachable).
+    assert.ok(
+      elapsed >= TIMEOUT_MS && elapsed <= TIMEOUT_MS + FORCE_RESOLVE_DELAY_MS + 4_000,
+      `expected settle near ${TIMEOUT_MS + FORCE_RESOLVE_DELAY_MS}ms, took ${elapsed}ms`,
+    );
+    // (c) Force-resolve preserves timed_out and surfaces the SIGKILL sentinel
+    //     (exit_code null) plus the explicit force_resolved flag, so the agent can
+    //     tell a forced kill (D-state hard deadline) from a clean SIGKILL exit.
+    assert.equal(result.timed_out, true, 'force-resolve must preserve timed_out');
+    assert.equal(result.exit_code, null, 'force-resolve exit_code must be null');
+    assert.equal(result.signal, 'SIGKILL', 'force-resolve must mark signal SIGKILL');
+    assert.equal(result.force_resolved, true, 'force-resolve must set force_resolved=true');
+  },
+);

package/src/resources/extensions/gsd/tests/exec-tool.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import { registerExecTools } from "../bootstrap/exec-tools.ts";
-import { executeUatExec } from "../tools/exec-tool.ts";
+import { executeGsdExec, executeUatExec } from "../tools/exec-tool.ts";
 import type { ExecSandboxRequest, ExecSandboxResult } from "../exec-sandbox.ts";
 
 function makeExecResult(request: ExecSandboxRequest): ExecSandboxResult {
@@ -12,6 +12,7 @@ function makeExecResult(request: ExecSandboxRequest): ExecSandboxResult {
     exit_code: 0,
     signal: null,
     timed_out: false,
+    force_resolved: false,
     duration_ms: 1,
     stdout_bytes: 12,
     stderr_bytes: 0,
@@ -51,6 +52,33 @@ test("executeUatExec accepts evidence-mode aliases for intent", async () => {
   assert.equal(requests[0]?.metadata?.intent, "uat-artifact-check");
 });
 
+test("gsd_exec surfaces a force-resolved (D-state) kill distinctly from a clean exit", async () => {
+  // A hard-deadline force-resolve sets force_resolved=true with a synthetic SIGKILL
+  // signal and null exit code. The tool result must carry that flag in details and
+  // render it as exit=timeout(force-killed) so the agent can tell it apart from a
+  // normally-exited or cleanly-timed-out command.
+  const result = await executeGsdExec(
+    { runtime: "bash", script: "sleep 60" },
+    {
+      baseDir: "/tmp/gsd-exec-force-resolved-test",
+      preferences: null,
+      run: async (request) => ({
+        ...makeExecResult(request),
+        exit_code: null,
+        signal: "SIGKILL",
+        timed_out: true,
+        force_resolved: true,
+        digest: "[no stdout \u2014 timed out]",
+      }),
+    },
+  );
+
+  assert.equal(result.isError, true, "a force-resolved kill is an error result");
+  assert.equal(result.details?.force_resolved, true, "details must expose force_resolved");
+  const text = result.content.map((c) => c.text ?? "").join("\n");
+  assert.match(text, /exit=timeout\(force-killed\)/, "summary must distinguish a force-killed result");
+});
+
 test("registerExecTools exposes gsd_uat_exec intent as recoverable string schema", () => {
   const tools: Array<{ name: string; parameters: any }> = [];
   registerExecTools({

package/src/resources/extensions/gsd/tests/gsd-command-home.test.ts

@@ -4,10 +4,13 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { buildGsdHomeModel, showGsdHome } from "../gsd-command-home.ts";
+import { buildIdleMenuSummary, detectIdleMilestoneResidueHint } from "../closeout-wizard.ts";
+import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
 import type { GSDState } from "../types.ts";
 
 function baseState(overrides: Partial<GSDState> = {}): GSDState {
@@ -118,6 +121,123 @@ test("/gsd home recommends start or configure after all milestones complete", ()
   assert.match(model.summary.join("\n"), /All milestones complete/);
 });
 
+test("/gsd home recommends fix or recover when milestone git residue is stranded", () => {
+  const model = buildGsdHomeModel(baseState({
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: "complete",
+    nextAction: "All milestones complete.",
+  }), {
+    strandedQuick: null,
+    unmergedMilestones: [],
+    idleResidueHint: {
+      milestoneIds: ["M008"],
+      message:
+        "Stranded milestone git residue detected (M008: worktree dir and/or milestone/* branch). " +
+        "Run /gsd dispatch complete-milestone M008 or /gsd status to recover closeout before starting new work.",
+    },
+  });
+
+  assert.equal(action(model, "fix_recover").recommended, true);
+  assert.equal(action(model, "fix_recover").enabled, true);
+  assert.match(model.summary[0], /Stranded milestone git residue/);
+  assert.equal(action(model, "continue_step").enabled, false);
+});
+
+test("detectIdleMilestoneResidueHint reports missing workflow database in a git repo", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-"));
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+    const hint = detectIdleMilestoneResidueHint(base);
+    assert.ok(hint);
+    assert.match(hint!.message, /\.gsd\/gsd\.db/);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("detectIdleMilestoneResidueHint matches unique-format milestone ids (M###-abc123)", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-unique-"));
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd-worktrees", "M042-abc123"), { recursive: true });
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    try {
+      // Closed milestone with lingering worktree dir — classic residue.
+      insertMilestone({ id: "M042-abc123", title: "Closed Unique", status: "complete" });
+      const hint = detectIdleMilestoneResidueHint(base);
+      assert.ok(hint, "unique-format closed milestone with worktree should be detected");
+      assert.deepEqual(hint!.milestoneIds, ["M042-abc123"]);
+      assert.match(hint!.message, /M042-abc123/);
+    } finally {
+      closeDatabase();
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("detectIdleMilestoneResidueHint ignores in-flight milestones with worktree artifacts", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-home-residue-active-"));
+  try {
+    execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd-worktrees", "M001"), { recursive: true });
+    mkdirSync(join(base, ".gsd-worktrees", "M002-abc123"), { recursive: true });
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    try {
+      // Active and pending milestones must not be flagged as stranded residue.
+      insertMilestone({ id: "M001", title: "Active milestone", status: "active" });
+      insertMilestone({ id: "M002-abc123", title: "Pending milestone", status: "pending" });
+      const hint = detectIdleMilestoneResidueHint(base);
+      assert.equal(hint, null, "active/pending milestone worktrees must not be classified as residue");
+    } finally {
+      closeDatabase();
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("buildIdleMenuSummary surfaces idle residue hint even when phase is complete", () => {
+  const summary = buildIdleMenuSummary(
+    {
+      activeMilestone: null,
+      activeSlice: null,
+      activeTask: null,
+      phase: "complete",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: "All milestones complete.",
+      lastCompletedMilestone: { id: "M001", title: "Menu Cleanup" },
+      registry: [{ id: "M001", title: "Menu Cleanup", status: "complete" }],
+      requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+      progress: {
+        milestones: { done: 1, total: 1 },
+        slices: { done: 0, total: 0 },
+        tasks: { done: 0, total: 0 },
+      },
+    },
+    {
+      strandedQuick: null,
+      unmergedMilestones: [],
+      idleResidueHint: {
+        milestoneIds: ["M008"],
+        message:
+          "Stranded milestone git residue detected (M008: worktree dir and/or milestone/* branch). " +
+          "Run /gsd dispatch complete-milestone M008 or /gsd status to recover closeout before starting new work.",
+      },
+    },
+  );
+
+  assert.match(summary[0] ?? "", /Stranded milestone git residue/);
+  assert.doesNotMatch(summary.join("\n"), /All milestones complete/);
+});
+
 test("showGsdHome renders the five-slot home text without an interactive TUI", async () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-home-"));
   const notifications: Array<{ message: string; level: string }> = [];

package/src/resources/extensions/gsd/tests/gsd-db.test.ts

@@ -30,6 +30,8 @@ import {
   insertTask,
   getTask,
   getSliceTasks,
+  getMilestoneSliceSummaries,
+  getClosedSliceIds,
   getActiveMilestoneFromDb,
   deleteMilestone,
   clearEngineHierarchy,
@@ -947,6 +949,31 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  test('gsd-db: slice summaries use the canonical closed vocabulary; getClosedSliceIds filters to closed ids', () => {
+    openDatabase(':memory:');
+    insertMilestone({ id: 'M001', status: 'active' });
+    insertSlice({ milestoneId: 'M001', id: 'S01', title: 'Complete', status: 'complete', depends: [], sequence: 1 });
+    insertSlice({ milestoneId: 'M001', id: 'S02', title: 'Done', status: 'done', depends: ['S01'], sequence: 2 });
+    insertSlice({ milestoneId: 'M001', id: 'S03', title: 'Skipped', status: 'skipped', depends: [], sequence: 3 });
+    insertSlice({ milestoneId: 'M001', id: 'S04', title: 'Closed', status: 'closed', depends: [], sequence: 4 });
+    insertSlice({ milestoneId: 'M001', id: 'S05', title: 'Active', status: 'active', depends: [], sequence: 5 });
+    insertSlice({ milestoneId: 'M001', id: 'S06', title: 'Pending', status: 'pending', depends: ['S05'], sequence: 6 });
+
+    const summaries = getMilestoneSliceSummaries('M001');
+    assert.deepStrictEqual(summaries[0], { id: 'S01', title: 'Complete', done: true, depends: [] });
+    assert.deepStrictEqual(summaries[5], { id: 'S06', title: 'Pending', done: false, depends: ['S05'] });
+    assert.deepStrictEqual(
+      summaries.map((s) => s.done),
+      [true, true, true, true, false, false],
+      'complete/done/skipped/closed are closed; active/pending are not',
+    );
+
+    assert.deepStrictEqual(getClosedSliceIds('M001'), ['S01', 'S02', 'S03', 'S04']);
+    assert.deepStrictEqual(getClosedSliceIds('M999'), [], 'unknown milestone yields no closed ids');
+
+    closeDatabase();
+  });
+
   test('gsd-db: FTS5 unavailable warning normalizes provider typo', () => {
     const previousStderr = setStderrLoggingEnabled(false);
     _resetLogs();

package/src/resources/extensions/gsd/tests/guidance.test.ts

@@ -10,6 +10,8 @@ import {
   recoveryRemediation,
   needsAttentionBlockerGuidance,
   needsRemediationBlockerGuidance,
+  uatSignoffBlockerGuidance,
+  worktreeCreationFailedGuidance,
   crashResumeHint,
   doctorFixHint,
   type RecoveryGuidanceKey,
@@ -95,6 +97,27 @@ describe("milestone blocker guidance", () => {
     assert.match(text, /\/gsd status/);
     assert.match(text, /\/gsd validate-milestone/);
   });
+
+  test("UAT sign-off guidance explains direct dispatch target", () => {
+    const missing = uatSignoffBlockerGuidance("M007", "S02");
+    const failing = uatSignoffBlockerGuidance("M007", "S02", "FAIL");
+
+    for (const text of [missing, failing]) {
+      assert.match(text, /Manual UAT sign-off \(PASS\) is required before milestone closure/);
+      assert.match(text, /\/gsd dispatch uat/);
+      assert.match(text, /most recently completed slice/);
+      assert.match(text, /re-run UAT for S02/);
+      assert.match(text, /gsd_uat_result_save/);
+    }
+  });
+
+  test("worktree creation failure guidance does not claim bootstrap continues", () => {
+    const text = worktreeCreationFailedGuidance("M007", "boom");
+
+    assert.match(text, /Auto-worktree creation for M007 failed: boom\. Continuing in project root\./);
+    assert.match(text, /Worktree isolation is degraded for this session\./);
+    assert.doesNotMatch(text, /work continues in the project root/i);
+  });
 });
 
 describe("crash resume hints", () => {

package/src/resources/extensions/gsd/tests/guided-dispatch-root.test.ts

@@ -11,6 +11,7 @@ import {
   _dispatchWorkflowForTest,
   resolveGuidedDispatchProjectRoot,
 } from "../guided-flow.ts";
+import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.ts";
 
 test("guided dispatch falls back to cwd only when no project root is supplied", () => {
   const cwd = process.cwd();
@@ -77,12 +78,8 @@ test("guided dispatch passes the explicit project root through model and compati
             seen.modelRoot = projectRoot;
             return { routing: null, appliedModel: null };
           },
-          getTransportSupportError: (
-            _provider: string | undefined,
-            _requiredTools: string[],
-            options?: { projectRoot?: string },
-          ) => {
-            seen.compatibilityRoot = options?.projectRoot ?? "";
+          getDispatchReadinessError: (input: { projectRoot?: string }) => {
+            seen.compatibilityRoot = input.projectRoot ?? "";
             return null;
           },
         },
@@ -119,6 +116,7 @@ test("guided dispatch accepts workflow MCP tools absent from parent active tool
       getProviderAuthMode: () => "externalCli",
     },
     ui: {
+      setStatus: () => {},
       notify: (message: string) => {
         notifications.push(message);
       },
@@ -134,8 +132,22 @@ test("guided dispatch accepts workflow MCP tools absent from parent active tool
     "write",
   ];
 
+  // The workflow MCP server registers its tools out of band, so the unit's
+  // required workflow tools show up in the registered tool snapshot
+  // (getAllTools) under the MCP server prefix without ever entering the parent
+  // session's active tool surface (getActiveTools). This is exactly the shape
+  // the readiness gate must accept. Derive the surface from the unit contract
+  // so this test stays correct if discuss-milestone's required tools change.
+  const registeredTools = [
+    ...activeTools,
+    ...getRequiredWorkflowToolsForUnit("discuss-milestone").map(
+      (tool) => `mcp__gsd-workflow__${tool}`,
+    ),
+  ];
+
   const pi = {
     getActiveTools: () => [...activeTools],
+    getAllTools: () => registeredTools.map((name) => ({ name })),
     setActiveTools: (tools: string[]) => {
       activeTools = [...tools];
     },

package/src/resources/extensions/gsd/tests/integration/auto-worktree.test.ts

@@ -134,6 +134,21 @@ describe("auto-worktree lifecycle", () => {
     teardownAutoWorktree(tempDir, "M003");
   });
 
+  test("isInAutoWorktree returns false when ambient cwd was deleted", (t) => {
+    const cwd = t.mock.method(process, "cwd", () => {
+      const err = new Error("process.cwd failed") as NodeJS.ErrnoException;
+      err.code = "ENOENT";
+      err.syscall = "uv_cwd";
+      throw err;
+    });
+
+    try {
+      assert.equal(isInAutoWorktree("/repo"), false);
+    } finally {
+      cwd.mock.restore();
+    }
+  });
+
   test("symlink-resolved auto worktree is detected after module state reset", () => {
     tempDir = createTempRepo();
     const savedGsdHome = process.env.GSD_HOME;

package/src/resources/extensions/gsd/tests/integration/doctor-environment-async.test.ts

@@ -0,0 +1,104 @@
+// Project/App: gsd-pi
+// File Purpose: Verify the non-blocking runEnvironmentChecksAsync is behaviourally
+// identical to the synchronous runEnvironmentChecks (the health-widget render
+// path was moved onto the async variant for performance), and that the single-
+// scan checkPortConflicts still detects a real in-use port.
+
+import test, { type TestContext } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { createServer } from "node:net";
+
+import {
+  runEnvironmentChecks,
+  runEnvironmentChecksAsync,
+  type EnvironmentCheckResult,
+} from "../../doctor-environment.ts";
+
+function makeProject(t: TestContext, files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-env-async-"));
+  t.after(() => {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+  for (const [name, content] of Object.entries(files)) {
+    const filePath = join(dir, name);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content);
+  }
+  return dir;
+}
+
+// Stable, order-independent signature of a check-result set for comparison.
+function normalize(results: EnvironmentCheckResult[]): string[] {
+  return results.map((r) => `${r.name}|${r.status}|${r.message}|${r.detail ?? ""}`).sort();
+}
+
+test("runEnvironmentChecksAsync returns the same results as runEnvironmentChecks", async (t) => {
+  const dir = makeProject(t, {
+    "package.json": JSON.stringify({
+      name: "fixture",
+      engines: { node: ">=18" },
+      scripts: { dev: "vite --port 4321", build: "tsc" },
+      devDependencies: { typescript: "^5.0.0" },
+    }),
+    ".env.example": "API_KEY=\n",
+    Dockerfile: "FROM node:20\n",
+  });
+  mkdirSync(join(dir, "node_modules"), { recursive: true });
+
+  const sync = runEnvironmentChecks(dir);
+  const asyncResults = await runEnvironmentChecksAsync(dir);
+
+  assert.deepEqual(
+    normalize(asyncResults),
+    normalize(sync),
+    "async checks must produce the identical result set as the sync checks",
+  );
+  // Sanity: the fixture is rich enough that the suite actually produced checks.
+  assert.ok(sync.length > 0, "expected the fixture to yield environment checks");
+});
+
+test("runEnvironmentChecksAsync matches sync on a bare directory (no package.json)", async (t) => {
+  const dir = makeProject(t, {});
+  const sync = runEnvironmentChecks(dir);
+  const asyncResults = await runEnvironmentChecksAsync(dir);
+  assert.deepEqual(normalize(asyncResults), normalize(sync));
+});
+
+test(
+  "single-scan port check detects a real in-use port, identically sync and async",
+  { skip: process.platform === "win32" ? "lsof-based port check is macOS/Linux only" : false },
+  async (t) => {
+    // Bind a real listener, then reference its port from package.json scripts so
+    // collectPortsToCheck picks it up. The server stays up across both check runs.
+    const server = createServer();
+    const port = await new Promise<number>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        const addr = server.address();
+        resolve(typeof addr === "object" && addr ? addr.port : 0);
+      });
+    });
+    t.after(() => new Promise<void>((resolve) => server.close(() => resolve())));
+    assert.ok(port >= 1024 && port <= 65535, "ephemeral port should be in the checked range");
+
+    const dir = makeProject(t, {
+      "package.json": JSON.stringify({ name: "fixture", scripts: { dev: `serve --port ${port}` } }),
+    });
+
+    const syncConflicts = runEnvironmentChecks(dir).filter((r) => r.name === "port_conflict");
+    const asyncConflicts = (await runEnvironmentChecksAsync(dir)).filter((r) => r.name === "port_conflict");
+
+    // Equivalence holds regardless of whether lsof is present on the runner.
+    assert.deepEqual(normalize(asyncConflicts), normalize(syncConflicts), "sync and async must agree on port conflicts");
+    // On macOS/Linux lsof is standard, so the listener must be reported and named.
+    assert.equal(syncConflicts.length, 1, "expected exactly one port conflict for the in-use port");
+    assert.match(syncConflicts[0]!.message, new RegExp(`\\b${port}\\b`), "conflict message must name the in-use port");
+  },
+);