gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/tests/init-prefs-routing.test.ts

@@ -12,7 +12,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { mapInitPrefsToWizardShape } from "../init-wizard.ts";
-import { writePreferencesFile } from "../commands-prefs-wizard.ts";
+import { handlePrefsWizard, writePreferencesFile } from "../commands-prefs-wizard.ts";
 
 test("mapInitPrefsToWizardShape — full roundtrip with all fields", () => {
   const out = mapInitPrefsToWizardShape({
@@ -123,6 +123,69 @@ test("writePreferencesFile — falls back to default body for new files", async
   }
 });
 
+test("handlePrefsWizard — Advanced config writes min_request_interval_ms", async () => {
+  const tmp = mkdtempSync(join(tmpdir(), "gsd-init-prefs-routing-"));
+  const path = join(tmp, "PREFERENCES.md");
+
+  try {
+    const selectResponses = [
+      "Advanced",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "(keep current)",
+      "── Save & Exit ──",
+    ];
+    const inputResponses = ["250"];
+    const ctx = {
+      ui: {
+        notify: () => {},
+        select: async (_label: string, options: string[]) => {
+          const response = selectResponses.shift();
+          if (response === undefined) {
+            throw new Error(
+              `Unexpected extra select prompt in handlePrefsWizard flow: selectResponses queue exhausted for "${_label}" ` +
+                "(expected no additional select prompts)",
+            );
+          }
+          if (response === "Advanced") {
+            const advancedOption = options.find((option) => option.startsWith("Advanced"));
+            if (!advancedOption) {
+              throw new Error(`Expected an "Advanced" option in "${_label}" menu`);
+            }
+            return advancedOption;
+          }
+          return response;
+        },
+        input: async () => {
+          const response = inputResponses.shift();
+          if (response === undefined) {
+            throw new Error(
+              "Unexpected extra input prompt in handlePrefsWizard flow: inputResponses queue exhausted " +
+                "(expected no additional input prompts)",
+            );
+          }
+          return response;
+        },
+      },
+      waitForIdle: async () => {},
+      reload: async () => {},
+    };
+
+    await handlePrefsWizard(ctx as any, "project", {}, { pathOverride: path });
+
+    assert.equal(selectResponses.length, 0, "Expected all queued selectResponses to be consumed");
+    assert.equal(inputResponses.length, 0, "Expected all queued inputResponses to be consumed");
+    const content = readFileSync(path, "utf-8");
+    assert.match(content, /^min_request_interval_ms:\s*250$/m);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
 // ─── Regression tests from #4457 codex adversarial review ──────────────────
 
 test("init — Step 9b shape: 'not_yet' option is recognized as defer (#4457 review)", async () => {

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

@@ -7,7 +7,7 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -21,6 +21,7 @@ import {
   getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
   syncGsdStateToWorktree,
+  _resetAutoWorktreeOriginalBaseForTests,
 } from "../../auto-worktree.ts";
 
 // Note: execSync is used intentionally in tests for git operations with
@@ -142,6 +143,54 @@ describe("auto-worktree lifecycle", () => {
     teardownAutoWorktree(tempDir, "M003");
   });
 
+  test("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-")));
+    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 {
+      const wtPath = createAutoWorktree(tempDir, "M001");
+      const realWtPath = realpathSync(wtPath);
+      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+
+      _resetAutoWorktreeOriginalBaseForTests();
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+
+      assert.ok(isInAutoWorktree(tempDir), "structural detection works without module originalBase");
+      const resolved = getAutoWorktreePath(realWtPath, "M001");
+      assert.ok(resolved, "existing worktree is found when basePath is the worktree path");
+      assert.equal(realpathSync(resolved!), realWtPath);
+      assert.equal(existsSync(join(realWtPath, ".gsd", "worktrees", "M001")), false);
+
+      enterAutoWorktree(tempDir, "M001");
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+      assert.deepStrictEqual(
+        getActiveAutoWorktreeContext(),
+        {
+          originalBase: tempDir,
+          worktreeName: "M001",
+          branch: "milestone/M001",
+        },
+        "active context is detected from a symlink-resolved 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");
@@ -345,4 +394,26 @@ describe("auto-worktree lifecycle", () => {
       teardownAutoWorktree(tempDir, "M003");
     }
   });
+
+  test("#2482: throws GSDError when repo has no commits", () => {
+    // Create a bare git init with no commits — HEAD is invalid
+    tempDir = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-empty-")));
+    run("git init", tempDir);
+    run("git config user.email test@test.com", tempDir);
+    run("git config user.name Test", tempDir);
+
+    assert.throws(
+      () => createAutoWorktree(tempDir, "M001"),
+      (err: unknown) => {
+        assert.ok(err instanceof Error, "should throw an Error");
+        assert.ok("code" in err, "should have a code property (GSDError)");
+        assert.strictEqual((err as { code: string }).code, "GSD_GIT_ERROR");
+        assert.ok(
+          err.message.includes("repository has no commits yet"),
+          `message should mention no commits, got: ${err.message}`,
+        );
+        return true;
+      },
+    );
+  });
 });

package/src/resources/extensions/gsd/tests/integration/token-savings.test.ts

@@ -338,27 +338,4 @@ console.log('\n=== token-savings: quality — correct scoping, no cross-contamin
   rmSync(base, { recursive: true, force: true });
 }
 
-// ═══════════════════════════════════════════════════════════════════════════
-// Test: Fixture data realism — sufficient volume and distribution
-// ═══════════════════════════════════════════════════════════════════════════
-
-console.log('\n=== token-savings: fixture data realism ===');
-{
-  // Verify fixture generators produce sufficient volume
-  assert.ok(DECISIONS_COUNT >= 20, `decisions count ≥ 20 (actual: ${DECISIONS_COUNT})`);
-  assert.ok(REQUIREMENTS_COUNT >= 20, `requirements count ≥ 20 (actual: ${REQUIREMENTS_COUNT})`);
-  assert.ok(MILESTONES.length >= 3, `milestones ≥ 3 (actual: ${MILESTONES.length})`);
-  assert.ok(SLICE_ASSIGNMENTS.length >= 5, `slice assignments ≥ 5 (actual: ${SLICE_ASSIGNMENTS.length})`);
-
-  // Verify markdown content is substantial
-  assert.ok(decisionsMarkdown.length > 1000, `decisions markdown > 1000 chars (actual: ${decisionsMarkdown.length})`);
-  assert.ok(requirementsMarkdown.length > 1000, `requirements markdown > 1000 chars (actual: ${requirementsMarkdown.length})`);
-
-  // Verify content structure
-  assert.match(decisionsMarkdown, /\| D001 \|/, 'decisions markdown has D001');
-  assert.match(decisionsMarkdown, /\| D024 \|/, 'decisions markdown has D024');
-  assert.match(requirementsMarkdown, /### R001/, 'requirements markdown has R001');
-  assert.match(requirementsMarkdown, /### R021/, 'requirements markdown has R021');
-}
-
 // ─── Report ────────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/memory-store.test.ts

@@ -4,6 +4,11 @@ import {
   isDbAvailable,
   _getAdapter,
 } from '../gsd-db.ts';
+import {
+  _resetLogs,
+  peekLogs,
+  setStderrLoggingEnabled,
+} from '../workflow-logger.ts';
 import {
   getActiveMemories,
   getActiveMemoriesRanked,
@@ -329,3 +334,126 @@ test('memory-store: schema includes memories table', () => {
 
   closeDatabase();
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// regression #4967 — createMemory must not silently swallow SQL errors
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-store: createMemory throws on memory-table SQL errors (regression #4967)', () => {
+  openDatabase(':memory:');
+
+  const adapter = _getAdapter()!;
+  // Drop FTS + dependents first to satisfy SQLite's trigger ordering, then
+  // the base memories table. IF EXISTS makes setup robust against schema
+  // versions that may not have created every dependent (e.g. embeddings).
+  adapter.prepare('DROP TABLE IF EXISTS memory_embeddings').run();
+  adapter.prepare('DROP TABLE IF EXISTS memories_fts').run();
+  adapter.prepare('DROP TABLE IF EXISTS memories').run();
+
+  // Pre-fix behaviour: returns null and the caller has no idea why.
+  // Post-fix behaviour: throws so the caller can surface the real SQL message.
+  assert.throws(
+    () => createMemory({ category: 'gotcha', content: 'broken store' }),
+    /memories|no such table/i,
+    'createMemory must surface SQL errors instead of returning null',
+  );
+
+  closeDatabase();
+});
+
+test('memory-store: VACUUM retry rolls back partial memory and logs recovery', () => {
+  openDatabase(':memory:');
+
+  const adapter = _getAdapter()!;
+  const originalPrepareMethod = adapter.prepare;
+  const originalPrepare = adapter.prepare.bind(adapter);
+  const previousStderrLogging = setStderrLoggingEnabled(false);
+  const streamAny = process.stderr as unknown as {
+    write: (chunk: string | Uint8Array, ...rest: unknown[]) => boolean;
+  };
+  const originalStderrWrite = streamAny.write.bind(streamAny);
+  let selectFailures = 0;
+  let vacuumRuns = 0;
+  _resetLogs();
+
+  adapter.prepare = ((sql: string) => {
+    if (sql === 'SELECT seq FROM memories WHERE id = :id' && selectFailures === 0) {
+      const stmt = originalPrepare(sql);
+      return {
+        run: (...params: unknown[]) => stmt.run(...params),
+        get: (..._params: unknown[]) => {
+          selectFailures++;
+          throw new Error('database disk image is malformed');
+        },
+        all: (...params: unknown[]) => stmt.all(...params),
+      };
+    }
+
+    if (sql === 'VACUUM') {
+      const stmt = originalPrepare(sql);
+      return {
+        run: (...params: unknown[]) => {
+          vacuumRuns++;
+          return stmt.run(...params);
+        },
+        get: (...params: unknown[]) => stmt.get(...params),
+        all: (...params: unknown[]) => stmt.all(...params),
+      };
+    }
+
+    return originalPrepare(sql);
+  }) as typeof adapter.prepare;
+  streamAny.write = (): boolean => true;
+
+  try {
+    const id = createMemory({ category: 'gotcha', content: 'recover without duplicate' });
+    assert.equal(id, 'MEM001', 'retry should create a single first memory');
+
+    const rows = adapter.prepare('SELECT id FROM memories ORDER BY seq').all();
+    assert.deepStrictEqual(
+      rows.map((row) => row['id']),
+      ['MEM001'],
+      'failed first attempt should not leave a live _TMP_ memory behind',
+    );
+    assert.equal(selectFailures, 1, 'test should simulate one malformed SELECT after INSERT');
+    assert.equal(vacuumRuns, 1, 'malformed recovery should run VACUUM once');
+    assert.ok(
+      peekLogs().some((entry) =>
+        entry.component === 'memory-store' &&
+        entry.message === 'recovered malformed memory store via VACUUM'
+      ),
+      'successful VACUUM recovery should be emitted to the workflow logger',
+    );
+  } finally {
+    adapter.prepare = originalPrepareMethod;
+    streamAny.write = originalStderrWrite;
+    setStderrLoggingEnabled(previousStderrLogging);
+    _resetLogs();
+    closeDatabase();
+  }
+});
+
+test('memory-store: applyMemoryActions stays non-fatal when memory store is broken (regression #4967)', () => {
+  openDatabase(':memory:');
+
+  const adapter = _getAdapter()!;
+  // Drop FTS + dependents first to satisfy SQLite's trigger ordering, then
+  // the base memories table. IF EXISTS makes setup robust against schema
+  // versions that may not have created every dependent (e.g. embeddings).
+  adapter.prepare('DROP TABLE IF EXISTS memory_embeddings').run();
+  adapter.prepare('DROP TABLE IF EXISTS memories_fts').run();
+  adapter.prepare('DROP TABLE IF EXISTS memories').run();
+
+  // applyMemoryActions wraps createMemory in a transaction with an outer
+  // catch. Even with createMemory now throwing, applyMemoryActions must not
+  // crash the auto-mode flow that calls it (memory extraction is best-effort).
+  const actions: MemoryAction[] = [
+    { action: 'CREATE', category: 'gotcha', content: 'inside-transaction call' },
+  ];
+  assert.doesNotThrow(
+    () => applyMemoryActions(actions),
+    'applyMemoryActions must absorb thrown errors so callers continue',
+  );
+
+  closeDatabase();
+});

package/src/resources/extensions/gsd/tests/memory-tools.test.ts

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
-import { closeDatabase, openDatabase } from '../gsd-db.ts';
+import { _getAdapter, closeDatabase, openDatabase } from '../gsd-db.ts';
 import { createMemory, supersedeMemory } from '../memory-store.ts';
 import {
   executeGsdGraph,
@@ -293,3 +293,35 @@ test('memory-tools: gsd_graph errors when DB is closed', () => {
   assert.ok(result.isError);
   assert.equal(result.details.error, 'db_unavailable');
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// regression #4967 — capture_thought must surface real SQL errors
+// ═══════════════════════════════════════════════════════════════════════════
+
+test('memory-tools: capture_thought surfaces underlying SQL error (regression #4967)', () => {
+  openDatabase(':memory:');
+
+  // Simulate the real-world failure mode where the memories table is gone.
+  // The original bug was a "database disk image is malformed" on the memory
+  // store; dropping the table produces a deterministic statement-time SQL
+  // error of the same shape — a thrown sqlite error during INSERT.
+  const adapter = _getAdapter()!;
+  adapter.prepare('DROP TABLE IF EXISTS memory_embeddings').run();
+  adapter.prepare('DROP TABLE IF EXISTS memories_fts').run();
+  adapter.prepare('DROP TABLE IF EXISTS memories').run();
+
+  const result = executeMemoryCapture({
+    category: 'gotcha',
+    content: 'should reveal the real reason',
+  });
+
+  assert.ok(result.isError, 'broken store should produce an error result');
+  assert.equal(result.details.operation, 'memory_capture');
+
+  const err = String(result.details.error ?? '');
+  assert.notEqual(err, 'create_failed', 'must not collapse to opaque create_failed');
+  assert.ok(err.length > 0, 'error detail must be populated');
+  assert.match(err, /memories|no such table/i, 'error must reference the underlying SQL fault');
+
+  closeDatabase();
+});

package/src/resources/extensions/gsd/tests/merge-self-branch-guard.test.ts

@@ -0,0 +1,124 @@
+// gsd-2 / merge-self-branch-guard.test.ts — regression for #5024
+//
+// mergeMilestoneToMain() must fail closed when the resolved integration
+// branch is the same ref as the milestone branch. Stale or corrupt
+// integration metadata (e.g. integrationBranch recorded as "milestone/<MID>")
+// would otherwise let the squash merge resolve to a self-merge: the post-
+// merge no-op safety check (#1792) compares main vs milestone and finds an
+// empty diff (because they're the same ref), so the helper returns success
+// for work that never landed on a distinct integration branch.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { mergeMilestoneToMain } from "../auto-worktree.ts";
+import { _resetServiceCache } from "../worktree.ts";
+import { _clearGsdRootCache } from "../paths.ts";
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "merge-self-guard-")));
+  git(["init"], dir);
+  git(["config", "user.email", "test@test.com"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  git(["add", "."], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+  return dir;
+}
+
+function assertSelfMergeRefIsRejected(recordedIntegrationBranch: string): void {
+  const savedCwd = process.cwd();
+  let tempDir = "";
+
+  // Isolate from user's global preferences so prefs.main_branch can't
+  // override the corrupt-metadata path under test.
+  const originalHome = process.env.HOME;
+  const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-fake-home-")));
+  process.env.HOME = fakeHome;
+  _clearGsdRootCache();
+  _resetServiceCache();
+
+  try {
+    tempDir = createTempRepo();
+
+    // Plant corrupt integration metadata: integrationBranch points at the
+    // milestone branch itself. Commit it so mergeMilestoneToMain's
+    // autoCommitDirtyState pre-step has nothing to capture and the
+    // postcondition (no new commits) cleanly reflects the guard.
+    const msDir = join(tempDir, ".gsd", "milestones", "M001");
+    mkdirSync(msDir, { recursive: true });
+    writeFileSync(
+      join(msDir, "M001-META.json"),
+      JSON.stringify({ integrationBranch: recordedIntegrationBranch }),
+    );
+    git(["add", "."], tempDir);
+    git(["commit", "-m", "chore: plant corrupt M001 meta"], tempDir);
+
+    // Create the milestone branch ref so any pre-guard branch operations
+    // wouldn't fail for unrelated reasons.
+    git(["branch", "milestone/M001"], tempDir);
+
+    const mainHeadBefore = git(["rev-parse", "main"], tempDir);
+    const milestoneHeadBefore = git(["rev-parse", "milestone/M001"], tempDir);
+
+    process.chdir(tempDir);
+
+    assert.throws(
+      () => mergeMilestoneToMain(tempDir, "M001", ""),
+      (err: unknown) => {
+        assert.ok(err instanceof Error, "expected an Error to be thrown");
+        assert.match(
+          err.message,
+          /self-merge|same ref/i,
+          "error message should explain the self-merge refusal",
+        );
+        return true;
+      },
+    );
+
+    // Postcondition: neither branch should have been advanced by a merge
+    // commit. The guard fires before checkout/merge, so both refs must be
+    // unchanged from their pre-call state.
+    const mainHeadAfter = git(["rev-parse", "main"], tempDir);
+    const milestoneHeadAfter = git(["rev-parse", "milestone/M001"], tempDir);
+    assert.equal(mainHeadAfter, mainHeadBefore, "main must not have advanced");
+    assert.equal(
+      milestoneHeadAfter,
+      milestoneHeadBefore,
+      "milestone branch must not have advanced",
+    );
+  } finally {
+    process.chdir(savedCwd);
+    process.env.HOME = originalHome;
+    _clearGsdRootCache();
+    _resetServiceCache();
+    if (tempDir && existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+    rmSync(fakeHome, { recursive: true, force: true });
+  }
+}
+
+test("mergeMilestoneToMain refuses exact milestone branch self-merge metadata (#5024)", () => {
+  assertSelfMergeRefIsRejected("milestone/M001");
+});
+
+test("mergeMilestoneToMain refuses refs/heads milestone branch self-merge metadata (#5024)", () => {
+  assertSelfMergeRefIsRejected("refs/heads/milestone/M001");
+});

package/src/resources/extensions/gsd/tests/milestone-id-gap-reuse-4996.test.ts

@@ -0,0 +1,152 @@
+// GSD Extension — Regression test for #4996: ghost milestone ID reuse
+// Verifies that isReusableGhostMilestone correctly identifies reclaim-safe stub dirs,
+// and that nextMilestoneIdReserved (guided-flow) prefers the lowest reusable ghost
+// over max+1. Also covers the race-window regression: a queued DB row must NOT be reused.
+
+import { describe, it, beforeEach, 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 { isReusableGhostMilestone } from "../state.ts";
+import { nextMilestoneIdReserved } from "../milestone-id-reservation.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+import { clearReservedMilestoneIds, findMilestoneIds } from "../milestone-ids.ts";
+import { invalidateAllCaches } from "../cache.ts";
+
+function makeBase(prefix = "gsd-gap-4996-"): string {
+  const base = mkdtempSync(join(tmpdir(), prefix));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function stubDir(base: string, mid: string): void {
+  // Create an empty stub — the phantom pattern
+  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} Context\n`);
+}
+
+describe("isReusableGhostMilestone (#4996)", () => {
+  let base: string;
+
+  afterEach(() => {
+    try { closeDatabase(); } catch { /* ignore */ }
+    try { invalidateAllCaches(); } catch { /* ignore */ }
+    try { rmSync(base, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it("(a) fails closed when the DB is unavailable", () => {
+    base = makeBase();
+    stubDir(base, "M003");
+    assert.equal(isReusableGhostMilestone(base, "M003"), false, "closed DB should block reusable-ghost claims");
+  });
+
+  it("(b) empty stub dir with an open DB and no DB row is reusable", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    stubDir(base, "M003");
+    assert.ok(isReusableGhostMilestone(base, "M003"), "empty stub with no DB row should be reusable");
+  });
+
+  it("(c) queued DB row with no content must NOT be reusable (race window regression)", () => {
+    base = makeBase();
+    stubDir(base, "M003");
+    const dbPath = join(base, ".gsd", "gsd.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M003", status: "queued" });
+    // Even though no content files exist, the queued DB row means an in-flight discuss
+    // is reserving this ID — it must not be reclaimed.
+    assert.ok(!isReusableGhostMilestone(base, "M003"), "queued DB row must block reuse");
+  });
+
+  it("(d) populated milestone dir is not reusable", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    populateDir(base, "M001");
+    assert.ok(!isReusableGhostMilestone(base, "M001"), "populated dir must not be reusable");
+  });
+
+  it("(e) stub dir with worktree is not reusable (legitimate in-flight)", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    stubDir(base, "M003");
+    // Simulate an existing worktree
+    mkdirSync(join(base, ".gsd", "worktrees", "M003"), { recursive: true });
+    assert.ok(!isReusableGhostMilestone(base, "M003"), "dir with worktree must not be reusable");
+  });
+
+  it("(f) active DB row makes dir not reusable", () => {
+    base = makeBase();
+    stubDir(base, "M003");
+    const dbPath = join(base, ".gsd", "gsd.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M003", status: "active" });
+    assert.ok(!isReusableGhostMilestone(base, "M003"), "active DB row must block reuse");
+  });
+});
+
+describe("primary regression: M003/M004 stubs returned as next ID (#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("M001/M002 populated + M003/M004 stubs → isReusableGhostMilestone returns true for M003 and M004", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    populateDir(base, "M001");
+    populateDir(base, "M002");
+    stubDir(base, "M003");
+    stubDir(base, "M004");
+
+    assert.ok(isReusableGhostMilestone(base, "M003"), "M003 should be identified as reusable ghost");
+    assert.ok(isReusableGhostMilestone(base, "M004"), "M004 should be identified as reusable ghost");
+    assert.ok(!isReusableGhostMilestone(base, "M001"), "M001 should not be reusable");
+    assert.ok(!isReusableGhostMilestone(base, "M002"), "M002 should not be reusable");
+
+    const nextId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+    assert.equal(nextId, "M003", "ID reservation should select the lowest reusable ghost");
+  });
+
+  it("when all dirs are populated, no ghost exists and the function returns false for all", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    populateDir(base, "M001");
+    populateDir(base, "M002");
+
+    assert.ok(!isReusableGhostMilestone(base, "M001"), "M001 is populated, not reusable");
+    assert.ok(!isReusableGhostMilestone(base, "M002"), "M002 is populated, not reusable");
+
+    const nextId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+    assert.equal(nextId, "M003", "ID reservation should fall back to max+1 when no ghost is reusable");
+  });
+
+  it("does not return an already-reserved reusable ghost twice", () => {
+    base = makeBase();
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    stubDir(base, "M001");
+
+    const firstId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+    const secondId = nextMilestoneIdReserved(findMilestoneIds(base), false, base);
+
+    assert.equal(firstId, "M001", "first reservation should reuse the ghost");
+    assert.equal(secondId, "M002", "second reservation must skip the already-reserved ghost");
+  });
+});