gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/tests/deferred-milestone-dir-4996.test.ts

@@ -0,0 +1,116 @@
+// GSD Extension — Regression test for #4996: deferred milestone dir creation
+// Verifies that showHeadlessMilestoneCreation does not pre-create the milestone
+// directory before the discuss flow runs. The dir should only appear after a
+// writer (saveArtifactToDb / atomicWriteAsync) emits the first artifact.
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, existsSync, rmSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import { isReusableGhostMilestone } from "../state.ts";
+import { nextMilestoneIdReserved } from "../milestone-id-reservation.ts";
+import { clearReservedMilestoneIds, findMilestoneIds } from "../milestone-ids.ts";
+import { invalidateAllCaches } from "../cache.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GUIDED_FLOW_PATH = join(__dirname, "..", "guided-flow.ts");
+
+function getShowHeadlessBody(): string {
+  const source = readFileSync(GUIDED_FLOW_PATH, "utf-8");
+  const fnStart = source.indexOf("export async function showHeadlessMilestoneCreation");
+  assert.ok(fnStart > -1, "showHeadlessMilestoneCreation must exist in guided-flow.ts");
+  const nextExport = source.indexOf("\nexport ", fnStart + 1);
+  return source.slice(fnStart, nextExport === -1 ? source.length : nextExport);
+}
+
+function makeBase(prefix = "gsd-deferred-dir-"): string {
+  const base = mkdtempSync(join(tmpdir(), prefix));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+describe("showHeadlessMilestoneCreation source guard (#4996)", () => {
+  it("does not call mkdirSync in the headless milestone creation path", () => {
+    const body = getShowHeadlessBody();
+    assert.doesNotMatch(
+      body,
+      /\bmkdirSync\s*\(/,
+      "showHeadlessMilestoneCreation must not pre-create milestone directories",
+    );
+  });
+
+  it("does not call mkdir or mkdirp before dispatchWorkflow", () => {
+    const body = getShowHeadlessBody();
+    const dispatchIdx = body.indexOf("dispatchWorkflow");
+    assert.ok(dispatchIdx > -1, "dispatchWorkflow must be present");
+
+    const beforeDispatch = body.slice(0, dispatchIdx);
+    assert.doesNotMatch(
+      beforeDispatch,
+      /\b(?:mkdir|mkdirp)\s*\(/,
+      "showHeadlessMilestoneCreation must defer directory creation until artifact write",
+    );
+  });
+});
+
+describe("deferred milestone dir creation (#4996)", () => {
+  let base: string;
+
+  beforeEach(() => {
+    clearReservedMilestoneIds();
+  });
+
+  afterEach(() => {
+    try { closeDatabase(); } catch { /* ignore */ }
+    try { invalidateAllCaches(); } catch { /* ignore */ }
+    try { clearReservedMilestoneIds(); } catch { /* ignore */ }
+    try { rmSync(base, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it("(a) fresh project: milestones dir has no M001 entry before any discuss flow", () => {
+    base = makeBase();
+    const nextId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+    assert.equal(nextId, "M001", "reservation should choose M001 for a fresh project");
+
+    const ids = findMilestoneIds(base);
+    assert.equal(ids.length, 0, "no milestone dirs should exist before any discuss flow");
+
+    // And specifically M001 should not exist
+    const m001Dir = join(base, ".gsd", "milestones", "M001");
+    assert.ok(!existsSync(m001Dir), "M001 dir must not exist before the discuss flow runs");
+  });
+
+  it("(b) abandoned discuss flow leaves no orphan: isReusableGhostMilestone returns false for non-existent dir", () => {
+    base = makeBase();
+    const nextId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+    assert.equal(nextId, "M001", "reservation should not require a pre-created directory");
+
+    const m001Dir = join(base, ".gsd", "milestones", "M001");
+    assert.ok(!existsSync(m001Dir), "no M001 dir should exist");
+    assert.equal(isReusableGhostMilestone(base, "M001"), false, "non-existent milestone should not be reusable");
+    // findMilestoneIds only returns dirs that exist
+    const ids = findMilestoneIds(base);
+    assert.ok(!ids.includes("M001"), "M001 should not appear in findMilestoneIds when no dir exists");
+  });
+
+  it("(c) a stub dir left from a previous bug IS reusable but a newly-generated ID with no dir is not in the ghost list", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    // Create a stub to represent a pre-existing phantom
+    mkdirSync(join(base, ".gsd", "milestones", "M001", "slices"), { recursive: true });
+
+    // isReusableGhostMilestone identifies the orphaned stub
+    assert.ok(isReusableGhostMilestone(base, "M001"), "pre-existing stub should be identified as reusable ghost");
+    const nextId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+    assert.equal(nextId, "M001", "reservation should reuse the pre-existing ghost");
+
+    // The new ID (M002, which would be max+1 in this scenario but ghost reuse returns M001)
+    // should not have a dir
+    const m002Dir = join(base, ".gsd", "milestones", "M002");
+    assert.ok(!existsSync(m002Dir), "a freshly-requested ID should have no dir until first artifact write");
+  });
+});

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

@@ -1,28 +1,22 @@
 /**
- * discuss-empty-db-fallback.test.ts — Tests for #2892.
+ * Behavioural regression tests for #2892.
  *
- * When the DB is open but empty (e.g., after crash/truncation),
- * getMilestoneSlices() returns [] and showDiscuss() incorrectly declares
- * "All slices are complete." The fix adds a roadmap fallback: when the DB
- * returns zero slices but a ROADMAP file exists, parse slices from the
- * roadmap instead of treating zero slices as "all complete."
+ * When the DB is open but empty (e.g. after crash/truncation),
+ * getMilestoneSlices() returns []. The fix in showDiscuss() falls back to
+ * parsing slices from the on-disk ROADMAP file instead of declaring "all
+ * slices are complete." These tests pin the parser contract that the
+ * fallback depends on: incomplete checkboxes (`[ ]`) yield `done=false`
+ * slices and completed checkboxes (`[x]`) yield `done=true`.
+ *
+ * The earlier source-grep / regex-on-showDiscuss-body tests (audit verdicts
+ * SOURCE_GREP / POSITIONAL — see #4826/#4829) were dropped; they pinned a
+ * specific surface form rather than behaviour.
  */
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
 import { parseRoadmapSlices } from "../roadmap-slices.ts";
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-function readGuidedFlowSource(): string {
-  const thisFile = fileURLToPath(import.meta.url);
-  const thisDir = dirname(thisFile);
-  return readFileSync(join(thisDir, "..", "guided-flow.ts"), "utf-8");
-}
-
 const SAMPLE_ROADMAP = `# M012 Roadmap
 
 ## Slices
@@ -34,80 +28,23 @@ const SAMPLE_ROADMAP = `# M012 Roadmap
   > After this: dashboard renders
 `;
 
-// ─── Tests ───────────────────────────────────────────────────────────────────
-
-describe("discuss-empty-db-fallback (#2892)", () => {
-
-  test("1. parseRoadmapSlices extracts slices from a valid ROADMAP", () => {
+describe("discuss-empty-db-fallback parser contract (#2892)", () => {
+  test("parseRoadmapSlices extracts slices from a valid ROADMAP", () => {
     const slices = parseRoadmapSlices(SAMPLE_ROADMAP);
     assert.strictEqual(slices.length, 3, "should parse 3 slices from sample roadmap");
-    assert.strictEqual(slices[0]!.id, "S01");
-    assert.strictEqual(slices[1]!.id, "S02");
-    assert.strictEqual(slices[2]!.id, "S03");
-    // All slices are incomplete ([ ] not [x])
-    assert.ok(slices.every(s => !s.done), "all slices should be incomplete");
-  });
-
-  test("2. guided-flow imports parseRoadmapSlices for roadmap fallback", () => {
-    const source = readGuidedFlowSource();
-    assert.ok(
-      source.includes("parseRoadmapSlices"),
-      "guided-flow must import parseRoadmapSlices to support roadmap fallback when DB is empty",
-    );
+    const ids = slices.map(s => s.id).sort();
+    assert.deepStrictEqual(ids, ["S01", "S02", "S03"]);
   });
 
-  test("3. guided-flow has roadmap fallback when normSlices is empty but roadmapContent exists", () => {
-    const source = readGuidedFlowSource();
-    // The fix must add a fallback that checks normSlices.length === 0 && roadmapContent
-    // and repopulates normSlices from the roadmap before the pendingSlices guard.
-    //
-    // Pattern: after DB query produces normSlices, if empty + roadmap exists,
-    // fall back to parseRoadmapSlices(roadmapContent).
-    const fallbackPattern = /normSlices\.length\s*===\s*0\s*&&\s*roadmapContent/;
+  test("incomplete checkboxes yield done=false (so fallback shows them as pending)", () => {
+    const slices = parseRoadmapSlices(SAMPLE_ROADMAP);
     assert.ok(
-      fallbackPattern.test(source),
-      "guided-flow must check normSlices.length === 0 && roadmapContent to trigger roadmap fallback",
+      slices.every(s => s.done === false),
+      "all 3 incomplete roadmap slices must be done=false — otherwise the empty-DB fallback would falsely report them complete (#2892)",
     );
   });
 
-  test("4. guided-flow no longer has unguarded pendingSlices === 0 exit after DB-only query", () => {
-    const source = readGuidedFlowSource();
-    // Extract the showDiscuss function body
-    const fnMatch = source.match(
-      /async function showDiscuss\s*\([^)]*\)[^{]*\{([\s\S]*?)\nfunction\s/,
-    );
-    assert.ok(!!fnMatch, "showDiscuss function body must be found");
-
-    if (fnMatch) {
-      const body = fnMatch[1]!;
-      // After the DB query block (isDbAvailable/getMilestoneSlices), there should
-      // be a roadmap fallback BEFORE the pendingSlices.length === 0 check.
-      // Find the getMilestoneSlices call and the pendingSlices === 0 check
-      const dbQueryIdx = body.indexOf("getMilestoneSlices");
-      const fallbackIdx = body.indexOf("parseRoadmapSlices");
-      const pendingGuardIdx = body.indexOf('pendingSlices.length === 0');
-
-      assert.ok(dbQueryIdx > 0, "getMilestoneSlices call must exist");
-      assert.ok(fallbackIdx > 0, "parseRoadmapSlices fallback must exist");
-      assert.ok(pendingGuardIdx > 0, "pendingSlices.length === 0 guard must exist");
-      assert.ok(
-        fallbackIdx > dbQueryIdx && fallbackIdx < pendingGuardIdx,
-        "parseRoadmapSlices fallback must appear BETWEEN DB query and pendingSlices === 0 guard",
-      );
-    }
-  });
-
-  test("5. roadmap-parsed slices map to NormSlice format with done=false by default", () => {
-    // When falling back to roadmap, incomplete slices ([ ]) should map to done:false,
-    // ensuring they appear as pending and are NOT falsely reported as complete.
-    const slices = parseRoadmapSlices(SAMPLE_ROADMAP);
-    const normSlices = slices.map(s => ({ id: s.id, done: s.done, title: s.title }));
-    const pendingSlices = normSlices.filter(s => !s.done);
-    assert.strictEqual(pendingSlices.length, 3,
-      "all 3 incomplete roadmap slices should be pending — not falsely treated as complete");
-  });
-
-  test("6. roadmap with completed slices correctly reports them as done", () => {
+  test("completed checkboxes yield done=true; mixed roadmap surfaces only the open slices as pending", () => {
     const completedRoadmap = `# M012 Roadmap
 
 ## Slices
@@ -119,9 +56,7 @@ describe("discuss-empty-db-fallback (#2892)", () => {
   > After this: dashboard renders
 `;
     const slices = parseRoadmapSlices(completedRoadmap);
-    const normSlices = slices.map(s => ({ id: s.id, done: s.done, title: s.title }));
-    const pendingSlices = normSlices.filter(s => !s.done);
-    assert.strictEqual(pendingSlices.length, 1, "only S02 should be pending");
-    assert.strictEqual(pendingSlices[0]!.id, "S02");
+    const pendingIds = slices.filter(s => !s.done).map(s => s.id);
+    assert.deepStrictEqual(pendingIds, ["S02"], "only S02 should be reported as pending");
   });
 });

package/src/resources/extensions/gsd/tests/discuss-queued-milestones.test.ts

@@ -16,11 +16,9 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { fileURLToPath } from "node:url";
-import { dirname } from "node:path";
 
 import { deriveState } from "../state.ts";
 import { invalidateAllCaches } from "../cache.ts";
@@ -57,12 +55,6 @@ function writeRoadmap(base: string, mid: string, content: string): void {
   writeFileSync(join(base, ".gsd", "milestones", mid, `${mid}-ROADMAP.md`), content);
 }
 
-function readGuidedFlowSource(): string {
-  const thisFile = fileURLToPath(import.meta.url);
-  const thisDir = dirname(thisFile);
-  return readFileSync(join(thisDir, "..", "guided-flow.ts"), "utf-8");
-}
-
 // ─── Tests ────────────────────────────────────────────────────────────────────
 
 describe("discuss-queued-milestones (#2307)", () => {
@@ -169,113 +161,10 @@ describe("discuss-queued-milestones (#2307)", () => {
     }
   });
 
-  test("6. guided-flow no longer hard-exits when no active milestone but pending exist", () => {
-    const source = readGuidedFlowSource();
-
-    // The old guard was a simple early-exit:
-    //   if (!state.activeMilestone) {
-    //     ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
-    //     return;
-    //   }
-    //
-    // The new guard should check for pending milestones and route instead.
-    const oldGuardPattern = /if\s*\(!state\.activeMilestone\)\s*\{\s*ctx\.ui\.notify\("No active milestone/;
-    assert.ok(
-      !oldGuardPattern.test(source),
-      "guided-flow must not unconditionally exit when activeMilestone is null",
-    );
-  });
-
-  test("7. showDiscussQueuedMilestone helper exists in guided-flow", () => {
-    const source = readGuidedFlowSource();
-    assert.ok(
-      source.includes("showDiscussQueuedMilestone"),
-      "guided-flow must export showDiscussQueuedMilestone helper",
-    );
-  });
-
-  test("8. dispatchDiscussForMilestone helper exists in guided-flow", () => {
-    const source = readGuidedFlowSource();
-    assert.ok(
-      source.includes("dispatchDiscussForMilestone"),
-      "guided-flow must export dispatchDiscussForMilestone helper",
-    );
-  });
-
-  test("9. dispatchDiscussForMilestone does not set pendingAutoStart", () => {
-    const source = readGuidedFlowSource();
-
-    // Extract the dispatchDiscussForMilestone function body
-    const fnMatch = source.match(
-      /async function dispatchDiscussForMilestone\s*\([^)]*\)[^{]*\{([\s\S]*?)\n\}/,
-    );
-    assert.ok(!!fnMatch, "dispatchDiscussForMilestone function body must be present");
-
-    if (fnMatch) {
-      assert.ok(
-        !fnMatch[1].includes("pendingAutoStart"),
-        "dispatchDiscussForMilestone must NOT set pendingAutoStart — discussing a queued milestone must not activate it",
-      );
-    }
-  });
-
-  test("10. slice picker includes queued milestone option when pending milestones exist", () => {
-    const source = readGuidedFlowSource();
-    assert.ok(
-      source.includes("discuss_queued_milestone"),
-      "slice picker must include a 'discuss_queued_milestone' action id for queued milestones",
-    );
-    assert.ok(
-      source.includes("Discuss a queued milestone"),
-      "slice picker must label the queued milestone action clearly",
-    );
-  });
-
-  test("11. queued milestone picker labels entries with [queued]", () => {
-    const source = readGuidedFlowSource();
-    assert.ok(
-      source.includes("[queued]"),
-      "queued milestone picker must label entries with [queued] to distinguish from active",
-    );
-  });
-
-  // ─── #3150: allDiscussed early-return must not block queued milestone discussion ──
-
-  test("12. allDiscussed path checks for pending milestones before returning (#3150)", () => {
-    const source = readGuidedFlowSource();
-
-    // Extract the allDiscussed block — the if (allDiscussed) { ... } body
-    const allDiscussedMatch = source.match(
-      /const allDiscussed = pendingSlices\.every\([\s\S]*?\n    if \(allDiscussed\) \{([\s\S]*?)\n    \}/,
-    );
-    assert.ok(!!allDiscussedMatch, "allDiscussed guard block must exist in showDiscuss()");
-
-    if (allDiscussedMatch) {
-      const body = allDiscussedMatch[1];
-      // The fix must check for pending milestones and route to showDiscussQueuedMilestone
-      assert.ok(
-        body.includes("pending") && body.includes("showDiscussQueuedMilestone"),
-        "allDiscussed block must check for pending milestones and call showDiscussQueuedMilestone before returning (#3150)",
-      );
-    }
-  });
-
-  test("13. pendingSlices.length===0 path checks for pending milestones before returning (#3150)", () => {
-    const source = readGuidedFlowSource();
-
-    // Find the pendingSlices.length === 0 guard block
-    const zeroSlicesMatch = source.match(
-      /if \(pendingSlices\.length === 0\) \{([\s\S]*?)\n  \}/,
-    );
-    assert.ok(!!zeroSlicesMatch, "pendingSlices.length === 0 guard block must exist in showDiscuss()");
-
-    if (zeroSlicesMatch) {
-      const body = zeroSlicesMatch[1];
-      // The fix must check for pending milestones and route to showDiscussQueuedMilestone
-      assert.ok(
-        body.includes("pending") && body.includes("showDiscussQueuedMilestone"),
-        "pendingSlices.length===0 block must check for pending milestones and call showDiscussQueuedMilestone before returning (#3150)",
-      );
-    }
-  });
+  // The earlier tests 6-13 source-grepped guided-flow.ts for identifier
+  // names (showDiscussQueuedMilestone, dispatchDiscussForMilestone),
+  // UI-copy strings ("[queued]", "Discuss a queued milestone"), and
+  // regex-on-function-body assertions for the #3150 routing — all
+  // structural rather than behavioural (Refs #4826). They were dropped
+  // when this file was tightened against handler-level assertions.
 });

package/src/resources/extensions/gsd/tests/discuss-tool-scope-leak.test.ts

@@ -1,77 +1,35 @@
-// GSD-2 — Regression test for #3616: discuss tool scoping must not leak into subsequent sessions
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
-
-/**
- * Bug #3616: After a discuss session narrows the active tool set via
- * setActiveTools(), the narrowed list persisted into the next auto-mode
- * session because newSession() did not restore extension tools when cwd
- * was unchanged. This caused gsd_plan_slice and other DB tools to be
- * missing from plan-slice subagent sessions.
- *
- * This test verifies the structural properties that prevent the leak:
- *   1. guided-flow.ts narrows tools ONLY for discuss-* unit types
- *   2. The narrowed set explicitly excludes gsd_plan_slice (a HEAVY_TOOL)
- *   3. agent-session.ts:newSession() has an else-branch that restores
- *      all extension tools even when cwd hasn't changed
- */
+// GSD-2 — Behavioural regression test for #3616.
+//
+// Bug: After a discuss session narrows the active tool set via setActiveTools,
+// the narrowed list persisted into the next auto-mode session because newSession()
+// did not restore extension tools when cwd was unchanged. This caused
+// gsd_plan_slice and other DB tools to be missing from plan-slice subagent
+// sessions.
+//
+// The behavioural invariant we can pin without grepping source: gsd_plan_slice
+// (a heavy planning tool) is NOT inside the discuss allowlist. The remaining
+// guarantees (newSession including all extension tools in both branches) are
+// covered by agent-session.test.ts inside packages/pi-coding-agent.
+//
+// Refs #4826 (rewrite from source-grep on guided-flow.ts / agent-session.ts).
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
 
 import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
-import { extractSourceRegion } from "./test-helpers.ts";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const guidedFlowSource = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
 
 describe("#3616 — discuss tool scoping must not leak across sessions", () => {
 	test("gsd_plan_slice is NOT in DISCUSS_TOOLS_ALLOWLIST", () => {
 		assert.ok(
 			!DISCUSS_TOOLS_ALLOWLIST.includes("gsd_plan_slice"),
-			"gsd_plan_slice should be excluded from discuss scope (it's a heavy planning tool)",
-		);
-	});
-
-	test("tool scoping only activates for discuss-* unit types", () => {
-		// The guard must be: if (unitType?.startsWith("discuss-"))
-		assert.ok(
-			guidedFlowSource.includes('unitType?.startsWith("discuss-")'),
-			"tool scoping should only trigger for discuss-* unit types",
+			`gsd_plan_slice (a heavy planning tool) must be excluded from the discuss scope; allowlist=${JSON.stringify(DISCUSS_TOOLS_ALLOWLIST)}`,
 		);
 	});
 
-	test("discuss tool scoping uses setActiveTools (not setTools) for reversibility", () => {
-		// setActiveTools changes the active subset but doesn't remove tools from
-		// the registry. newSession()'s _refreshToolRegistry can restore them.
-		assert.ok(
-			guidedFlowSource.includes("pi.setActiveTools(scopedTools)"),
-			"should use pi.setActiveTools to narrow tools (preserving registry)",
-		);
-	});
-
-	test("newSession() in agent-session.ts has defense against tool narrowing persistence", () => {
-		const agentSessionSource = readFileSync(
-			join(process.cwd(), "packages/pi-coding-agent/src/core/agent-session.ts"),
-			"utf-8",
-		);
-		const newSessionStart = agentSessionSource.indexOf("async newSession(options?:");
-		assert.ok(newSessionStart >= 0, "should find newSession");
-		const body = extractSourceRegion(agentSessionSource, "async newSession(options?:");
-
-		// Both branches (cwd-changed and cwd-unchanged) must include extension tools
-		assert.ok(
-			body.includes("includeAllExtensionTools: true"),
-			"newSession() must include all extension tools in both branches",
-		);
-
-		// Count occurrences — should be at least 2 (one per branch)
-		const matches = body.match(/includeAllExtensionTools:\s*true/g);
+	test("DISCUSS_TOOLS_ALLOWLIST is non-empty (sanity)", () => {
 		assert.ok(
-			matches && matches.length >= 2,
-			`expected >=2 includeAllExtensionTools:true in newSession(), got ${matches?.length ?? 0}`,
+			DISCUSS_TOOLS_ALLOWLIST.length > 0,
+			"discuss scope should include at least one tool — empty allowlist would break /gsd discuss",
 		);
 	});
 });

package/src/resources/extensions/gsd/tests/doctor-orphan-milestone-4996.test.ts

@@ -0,0 +1,100 @@
+// GSD Extension — Regression test for #4996: doctor orphan milestone dir check
+// Verifies that checkRuntimeHealth reports orphan_milestone_dir for empty stub
+// dirs with no DB row, does not report populated dirs, and does not report
+// legitimate in-flight worktree-only milestone dirs.
+
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { checkRuntimeHealth } from "../doctor-runtime-checks.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+import { invalidateAllCaches } from "../cache.ts";
+import type { DoctorIssue, DoctorIssueCode } from "../doctor-types.ts";
+
+function makeBase(prefix = "gsd-doctor-orphan-"): string {
+  const base = mkdtempSync(join(tmpdir(), prefix));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function stubDir(base: string, mid: string): void {
+  mkdirSync(join(base, ".gsd", "milestones", mid, "slices"), { recursive: true });
+}
+
+function populateDir(base: string, mid: string): void {
+  mkdirSync(join(base, ".gsd", "milestones", mid), { recursive: true });
+  writeFileSync(join(base, ".gsd", "milestones", mid, `${mid}-CONTEXT.md`), `# ${mid}\n`);
+}
+
+describe("gsd_doctor orphan milestone directory check (#4996)", () => {
+  let base: string;
+
+  afterEach(() => {
+    try { closeDatabase(); } catch { /* ignore */ }
+    try { invalidateAllCaches(); } catch { /* ignore */ }
+    try { rmSync(base, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it("(a) empty stub dir with no DB row is reported as orphan_milestone_dir", async () => {
+    base = makeBase();
+    stubDir(base, "M003");
+
+    const issues: DoctorIssue[] = [];
+    const fixes: string[] = [];
+    await checkRuntimeHealth(base, issues, fixes, () => false);
+
+    const orphan = issues.find(i => i.code === "orphan_milestone_dir" && i.unitId === "M003");
+    assert.ok(orphan, "should report orphan_milestone_dir for empty stub");
+    assert.equal(orphan?.severity, "warning");
+    assert.equal(orphan?.fixable, true);
+    assert.ok(orphan?.message.includes("M003"), "message should name the milestone");
+  });
+
+  it("(b) populated milestone dir is NOT reported", async () => {
+    base = makeBase();
+    populateDir(base, "M001");
+
+    const issues: DoctorIssue[] = [];
+    const fixes: string[] = [];
+    await checkRuntimeHealth(base, issues, fixes, () => false);
+
+    const orphan = issues.find(i => i.code === "orphan_milestone_dir" && i.unitId === "M001");
+    assert.ok(!orphan, "populated milestone dir must not be reported as orphan");
+  });
+
+  it("(c) worktree-only milestone (no content files, no DB row, but worktree exists) is NOT reported", async () => {
+    base = makeBase();
+    stubDir(base, "M003");
+    // Simulate a legitimate in-flight worktree
+    mkdirSync(join(base, ".gsd", "worktrees", "M003"), { recursive: true });
+
+    const issues: DoctorIssue[] = [];
+    const fixes: string[] = [];
+    await checkRuntimeHealth(base, issues, fixes, () => false);
+
+    const orphan = issues.find(i => i.code === "orphan_milestone_dir" && i.unitId === "M003");
+    assert.ok(!orphan, "milestone with a worktree must not be reported as orphan");
+  });
+
+  it("(d) queued DB row (in-flight ID) is NOT reported as orphan", async () => {
+    base = makeBase();
+    stubDir(base, "M003");
+    const dbPath = join(base, ".gsd", "gsd.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M003", status: "queued" });
+
+    const issues: DoctorIssue[] = [];
+    const fixes: string[] = [];
+    await checkRuntimeHealth(base, issues, fixes, () => false);
+
+    const orphan = issues.find(i => i.code === "orphan_milestone_dir" && i.unitId === "M003");
+    assert.ok(!orphan, "queued DB row must block orphan report (in-flight race protection)");
+  });
+});