gsd-pi 2.31.2 → 2.32.0-dev.3d7932c

package/src/resources/extensions/gsd/prompts/run-uat.md

@@ -17,11 +17,8 @@ If a `GSD Skill Preferences` block is present in system context, use it to decid
 ## UAT Instructions
 
 **UAT file:** `{{uatPath}}`
-**UAT type:** `{{uatType}}`
 **Result file to write:** `{{uatResultPath}}`
 
-### If UAT type is `artifact-driven`
-
 You are the test runner. Execute every check defined in `{{uatPath}}` directly:
 
 - Run shell commands with `bash`
@@ -46,7 +43,7 @@ Write `{{uatResultPath}}` with:
 ```markdown
 ---
 sliceId: {{sliceId}}
-uatType: {{uatType}}
+uatType: artifact-driven
 verdict: PASS | FAIL | PARTIAL
 date: <ISO 8601 timestamp>
 ---
@@ -68,44 +65,6 @@ date: <ISO 8601 timestamp>
 <any additional context, errors encountered, or follow-up items>
 ```
 
-### If UAT type is NOT `artifact-driven` (type is `{{uatType}}`)
-
-This UAT type requires human execution or live-runtime observation that you cannot perform mechanically. Your role is to surface it clearly for review.
-
-Write `{{uatResultPath}}` with:
-
-```markdown
----
-sliceId: {{sliceId}}
-uatType: {{uatType}}
-verdict: surfaced-for-human-review
-date: <ISO 8601 timestamp>
----
-
-# UAT Result — {{sliceId}}
-
-## UAT Type
-
-`{{uatType}}` — requires human execution or live-runtime verification.
-
-## Status
-
-Surfaced for human review. Auto-mode will pause after this unit so the UAT can be performed manually.
-
-## UAT File
-
-See `{{uatPath}}` for the full UAT specification and acceptance criteria.
-
-## Instructions for Human Reviewer
-
-Review `{{uatPath}}`, perform the described UAT steps, then update this file with:
-- The actual verdict (PASS / FAIL / PARTIAL)
-- Results for each check
-- Date completed
-
-Once updated, run `/gsd auto` to resume auto-mode.
-```
-
 ---
 
 **You MUST write `{{uatResultPath}}` before finishing.**

package/src/resources/extensions/gsd/quick.ts

