@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

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

@@ -0,0 +1,148 @@
+// GSD Extension — Guidance module tests
+// The catalog is the test surface: every typed finding must resolve to
+// non-empty remediation, and load-bearing phrases must survive edits.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  formatGuidance,
+  recoveryRemediation,
+  needsAttentionBlockerGuidance,
+  needsRemediationBlockerGuidance,
+  uatSignoffBlockerGuidance,
+  worktreeCreationFailedGuidance,
+  crashResumeHint,
+  doctorFixHint,
+  type RecoveryGuidanceKey,
+} from "../guidance.js";
+import { classifyFailure, type RecoveryFailureKind } from "../recovery-classification.js";
+import { isValidationBlockedState } from "../validation-block-guard.js";
+import type { GSDState } from "../types.js";
+
+const RECOVERY_KEYS: RecoveryGuidanceKey[] = [
+  "tool-schema",
+  "tool-contract",
+  "tool-unavailable",
+  "deterministic-policy",
+  "lifecycle-progression",
+  "stale-worker",
+  "worktree-invalid",
+  "verification-drift",
+  "reconciliation-drift",
+  "illegal-transition",
+  "runtime-unknown",
+  "provider-transient",
+  "provider-permanent",
+];
+
+describe("guidance catalog", () => {
+  test("every recovery guidance key resolves to non-empty remediation", () => {
+    for (const key of RECOVERY_KEYS) {
+      const remediation = recoveryRemediation(key);
+      assert.ok(remediation.length > 0, `empty remediation for ${key}`);
+    }
+  });
+
+  test("classifyFailure carries catalog remediation for every failure kind", () => {
+    const kinds: RecoveryFailureKind[] = [
+      "tool-schema",
+      "tool-contract",
+      "deterministic-policy",
+      "lifecycle-progression",
+      "stale-worker",
+      "worktree-invalid",
+      "verification-drift",
+      "reconciliation-drift",
+      "runtime-unknown",
+    ];
+    for (const kind of kinds) {
+      const result = classifyFailure({ error: new Error("boom"), failureKind: kind });
+      assert.equal(result.failureKind, kind);
+      assert.equal(result.exitReason, kind);
+      assert.ok(result.remediation.length > 0, `empty remediation for ${kind}`);
+    }
+  });
+
+  test("escalation kinds with weak guidance now name a concrete command", () => {
+    for (const key of ["stale-worker", "worktree-invalid", "verification-drift", "reconciliation-drift"] as const) {
+      assert.match(recoveryRemediation(key), /\/gsd /, `no command in remediation for ${key}`);
+    }
+  });
+
+  test("formatGuidance numbers steps under the summary", () => {
+    const text = formatGuidance({ summary: "It broke.", steps: ["Fix it.", "Retry."] });
+    assert.equal(text, "It broke.\n\n1. Fix it.\n2. Retry.");
+  });
+
+  test("formatGuidance with no steps is just the summary", () => {
+    assert.equal(formatGuidance({ summary: "All good.", steps: [] }), "All good.");
+  });
+});
+
+describe("milestone blocker guidance", () => {
+  test("needs-attention blocker keeps the phrase the validation-block guard matches", () => {
+    const state = { phase: "blocked", blockers: [needsAttentionBlockerGuidance("M005")] } as unknown as GSDState;
+    assert.ok(isValidationBlockedState(state));
+  });
+
+  test("needs-remediation blocker keeps the phrase the validation-block guard matches", () => {
+    const state = { phase: "blocked", blockers: [needsRemediationBlockerGuidance("M005")] } as unknown as GSDState;
+    assert.ok(isValidationBlockedState(state));
+  });
+
+  test("blockers carry the milestone id and concrete fix commands", () => {
+    const text = needsAttentionBlockerGuidance("M007");
+    assert.match(text, /M007/);
+    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", () => {
+  test("bootstrap crash reports no work lost", () => {
+    assert.match(crashResumeHint("starting", "bootstrap") ?? "", /No work was lost/);
+  });
+
+  test("unit classes map to their resume hints", () => {
+    assert.match(crashResumeHint("research-milestone", "M001") ?? "", /may be incomplete/);
+    assert.match(crashResumeHint("execute-task", "T001") ?? "", /completed work is preserved/);
+    assert.match(crashResumeHint("complete-slice", "S001") ?? "", /interrupted/);
+  });
+
+  test("unknown unit types yield no hint", () => {
+    assert.equal(crashResumeHint("triage-captures", "X"), undefined);
+  });
+});
+
+describe("doctor fix hints", () => {
+  test("known codes resolve to a hint", () => {
+    assert.ok(doctorFixHint("stale_crash_lock"));
+    assert.ok(doctorFixHint("db_unavailable"));
+  });
+
+  test("codes without authored guidance resolve to undefined", () => {
+    assert.equal(doctorFixHint("delimiter_in_title"), undefined);
+  });
+});

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-milestone-merge.test.ts

@@ -35,6 +35,7 @@ import {
   insertTask,
   openDatabase,
 } from "../../gsd-db.ts";
+import { createGsdIntegrationProject } from "./gsd-integration-fixture.ts";
 
 function run(cmd: string, cwd: string): string {
   // Safe: all inputs are hardcoded test strings, not user input
@@ -42,17 +43,12 @@ function run(cmd: string, cwd: string): string {
 }
 
 function createTempRepo(): string {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), "wt-ms-merge-test-")));
-  run("git init", dir);
-  run("git config user.email test@test.com", dir);
-  run("git config user.name Test", dir);
-  writeFileSync(join(dir, "README.md"), "# test\n");
-  mkdirSync(join(dir, ".gsd"), { recursive: true });
-  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
-  run("git add .", dir);
-  run("git commit -m init", dir);
-  run("git branch -M main", dir);
-  return dir;
+  return createGsdIntegrationProject({
+    prefix: "wt-ms-merge-test-",
+    initialFiles: {
+      ".gsd/STATE.md": "# State\n",
+    },
+  }).root;
 }
 
 function createTempRepoWithExternalGsd(): { repo: string; externalState: string } {
@@ -784,6 +780,52 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     );
   });
 
+  test("#2156 (legacy): mergeMilestoneToMain removes external-state worktrees created under .gsd/worktrees/", () => {
+    const { repo, externalState } = freshRepoWithExternalGsd();
+    // Worktrees created by older versions live at .gsd/worktrees/<MID>; git
+    // resolves the symlink and registers them under external state. Canonical
+    // .gsd-worktrees/ creation never crosses the symlink, so this coverage
+    // creates the legacy worktree explicitly. createAutoWorktree chdirs into
+    // the new worktree and mergeMilestoneToMain reads process.cwd() as the
+    // worktree cwd, so mirror that here.
+    const wtPath = join(repo, ".gsd", "worktrees", "M216");
+    run(`git worktree add -b milestone/M216 "${wtPath}"`, repo);
+    process.chdir(wtPath);
+
+    addSliceToMilestone(repo, wtPath, "M216", "S01", "Legacy external cleanup", [
+      { file: "legacy-external-cleanup.ts", content: "export const legacyExternalCleanup = true;\n", message: "add legacy external cleanup" },
+    ]);
+
+    const realWtPath = realpathSync(wtPath);
+    assert.ok(
+      realWtPath.startsWith(externalState),
+      `legacy worktree should be registered under external .gsd state, got ${realWtPath}`,
+    );
+
+    // Recreate the exact divergence from #1852: local .gsd/ is replaced with a
+    // stale real directory, so the computed path no longer matches git's record.
+    unlinkSync(join(repo, ".gsd"));
+    mkdirSync(join(repo, ".gsd", "worktrees", "M216"), { recursive: true });
+    writeFileSync(join(repo, ".gsd", "STATE.md"), "# Local stale state\n");
+    writeFileSync(join(repo, ".gsd", "worktrees", "M216", "stale.txt"), "stale local artifact\n");
+
+    const roadmap = makeRoadmap("M216", "Legacy external cleanup", [
+      { id: "S01", title: "Legacy external cleanup" },
+    ]);
+
+    mergeMilestoneToMain(repo, "M216", roadmap);
+
+    assert.ok(
+      !run("git worktree list", repo).includes("M216"),
+      "merged legacy milestone worktree should be removed from git worktree list",
+    );
+    assert.ok(!existsSync(realWtPath), "real external worktree directory should be removed");
+    assert.ok(
+      !run("git branch", repo).includes("milestone/M216"),
+      "milestone branch should be deleted after merge cleanup",
+    );
+  });
+
   test("#2912: MERGE_HEAD cleaned up after squash-merge conflict", () => {
     const repo = freshRepo();
     const wtPath = createAutoWorktree(repo, "M291");

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

@@ -11,6 +11,11 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
+import {
+  commitAll,
+  createGsdIntegrationProject,
+  writeGsdMilestoneContext,
+} from "./gsd-integration-fixture.ts";
 
 import {
   createAutoWorktree,
@@ -32,17 +37,12 @@ function run(command: string, cwd: string): string {
 }
 
 function createTempRepo(): string {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-test-")));
-  run("git init", dir);
-  run("git config user.email test@test.com", dir);
-  run("git config user.name Test", dir);
-  // Create initial commit on main
-  writeFileSync(join(dir, "README.md"), "# test\n");
-  run("git add .", dir);
-  run("git commit -m init", dir);
-  // Ensure branch is called main
-  run("git branch -M main", dir);
-  return dir;
+  return createGsdIntegrationProject("auto-wt-test-").root;
+}
+
+function commitMilestoneContext(repo: string, milestoneId: string): void {
+  writeGsdMilestoneContext(repo, milestoneId);
+  commitAll(repo, "add milestone");
 }
 
 describe("auto-worktree lifecycle", () => {
@@ -59,13 +59,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("create → detect → teardown", () => {
     tempDir = createTempRepo();
-
-    // Create .gsd/milestones/M003 with a dummy file (simulates planning artifacts)
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // ─── createAutoWorktree ──────────────────────────────────────────
     const wtPath = createAutoWorktree(tempDir, "M003");
@@ -112,11 +106,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("re-entry: create again, exit without teardown, re-enter", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     const wtPath2 = createAutoWorktree(tempDir, "M003");
     assert.ok(existsSync(wtPath2), "worktree re-created");
@@ -144,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;
@@ -192,13 +197,62 @@ describe("auto-worktree lifecycle", () => {
     }
   });
 
+  test("legacy symlink-resolved auto worktree is detected after module state reset", () => {
+    tempDir = createTempRepo();
+    const savedGsdHome = process.env.GSD_HOME;
+    const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-home-legacy-")));
+    const storage = join(fakeHome, ".gsd", "projects", "abc123def456");
+    mkdirSync(join(storage, "milestones", "M001"), { recursive: true });
+    writeFileSync(join(storage, "milestones", "M001", "CONTEXT.md"), "# M001\n");
+    symlinkSync(storage, join(tempDir, ".gsd"));
+    process.env.GSD_HOME = join(fakeHome, ".gsd");
+
+    try {
+      // Worktrees created by older versions live at .gsd/worktrees/<MID>;
+      // git resolves the symlink and registers them under external state.
+      // Detection must keep working for them — canonical .gsd-worktrees/
+      // creation never crosses the symlink, so create the legacy worktree
+      // explicitly.
+      const wtPath = join(tempDir, ".gsd", "worktrees", "M001");
+      run(`git worktree add -b milestone/M001 "${wtPath}"`, tempDir);
+      const realWtPath = realpathSync(wtPath);
+      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+
+      _resetAutoWorktreeOriginalBaseForTests();
+      process.chdir(realWtPath);
+
+      assert.ok(isInAutoWorktree(tempDir), "structural detection works without module originalBase");
+      const resolved = getAutoWorktreePath(realWtPath, "M001");
+      assert.ok(resolved, "existing legacy worktree is found when basePath is the worktree path");
+      assert.equal(realpathSync(resolved!), realWtPath);
+
+      enterAutoWorktree(tempDir, "M001");
+      process.chdir(realWtPath);
+      assert.deepStrictEqual(
+        getActiveAutoWorktreeContext(),
+        {
+          originalBase: tempDir,
+          worktreeName: "M001",
+          branch: "milestone/M001",
+        },
+        "active context is detected from a symlink-resolved legacy worktree cwd",
+      );
+    } finally {
+      process.chdir(tempDir);
+      try {
+        teardownAutoWorktree(tempDir, "M001");
+      } catch {
+        // Best-effort cleanup for partially-created temp worktrees.
+      }
+      if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = savedGsdHome;
+      rmSync(fakeHome, { recursive: true, force: true });
+    }
+  });
+
   test("coexistence with manual worktree", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // Import createWorktree directly for manual worktree
     const { createWorktree } = await import("../../worktree-manager.ts");
@@ -221,11 +275,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("split-brain prevention: originalBase cleared after teardown", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     createAutoWorktree(tempDir, "M003");
     teardownAutoWorktree(tempDir, "M003");
@@ -235,11 +285,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#1526: getMainBranch returns milestone/<MID> in auto-worktree", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M005");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M005 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M005");
 
     const { GitServiceImpl } = await import("../../git-service.ts");
 
@@ -259,11 +305,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#1713: stale worktree directory without .git file", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M010");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M010 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M010");
 
     // Simulate a crash leaving a stale directory with no .git file.
     const { worktreePath } = await import("../../worktree-manager.ts");
@@ -284,11 +326,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#778: re-attach does not reconcile plan checkboxes into a worktree-local .gsd projection", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     const planRelPath = join(".gsd", "milestones", "M004", "slices", "S01", "S01-PLAN.md");
     const planDir = join(tempDir, ".gsd", "milestones", "M004", "slices", "S01");
@@ -348,11 +386,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#2791: mcp.json is not copied into worktree on creation after copyPlanningArtifacts removal", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // Create mcp.json in .gsd/ AFTER the commit (untracked, like real usage).
     // Phase C removed copyPlanningArtifacts, so creation should not seed a
@@ -377,11 +411,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#2791: mcp.json synced via syncGsdStateToWorktree (ROOT_STATE_FILES)", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // Create worktree first (no mcp.json yet)
     const wtPath = createAutoWorktree(tempDir, "M003");

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");
+  },
+);