@@ -14,8 +14,8 @@ import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { GitServiceImpl, runGit } from "./git-service.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { createGitService, runGit } from "./git-service.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 
@@ -103,16 +103,16 @@ export async function handleQuick(
   const date = new Date().toISOString().split("T")[0];
 
   // Create git branch for the quick task (unless isolation: none)
-  const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-  const git = new GitServiceImpl(basePath, gitPrefs);
+  const git = createGitService(basePath);
   const branchName = `gsd/quick/${taskNum}-${slug}`;
-  const skipBranch = gitPrefs.isolation === "none";
+  const skipBranch = git.prefs.isolation === "none";
 
   let branchCreated = false;
+  let originalBranch: string | undefined;
   if (!skipBranch) {
     try {
-      const current = git.getCurrentBranch();
-      if (current !== branchName) {
+      originalBranch = git.getCurrentBranch();
+      if (originalBranch !== branchName) {
         // Auto-commit any dirty state before switching
         try {
           git.autoCommit("quick-task", `Q${taskNum}`, []);
@@ -123,7 +123,7 @@ export async function handleQuick(
       }
     } catch (err) {
       // Branch creation failed — continue on current branch
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       ctx.ui.notify(`Could not create branch ${branchName}: ${message}. Working on current branch.`, "warning");
     }
   }
@@ -156,4 +156,57 @@ export async function handleQuick(
     },
     { triggerTurn: true },
   );
+
+  // Schedule branch merge-back after the quick task agent session ends.
+  // Without this, auto-mode resumes on the quick-task branch (#1269).
+  if (branchCreated && originalBranch) {
+    _pendingQuickBranchReturn = {
+      basePath,
+      originalBranch,
+      quickBranch: branchName,
+      taskNum,
+      slug,
+      description,
+    };
+  }
+}
+
+/** Pending quick-task branch return — consumed by cleanupQuickBranch(). */
+let _pendingQuickBranchReturn: {
+  basePath: string;
+  originalBranch: string;
+  quickBranch: string;
+  taskNum: number;
+  slug: string;
+  description: string;
+} | null = null;
+
+/**
+ * Merge the quick-task branch back to the original branch and switch.
+ * Called from the agent_end handler after a quick task completes.
+ * Returns true if a branch return was performed.
+ */
+export function cleanupQuickBranch(): boolean {
+  if (!_pendingQuickBranchReturn) return false;
+  const { basePath, originalBranch, quickBranch, taskNum, slug, description } = _pendingQuickBranchReturn;
+  _pendingQuickBranchReturn = null;
+
+  try {
+    // Auto-commit any remaining work
+    try { runGit(basePath, ["add", "-A"]); } catch {}
+    try { runGit(basePath, ["commit", "-m", `quick(Q${taskNum}): ${slug}`]); } catch {}
+
+    // Switch back and merge
+    runGit(basePath, ["checkout", originalBranch]);
+    try {
+      runGit(basePath, ["merge", "--squash", quickBranch]);
+      runGit(basePath, ["commit", "-m", `quick(Q${taskNum}): ${description.slice(0, 72)}`]);
+    } catch { /* merge conflict or nothing — non-fatal */ }
+
+    // Clean up quick branch
+    try { runGit(basePath, ["branch", "-D", quickBranch]); } catch {}
+    return true;
+  } catch {
+    return false;
+  }
 }

package/src/resources/extensions/gsd/repo-identity.ts

@@ -10,7 +10,7 @@ import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
@@ -37,6 +37,27 @@ function getRemoteUrl(basePath: string): string {
  */
 function resolveGitRoot(basePath: string): string {
   try {
+    // In a worktree, --show-toplevel returns the worktree path, not the main
+    // repo root. Use --git-common-dir to find the shared .git directory,
+    // then derive the main repo root from it (#1288).
+    const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd: basePath,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+    }).trim();
+
+    // If commonDir ends with .git/worktrees/<name>, the main repo is two
+    // levels up from the worktrees dir. If it's just .git, resolve normally.
+    if (commonDir.includes(`${sep}worktrees${sep}`) || commonDir.includes("/worktrees/")) {
+      // e.g., /path/to/project/.gsd/worktrees/M001/.git → /path/to/project
+      // or /path/to/project/.git/worktrees/M001 → /path/to/project
+      const gitDir = commonDir.replace(/[/\\]worktrees[/\\][^/\\]+$/, "");
+      const mainRoot = resolve(gitDir, "..");
+      return mainRoot;
+    }
+
+    // Not in a worktree — use --show-toplevel as usual
     return execFileSync("git", ["rev-parse", "--show-toplevel"], {
       cwd: basePath,
       encoding: "utf-8",

package/src/resources/extensions/gsd/session-lock.ts

@@ -154,12 +154,23 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
         // Retry acquisition after cleanup
         const release = lockfile.lockSync(gsdDir, {
           realpath: false,
-          stale: 300_000,
+          stale: 1_800_000, // 30 minutes — match primary lock settings
           update: 10_000,
+          onCompromised: () => {
+            _lockCompromised = true;
+          },
         });
         _releaseFunction = release;
         _lockedPath = basePath;
         _lockPid = process.pid;
+
+        // Safety net for retry path too
+        const retryLockDir = join(gsdDir + ".lock");
+        process.once("exit", () => {
+          try { if (_releaseFunction) { _releaseFunction(); _releaseFunction = null; } } catch {}
+          try { if (existsSync(retryLockDir)) rmSync(retryLockDir, { recursive: true, force: true }); } catch {}
+        });
+
         atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
         return { acquired: true };
       } catch {

package/src/resources/extensions/gsd/tests/auto-reentrancy-guard.test.ts

@@ -0,0 +1,127 @@
+/**
+ * auto-reentrancy-guard.test.ts — Tests for the unconditional reentrancy guard.
+ *
+ * Regression for #1272: auto-mode stuck-loop where gap watchdog or
+ * pendingAgentEndRetry could enter dispatchNextUnit concurrently during
+ * recursive skip chains because the reentrancy guard was bypassed when
+ * skipDepth > 0.
+ *
+ * The fix makes the guard unconditional (`if (s.dispatching)` without
+ * `&& s.skipDepth === 0`), and defers recursive re-dispatch via
+ * setImmediate/setTimeout so s.dispatching is released first.
+ */
+
+import {
+  _getDispatching,
+  _setDispatching,
+  _getSkipDepth,
+  _setSkipDepth,
+} from "../auto.ts";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+async function main(): Promise<void> {
+  // ─── Test-only accessors work ───────────────────────────────────────────
+  console.log("\n=== reentrancy guard: test accessors round-trip ===");
+  {
+    _setDispatching(false);
+    assertEq(_getDispatching(), false, "dispatching starts false");
+
+    _setDispatching(true);
+    assertEq(_getDispatching(), true, "dispatching set to true");
+
+    _setDispatching(false);
+    assertEq(_getDispatching(), false, "dispatching reset to false");
+  }
+
+  // ─── skipDepth accessors ────────────────────────────────────────────────
+  console.log("\n=== reentrancy guard: skipDepth accessors round-trip ===");
+  {
+    _setSkipDepth(0);
+    assertEq(_getSkipDepth(), 0, "skipDepth starts at 0");
+
+    _setSkipDepth(3);
+    assertEq(_getSkipDepth(), 3, "skipDepth set to 3");
+
+    _setSkipDepth(0);
+    assertEq(_getSkipDepth(), 0, "skipDepth reset to 0");
+  }
+
+  // ─── Guard blocks even when skipDepth > 0 (#1272 regression) ───────────
+  console.log("\n=== reentrancy guard: blocks when dispatching=true regardless of skipDepth ===");
+  {
+    // Simulate the scenario from #1272: dispatching=true + skipDepth>0
+    // The old guard (`if (s.dispatching && s.skipDepth === 0)`) would allow
+    // concurrent entry when skipDepth > 0. The fix makes the check
+    // unconditional on skipDepth.
+    _setDispatching(true);
+    _setSkipDepth(2);
+
+    // Verify dispatching is true — guard should block regardless of skipDepth
+    assertTrue(
+      _getDispatching() === true,
+      "dispatching flag is true during skip chain"
+    );
+
+    // The actual reentrancy guard in dispatchNextUnit checks:
+    //   if (s.dispatching) { return; }
+    // We verify the state that would trigger the guard:
+    const wouldBlock = _getDispatching(); // unconditional check
+    const wouldBlockOld = _getDispatching() && _getSkipDepth() === 0; // old check
+
+    assertTrue(wouldBlock === true, "new guard blocks when dispatching=true, skipDepth=2");
+    assertTrue(wouldBlockOld === false, "old guard WOULD NOT block when dispatching=true, skipDepth=2 (the bug)");
+
+    // Clean up
+    _setDispatching(false);
+    _setSkipDepth(0);
+  }
+
+  // ─── Guard allows entry when dispatching=false ──────────────────────────
+  console.log("\n=== reentrancy guard: allows entry when dispatching=false ===");
+  {
+    _setDispatching(false);
+    _setSkipDepth(0);
+    assertTrue(!_getDispatching(), "guard allows entry when dispatching=false, skipDepth=0");
+
+    _setDispatching(false);
+    _setSkipDepth(3);
+    assertTrue(!_getDispatching(), "guard allows entry when dispatching=false, skipDepth=3");
+
+    _setSkipDepth(0);
+  }
+
+  // ─── skipDepth does not affect guard decision (the fix) ─────────────────
+  console.log("\n=== reentrancy guard: skipDepth is irrelevant to guard decision ===");
+  {
+    for (const depth of [0, 1, 2, 5]) {
+      _setDispatching(true);
+      _setSkipDepth(depth);
+      assertTrue(
+        _getDispatching() === true,
+        `guard blocks at skipDepth=${depth} when dispatching=true`
+      );
+    }
+
+    for (const depth of [0, 1, 2, 5]) {
+      _setDispatching(false);
+      _setSkipDepth(depth);
+      assertTrue(
+        _getDispatching() === false,
+        `guard allows at skipDepth=${depth} when dispatching=false`
+      );
+    }
+
+    // Clean up
+    _setDispatching(false);
+    _setSkipDepth(0);
+  }
+
+  report();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/resources/extensions/gsd/tests/context-compression.test.ts

@@ -91,7 +91,7 @@ test("compression: buildPlanMilestonePrompt minimal drops project/requirements/d
   // The plan-milestone builder should gate root file inlining on inlineLevel
   assert.ok(
     promptsSrc.includes('inlineLevel !== "minimal"') &&
-    promptsSrc.includes('inlineGsdRootFile(base, "project.md"'),
+    promptsSrc.includes("inlineProjectFromDb(base)"),
     "plan-milestone should conditionally include project.md based on level",
   );
 });

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

@@ -0,0 +1,314 @@
+/**
+ * doctor-environment.test.ts — Tests for environment health checks (#1221).
+ *
+ * Tests:
+ *   - Node version detection
+ *   - Dependencies installed check
+ *   - Env file detection
+ *   - Port conflict detection
+ *   - Disk space check
+ *   - Docker detection
+ *   - Project tool detection
+ *   - Doctor issue conversion
+ *   - Report formatting
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  runEnvironmentChecks,
+  runFullEnvironmentChecks,
+  environmentResultsToDoctorIssues,
+  formatEnvironmentReport,
+  checkEnvironmentHealth,
+  type EnvironmentCheckResult,
+} from "../doctor-environment.ts";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+function createProjectDir(files: Record<string, string> = {}): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-env-test-"));
+  for (const [name, content] of Object.entries(files)) {
+    const filePath = join(dir, name);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content);
+  }
+  return dir;
+}
+
+async function main(): Promise<void> {
+  const cleanups: string[] = [];
+
+  try {
+    // ── Node Version Check ─────────────────────────────────────────────
+    console.log("\n=== env: no package.json returns empty ===");
+    {
+      const dir = createProjectDir();
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      // No package.json → no node checks
+      const nodeCheck = results.find(r => r.name === "node_version");
+      assertEq(nodeCheck, undefined, "no node version check without package.json");
+    }
+
+    console.log("\n=== env: package.json without engines returns no node check ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test", version: "1.0.0" }),
+      });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const nodeCheck = results.find(r => r.name === "node_version");
+      assertEq(nodeCheck, undefined, "no node version check without engines field");
+    }
+
+    console.log("\n=== env: package.json with engines returns node check ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({
+          name: "test",
+          version: "1.0.0",
+          engines: { node: ">=18.0.0" },
+        }),
+      });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const nodeCheck = results.find(r => r.name === "node_version");
+      assertTrue(nodeCheck !== undefined, "node version check runs with engines field");
+      // Current node should be >= 18 in CI
+      assertEq(nodeCheck!.status, "ok", "node version meets requirement");
+    }
+
+    // ── Dependencies Check ─────────────────────────────────────────────
+    console.log("\n=== env: missing node_modules detected ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+      });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const depsCheck = results.find(r => r.name === "dependencies");
+      assertTrue(depsCheck !== undefined, "dependencies check runs");
+      assertEq(depsCheck!.status, "error", "missing node_modules is an error");
+      assertTrue(depsCheck!.message.includes("node_modules missing"), "reports missing node_modules");
+    }
+
+    console.log("\n=== env: existing node_modules detected ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+      });
+      mkdirSync(join(dir, "node_modules"), { recursive: true });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const depsCheck = results.find(r => r.name === "dependencies");
+      assertTrue(depsCheck !== undefined, "dependencies check runs");
+      assertEq(depsCheck!.status, "ok", "existing node_modules is ok");
+    }
+
+    // ── Env File Check ─────────────────────────────────────────────────
+    console.log("\n=== env: .env.example without .env detected ===");
+    {
+      const dir = createProjectDir({
+        ".env.example": "DB_URL=xxx\nAPI_KEY=xxx\n",
+      });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const envCheck = results.find(r => r.name === "env_file");
+      assertTrue(envCheck !== undefined, "env file check runs");
+      assertEq(envCheck!.status, "warning", "missing .env is a warning");
+    }
+
+    console.log("\n=== env: .env.example with .env is ok ===");
+    {
+      const dir = createProjectDir({
+        ".env.example": "DB_URL=xxx\n",
+        ".env": "DB_URL=postgres://localhost/test\n",
+      });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const envCheck = results.find(r => r.name === "env_file");
+      assertTrue(envCheck !== undefined, "env file check runs");
+      assertEq(envCheck!.status, "ok", "present .env is ok");
+    }
+
+    console.log("\n=== env: .env.example with .env.local is ok ===");
+    {
+      const dir = createProjectDir({
+        ".env.example": "DB_URL=xxx\n",
+        ".env.local": "DB_URL=postgres://localhost/test\n",
+      });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const envCheck = results.find(r => r.name === "env_file");
+      assertTrue(envCheck !== undefined, "env file check runs");
+      assertEq(envCheck!.status, "ok", ".env.local counts as present");
+    }
+
+    // ── Disk Space Check ───────────────────────────────────────────────
+    console.log("\n=== env: disk space check returns result ===");
+    if (process.platform !== "win32") {
+      const dir = createProjectDir();
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const diskCheck = results.find(r => r.name === "disk_space");
+      assertTrue(diskCheck !== undefined, "disk space check runs on unix");
+      // Should be ok on dev machines with reasonable disk
+      assertTrue(diskCheck!.status === "ok" || diskCheck!.status === "warning", "disk check returns valid status");
+    }
+
+    // ── Project Tools Check ────────────────────────────────────────────
+    console.log("\n=== env: detects missing python when pyproject.toml exists ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+        "pyproject.toml": "[build-system]\nrequires = ['setuptools']\n",
+      });
+      mkdirSync(join(dir, "node_modules"), { recursive: true });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const pythonCheck = results.find(r => r.name === "python");
+      // Python is likely installed on CI/dev machines, so just verify the check runs
+      // without error — the result depends on the system
+      assertTrue(true, "python check runs without error");
+    }
+
+    console.log("\n=== env: detects Cargo.toml ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+        "Cargo.toml": "[package]\nname = 'test'\n",
+      });
+      mkdirSync(join(dir, "node_modules"), { recursive: true });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      // Just verify it runs without error
+      assertTrue(true, "cargo check runs without error");
+    }
+
+    // ── Docker Check ───────────────────────────────────────────────────
+    console.log("\n=== env: no docker check without Dockerfile ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+      });
+      mkdirSync(join(dir, "node_modules"), { recursive: true });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const dockerCheck = results.find(r => r.name === "docker");
+      assertEq(dockerCheck, undefined, "no docker check without Dockerfile");
+    }
+
+    console.log("\n=== env: docker check with Dockerfile ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+        "Dockerfile": "FROM node:22\n",
+      });
+      mkdirSync(join(dir, "node_modules"), { recursive: true });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      const dockerCheck = results.find(r => r.name === "docker");
+      // Docker may or may not be installed on the test machine
+      assertTrue(dockerCheck !== undefined, "docker check runs when Dockerfile present");
+    }
+
+    // ── Doctor Issue Conversion ────────────────────────────────────────
+    console.log("\n=== env: converts results to doctor issues ===");
+    {
+      const results: EnvironmentCheckResult[] = [
+        { name: "node_version", status: "ok", message: "Node.js v22.0.0" },
+        { name: "dependencies", status: "error", message: "node_modules missing" },
+        { name: "env_file", status: "warning", message: ".env missing", detail: "Copy .env.example" },
+      ];
+
+      const issues = environmentResultsToDoctorIssues(results);
+      assertEq(issues.length, 2, "only non-ok results converted");
+      assertEq(issues[0]!.severity, "error", "error severity preserved");
+      assertEq(issues[0]!.code, "env_dependencies", "code prefixed with env_");
+      assertEq(issues[1]!.severity, "warning", "warning severity preserved");
+      assertTrue(issues[1]!.message.includes("Copy .env.example"), "detail included in message");
+    }
+
+    // ── checkEnvironmentHealth integration ──────────────────────────────
+    console.log("\n=== env: checkEnvironmentHealth adds issues to array ===");
+    {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({ name: "test" }),
+      });
+      cleanups.push(dir);
+
+      const issues: any[] = [];
+      await checkEnvironmentHealth(dir, issues);
+      // Should have at least the missing node_modules issue
+      assertTrue(issues.some(i => i.code === "env_dependencies"), "environment issues added to array");
+    }
+
+    // ── Report Formatting ──────────────────────────────────────────────
+    console.log("\n=== env: formatEnvironmentReport ===");
+    {
+      const results: EnvironmentCheckResult[] = [
+        { name: "node_version", status: "ok", message: "Node.js v22.0.0" },
+        { name: "dependencies", status: "error", message: "node_modules missing", detail: "Run npm install" },
+        { name: "disk_space", status: "ok", message: "50.2GB free" },
+      ];
+
+      const report = formatEnvironmentReport(results);
+      assertTrue(report.includes("Environment Health:"), "has header");
+      assertTrue(report.includes("Node.js v22.0.0"), "includes ok result");
+      assertTrue(report.includes("node_modules missing"), "includes error result");
+      assertTrue(report.includes("Run npm install"), "includes detail for errors");
+    }
+
+    console.log("\n=== env: formatEnvironmentReport empty ===");
+    {
+      const report = formatEnvironmentReport([]);
+      assertEq(report, "No environment checks applicable.", "empty report message");
+    }
+
+    // ── Full environment checks include git remote ─────────────────────
+    console.log("\n=== env: runFullEnvironmentChecks includes git remote ===");
+    {
+      // runFullEnvironmentChecks adds git remote check
+      // We can't easily test this without a real git repo, but verify it doesn't throw
+      const dir = createProjectDir();
+      cleanups.push(dir);
+      const results = runFullEnvironmentChecks(dir);
+      // No git repo → no remote check, but should not throw
+      assertTrue(true, "runFullEnvironmentChecks does not throw on non-git dir");
+    }
+
+    // ── Port Detection from package.json ───────────────────────────────
+    console.log("\n=== env: port detection from scripts ===");
+    if (process.platform !== "win32") {
+      const dir = createProjectDir({
+        "package.json": JSON.stringify({
+          name: "test",
+          scripts: {
+            dev: "next dev --port 3456",
+            start: "node server.js",
+          },
+        }),
+      });
+      mkdirSync(join(dir, "node_modules"), { recursive: true });
+      cleanups.push(dir);
+      const results = runEnvironmentChecks(dir);
+      // Port 3456 is unlikely to be in use, so no conflicts expected
+      const portConflicts = results.filter(r => r.name === "port_conflict");
+      // Just verify it ran without error
+      assertTrue(true, "port check with script-detected ports runs without error");
+    }
+
+  } finally {
+    for (const dir of cleanups) {
+      try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  }
+
+  report();
+}
+
+main();