gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

package/src/resources/extensions/gsd/tests/auto-start-bootstrap-await-3420.test.ts

@@ -0,0 +1,141 @@
+/**
+ * auto-start-bootstrap-await-3420.test.ts — Regression test for #3420.
+ *
+ * Bug: In bootstrapAutoSession, when state.phase === "pre-planning" and no
+ * context file exists, showSmartEntry is called to dispatch a discuss workflow.
+ * showSmartEntry calls dispatchWorkflow which calls pi.sendMessage() — a
+ * fire-and-forget call that returns immediately. The LLM discussion runs
+ * asynchronously in a separate turn.
+ *
+ * The bug: after showSmartEntry returns (before the LLM has run), the code
+ * immediately calls invalidateAllCaches() + deriveState() + checks postState.
+ * Since the discussion hasn't run yet, postState.phase is still "pre-planning"
+ * and the context check fails, producing the warning:
+ *   "Discussion completed but milestone context is still missing. Run /gsd to try again."
+ *
+ * The discussion never ran — the warning fires immediately.
+ *
+ * Fix: bootstrapAutoSession must return false (release lock) after showSmartEntry
+ * dispatches the workflow. The checkAutoStartAfterDiscuss callback in guided-flow.ts
+ * already handles re-entering auto-mode when the discussion completes.
+ *
+ * This test verifies the fix by asserting that the pre-planning !hasContext block
+ * does NOT contain a postState phase check after showSmartEntry — it must
+ * return false immediately to let the async dispatch complete.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const sourcePath = join(import.meta.dirname, "..", "auto-start.ts");
+const source = readFileSync(sourcePath, "utf-8");
+
+test("bootstrapAutoSession: pre-planning no-context path does NOT check postState immediately after showSmartEntry (#3420)", () => {
+  // Find the pre-planning block that handles the case where context is missing.
+  // This block dispatches showSmartEntry which is async (fire-and-forget via pi.sendMessage).
+  // After the dispatch, checking postState.phase immediately is premature — the
+  // LLM discussion hasn't run yet. The block should return false instead.
+  const prePlanningNoContextBlock = source.match(
+    /\/\/ Active milestone exists but has no roadmap\s*\n\s*if\s*\(\s*state\.phase\s*===\s*"pre-planning"\s*\)([\s\S]*?)\/\/ Active milestone has CONTEXT-DRAFT/,
+  );
+  assert.ok(
+    !!prePlanningNoContextBlock,
+    "auto-start.ts must have the pre-planning handler block before needs-discussion",
+  );
+
+  const block = prePlanningNoContextBlock![1];
+
+  // The block must call showSmartEntry when !hasContext
+  assert.ok(
+    block.includes("showSmartEntry"),
+    "pre-planning !hasContext block must call showSmartEntry to dispatch the discuss workflow",
+  );
+
+  // FAILING ASSERTION (before fix): after showSmartEntry, the block must NOT
+  // immediately check postState.phase — that check fires before the LLM runs.
+  // Instead, it must return false (release lock) so the async dispatch can complete.
+  // The warning "Discussion completed but milestone context is still missing"
+  // fires prematurely when this postState check exists.
+  assert.ok(
+    !block.includes("Discussion completed but milestone context is still missing"),
+    "pre-planning !hasContext block must NOT check postState.phase immediately after showSmartEntry — " +
+    "the dispatch is async (pi.sendMessage is fire-and-forget) and the discussion hasn't run yet; " +
+    "return false instead so checkAutoStartAfterDiscuss can re-enter auto-mode after discussion completes (#3420)",
+  );
+});
+
+test("bootstrapAutoSession: complete/no-milestone path does NOT check postState immediately after showSmartEntry (#3420)", () => {
+  // Find the complete/no-milestone block
+  const completeBlock = source.match(
+    /\/\/ No active work — start a new milestone via discuss flow\s*\n\s*if\s*\(!state\.activeMilestone\s*\|\|\s*state\.phase\s*===\s*"complete"\s*\)([\s\S]*?)\/\/ Active milestone exists but has no roadmap/,
+  );
+  assert.ok(
+    !!completeBlock,
+    "auto-start.ts must have the complete/no-milestone handler block",
+  );
+
+  const block = completeBlock![1];
+
+  // The block must call showSmartEntry
+  assert.ok(
+    block.includes("showSmartEntry"),
+    "complete/no-milestone block must call showSmartEntry",
+  );
+
+  // After showSmartEntry dispatches, checking postState.phase is premature —
+  // the LLM hasn't had a turn yet. The block should return false.
+  // Specifically, the "no milestone context was written" warning fires too early.
+  assert.ok(
+    !block.includes("Discussion completed but no milestone context was written"),
+    "complete/no-milestone block must NOT check postState.phase immediately after showSmartEntry dispatch — " +
+    "return false instead so the async LLM turn can complete (#3420)",
+  );
+});
+
+test("bootstrapAutoSession: showSmartEntry in pre-planning path is followed by releaseLockAndReturn, not postState check (#3420)", () => {
+  // After the fix, the pre-planning !hasContext branch should call showSmartEntry
+  // and then immediately return releaseLockAndReturn() — not check postState.
+  const prePlanningNoContextBlock = source.match(
+    /\/\/ Active milestone exists but has no roadmap\s*\n\s*if\s*\(\s*state\.phase\s*===\s*"pre-planning"\s*\)([\s\S]*?)\/\/ Active milestone has CONTEXT-DRAFT/,
+  );
+  assert.ok(!!prePlanningNoContextBlock, "pre-planning handler block found");
+
+  const block = prePlanningNoContextBlock![1];
+
+  // After the fix, the !hasContext branch ends with releaseLockAndReturn
+  assert.ok(
+    block.includes("releaseLockAndReturn"),
+    "pre-planning !hasContext block must call releaseLockAndReturn() after showSmartEntry dispatch (#3420)",
+  );
+
+  // The showSmartEntry call must appear before releaseLockAndReturn
+  const showSmartEntryIdx = block.indexOf("showSmartEntry");
+  const releaseLockIdx = block.indexOf("releaseLockAndReturn");
+  assert.ok(
+    showSmartEntryIdx > -1 && releaseLockIdx > -1,
+    "both showSmartEntry and releaseLockAndReturn must appear in the block",
+  );
+  assert.ok(
+    showSmartEntryIdx < releaseLockIdx,
+    "showSmartEntry must appear before releaseLockAndReturn in pre-planning !hasContext block",
+  );
+
+  // There must be NO invalidateAllCaches between showSmartEntry and releaseLockAndReturn
+  // (invalidateAllCaches + deriveState after showSmartEntry is the buggy premature check)
+  const afterShowSmartEntry = block.substring(showSmartEntryIdx);
+  const cacheInvalidateIdx = afterShowSmartEntry.indexOf("invalidateAllCaches");
+  const releaseFromShowIdx = afterShowSmartEntry.indexOf("releaseLockAndReturn");
+
+  // If invalidateAllCaches appears, it must appear AFTER releaseLockAndReturn
+  // (which is impossible since releaseLockAndReturn returns) — so invalidateAllCaches
+  // must not appear at all between showSmartEntry and the end of the !hasContext block.
+  if (cacheInvalidateIdx !== -1) {
+    assert.ok(
+      cacheInvalidateIdx > releaseFromShowIdx,
+      "invalidateAllCaches must NOT appear between showSmartEntry and releaseLockAndReturn — " +
+      "this is the premature postState check that causes #3420",
+    );
+  }
+});

package/src/resources/extensions/gsd/tests/auto-start-clean-runtime-db-gated.test.ts

@@ -0,0 +1,64 @@
+// GSD-2 auto-start regression test: cleanStaleRuntimeUnits is DB-gated (#4663)
+//
+// Source-level structural check that the stale-runtime-cleanup predicate in
+// auto-start.ts consults DB status when available instead of treating a
+// SUMMARY-file on disk as proof of milestone completion. Pairs with #4658 /
+// PR #4660 fix in auto-dispatch + auto-recovery.
+
+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 { extractSourceRegion } from "./test-helpers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourceFile = join(__dirname, "..", "auto-start.ts");
+
+describe("auto-start cleanStaleRuntimeUnits DB gating (#4663)", () => {
+  const source = readFileSync(sourceFile, "utf-8");
+
+  test("imports isClosedStatus for DB-status check", () => {
+    assert.match(
+      source,
+      /import\s*\{\s*isClosedStatus\s*\}\s*from\s*["']\.\/status-guards/,
+    );
+  });
+
+  test("cleanStaleRuntimeUnits is called after openProjectDbIfPresent", () => {
+    const openDbIdx = source.indexOf("await openProjectDbIfPresent(base)");
+    assert.ok(openDbIdx > -1, "openProjectDbIfPresent should be called in auto-start");
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(", openDbIdx);
+    assert.ok(
+      cleanIdx > -1,
+      "cleanStaleRuntimeUnits must run AFTER openProjectDbIfPresent so predicate can consult DB",
+    );
+  });
+
+  test("cleanStaleRuntimeUnits predicate consults DB status when available", () => {
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
+    assert.ok(cleanIdx > -1);
+    const snippet = extractSourceRegion(source, "cleanStaleRuntimeUnits(");
+    assert.match(
+      snippet,
+      /isDbAvailable\(\)/,
+      "predicate must branch on DB availability",
+    );
+    assert.match(
+      snippet,
+      /isClosedStatus\(/,
+      "predicate must check DB status via isClosedStatus",
+    );
+  });
+
+  test("cleanStaleRuntimeUnits predicate still falls back to SUMMARY-file when DB unavailable", () => {
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
+    assert.ok(cleanIdx > -1);
+    const snippet = extractSourceRegion(source, "cleanStaleRuntimeUnits(");
+    assert.match(
+      snippet,
+      /resolveMilestoneFile\(base,\s*mid,\s*["']SUMMARY["']\)/,
+      "legacy FS-fallback branch should still use SUMMARY file presence",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/auto-start-cold-db-bootstrap.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -13,7 +13,7 @@ console.log("\n=== #2841: cold DB opened before initial deriveState ===");
 const helperIdx = src.indexOf("async function openProjectDbIfPresent");
 assertTrue(helperIdx >= 0, "auto-start.ts defines a helper for pre-derive DB open (#2841)");
 
-const helperRegion = helperIdx >= 0 ? src.slice(helperIdx, helperIdx + 500) : "";
+const helperRegion = helperIdx >= 0 ? extractSourceRegion(src, "async function openProjectDbIfPresent") : "";
 assertTrue(
   helperRegion.includes("resolveProjectRootDbPath(basePath)"),
   "pre-derive DB helper resolves the project-root DB path (#2841)",

package/src/resources/extensions/gsd/tests/auto-start-needs-discussion.test.ts

@@ -157,62 +157,19 @@ describe("auto-start-needs-discussion (#1726)", () => {
     }
   });
 
-  test("6. No infinite loop: needs-discussion always routes to showSmartEntry", () => {
-    const source = readAutoStartSource();
-
-    // Verify needs-discussion does NOT appear in auto-dispatch trigger conditions
-    // within auto-start.ts. The only place needs-discussion should appear is in
-    // the showSmartEntry routing block.
-    const survivorSection = source.match(
-      /\/\/ Milestone branch recovery.*?let hasSurvivorBranch = false;[\s\S]*?if\s*\([^)]*state\.phase[^)]*\)\s*\{/,
-    );
-    if (survivorSection) {
-      assert.ok(
-        !survivorSection[0].includes("needs-discussion"),
-        "survivor branch phase condition must not mention needs-discussion",
-      );
-    }
-
-    // Verify needs-discussion IS handled inside the !hasSurvivorBranch block
-    const notSurvivorBlock = source.match(
-      /if\s*\(!hasSurvivorBranch\)\s*\{([\s\S]*?)\/\/ Unreachable safety check/,
-    );
-    assert.ok(!!notSurvivorBlock,
-      "found !hasSurvivorBranch block in auto-start.ts");
-    if (notSurvivorBlock) {
-      assert.ok(
-        notSurvivorBlock[1].includes('"needs-discussion"'),
-        "!hasSurvivorBranch block must handle needs-discussion phase",
-      );
-    }
-  });
-
-  test("7. Survivor branch + needs-discussion routes to showSmartEntry", () => {
-    const source = readAutoStartSource();
-
-    // When hasSurvivorBranch is true AND phase is needs-discussion, the code
-    // must route to showSmartEntry instead of falling through to auto-mode.
-    const survivorNeedsDiscussion = source.match(
-      /if\s*\(hasSurvivorBranch\s*&&\s*state\.phase\s*===\s*"needs-discussion"\)\s*\{[^}]*showSmartEntry/s,
-    );
-    assert.ok(!!survivorNeedsDiscussion,
-      "hasSurvivorBranch && needs-discussion must route to showSmartEntry");
-
-    // Verify the handler checks if the discussion succeeded
-    const handlerBlock = source.match(
-      /if\s*\(hasSurvivorBranch\s*&&\s*state\.phase\s*===\s*"needs-discussion"\)\s*\{([\s\S]*?)\n    \}/,
-    );
-    assert.ok(!!handlerBlock,
-      "found survivor + needs-discussion handler block");
-    if (handlerBlock) {
-      assert.ok(
-        handlerBlock[1].includes('postState.phase !== "needs-discussion"'),
-        "handler must check if phase advanced after discussion",
-      );
-      assert.ok(
-        handlerBlock[1].includes("releaseLockAndReturn"),
-        "handler must abort if discussion didn't promote draft",
-      );
-    }
-  });
+  // Tests 6 and 7 removed in the #4832 follow-up.
+  //
+  // They source-grepped `auto-start.ts` for specific regex patterns like
+  // `if (hasSurvivorBranch && state.phase === "needs-discussion")` —
+  // which broke (correctly so) when the three-way survivor decision was
+  // extracted into the `decideSurvivorAction` pure helper. The
+  // behavioural invariants they were trying to uphold are now covered
+  // directly in `survivor-branch-complete.test.ts`:
+  //   - (hasSurvivor=true, phase="needs-discussion") → "discuss"
+  //   - (hasSurvivor=false, phase="needs-discussion") → "none"
+  //   - (hasSurvivor=true, phase=other)              → "none"
+  // Those tests fail on real decision regressions without the
+  // source-grep brittleness. Tests 1–5 above remain — they hit
+  // `deriveState` on real fixtures and defend the #1726 infinite-loop
+  // fix end-to-end.
 });

package/src/resources/extensions/gsd/tests/auto-start-worktree-db-path.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -13,7 +13,7 @@ console.log("\n=== #3822: worktree bootstrap uses project DB path ===");
 const dbLifecycleIdx = src.indexOf("// ── DB lifecycle ──");
 assertTrue(dbLifecycleIdx > 0, "auto-start.ts has a DB lifecycle section");
 
-const dbLifecycleRegion = dbLifecycleIdx > 0 ? src.slice(dbLifecycleIdx, dbLifecycleIdx + 600) : "";
+const dbLifecycleRegion = dbLifecycleIdx > 0 ? extractSourceRegion(src, "// ── DB lifecycle ──") : "";
 
 assertTrue(
   dbLifecycleRegion.includes("const gsdDbPath = resolveProjectRootDbPath(s.basePath);"),

package/src/resources/extensions/gsd/tests/auto-thinking-restore.test.ts

@@ -2,6 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const autoSrc = readFileSync(join(import.meta.dirname, "..", "auto.ts"), "utf-8");
 const phasesSrc = readFileSync(join(import.meta.dirname, "..", "auto", "phases.ts"), "utf-8");
@@ -20,7 +21,7 @@ test("stopAuto restores original thinking level", () => {
 test("runUnitPhase threads captured thinking level into selectAndApplyModel", () => {
   const callIdx = phasesSrc.indexOf("deps.selectAndApplyModel(");
   assert.ok(callIdx > -1, "phases.ts should call selectAndApplyModel");
-  const callBlock = phasesSrc.slice(callIdx, callIdx + 600);
+  const callBlock = extractSourceRegion(phasesSrc, "deps.selectAndApplyModel(");
   assert.ok(
     callBlock.includes("s.autoModeStartThinkingLevel"),
     "runUnitPhase should pass autoModeStartThinkingLevel to selectAndApplyModel",
@@ -30,7 +31,7 @@ test("runUnitPhase threads captured thinking level into selectAndApplyModel", ()
 test("hook model override preserves captured thinking level", () => {
   const hookIdx = phasesSrc.indexOf("const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;");
   assert.ok(hookIdx > -1, "phases.ts should include hook model override handling");
-  const hookBlock = phasesSrc.slice(hookIdx, hookIdx + 600);
+  const hookBlock = extractSourceRegion(phasesSrc, "const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;");
   assert.ok(
     hookBlock.includes("pi.setThinkingLevel(s.autoModeStartThinkingLevel)"),
     "hook model override should re-apply captured thinking level after setModel",

package/src/resources/extensions/gsd/tests/auto-warning-noise-regression.test.ts

@@ -27,6 +27,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { buildFlatRateContext } from "../auto-model-selection.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 // ─── Bug 2: this-binding regression ─────────────────────────────────────
 
@@ -69,7 +70,7 @@ test("isSamePath short-circuits ENOENT before logging a warning", () => {
   assert.ok(fnIdx !== -1, "isSamePath function exists");
 
   // Grab the function body (enough to cover the catch block).
-  const fnBody = src.slice(fnIdx, fnIdx + 600);
+  const fnBody = extractSourceRegion(src, "function isSamePath", { fromIdx: fnIdx });
 
   const catchIdx = fnBody.indexOf("catch");
   assert.ok(catchIdx !== -1, "isSamePath has a catch block");
@@ -103,7 +104,7 @@ test("checkAutoStartAfterDiscuss guards DISCUSSION-MANIFEST.json unlink with exi
 
   // Everything from the comment to a short distance below should contain
   // the existsSync guard before the unlinkSync call.
-  const block = src.slice(cleanupIdx, cleanupIdx + 400);
+  const block = extractSourceRegion(src, "remove discussion manifest after auto-start", { fromIdx: cleanupIdx });
 
   const existsIdx = block.indexOf("existsSync(manifestPath)");
   const unlinkIdx = block.indexOf("unlinkSync(manifestPath)");

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

@@ -144,3 +144,26 @@ describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", (
     );
   });
 });
+
+describe("#4365: tool_execution_start hook must pass toolName to markToolStart", () => {
+  test("tool_execution_start handler passes event.toolName to markToolStart", () => {
+    // The tool_execution_start handler must forward toolName so that
+    // hasInteractiveToolInFlight() can correctly identify ask_user_questions
+    // and prevent the idle watchdog from firing during interactive tool calls.
+    const startMarker = 'pi.on("tool_execution_start", async (event) => {';
+    const endMarker = 'pi.on("tool_execution_end", async (event) => {';
+    const toolExecutionStartSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(
+      toolExecutionStartSection.length > 0,
+      "Could not locate tool_execution_start handler section",
+    );
+    assert.ok(
+      toolExecutionStartSection.includes("markToolStart(event.toolCallId, event.toolName)"),
+      "tool_execution_start handler must pass event.toolName to markToolStart so hasInteractiveToolInFlight() works correctly",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts

@@ -2,6 +2,7 @@ import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const systemContextSrc = readFileSync(
   join(import.meta.dirname, "..", "bootstrap", "system-context.ts"),
@@ -29,7 +30,7 @@ describe("bootstrap deriveState DB guards (#3844)", () => {
   test("register-hooks opens DB before deriveState in session_before_compact", () => {
     const compactIdx = registerHooksSrc.indexOf('pi.on("session_before_compact"');
     assert.ok(compactIdx > -1, "register-hooks should define session_before_compact");
-    const compactSection = registerHooksSrc.slice(compactIdx, compactIdx + 1600);
+    const compactSection = extractSourceRegion(registerHooksSrc, 'pi.on("session_before_compact"');
     const ensureIdx = compactSection.indexOf("ensureDbOpen()");
     const deriveIdx = compactSection.indexOf("deriveState(basePath)");
     assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen()");

package/src/resources/extensions/gsd/tests/cache-staleness-regression.test.ts

@@ -69,11 +69,11 @@ describe("cache-staleness-regression", () => {
       ].join('\n');
       writeMilestoneFile(base, 'M001', 'ROADMAP', roadmap);
 
-      // Step 3: WITHOUT invalidation, the old state might be cached
-      // The state cache has a 100ms TTL, so wait just past it
-      await new Promise(r => setTimeout(r, 150));
-
-      // Step 4: Invalidate and re-derive — should see the new roadmap
+      // Step 3: Explicit invalidation — this is the #1240 fix path. We
+      // do NOT rely on the 100ms TTL here; the production code calls
+      // invalidateAllCaches() / invalidateStateCache() immediately after
+      // writing planning files, so the next deriveState() must see the
+      // new roadmap without any wall-clock wait.
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -100,10 +100,8 @@ describe("cache-staleness-regression", () => {
       // Simulate: discussion completes, CONTEXT.md is written
       writeMilestoneFile(base, 'M001', 'CONTEXT', '# M001: Test\n\nFull context after discussion.\n');
 
-      // Wait past TTL
-      await new Promise(r => setTimeout(r, 150));
-
-      // Without invalidation, we'd still see 'needs-discussion'
+      // Explicit invalidation is the production fix path for #1249 —
+      // no wall-clock wait needed.
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -116,7 +114,7 @@ describe("cache-staleness-regression", () => {
     }
   });
 
-  test("state cache TTL: fresh reads after 100ms", async () => {
+  test("state cache TTL: within window returns cached; past window re-derives", async () => {
     const base = createBase();
     try {
       writeMilestoneFile(base, 'M001', 'CONTEXT', '# M001\n\nDesc.\n');
@@ -126,7 +124,7 @@ describe("cache-staleness-regression", () => {
       const state1 = await deriveState(base);
       assert.strictEqual(state1.phase, 'pre-planning', 'initial: pre-planning');
 
-      // Write roadmap immediately
+      // Write roadmap immediately — no invalidation
       writeMilestoneFile(base, 'M001', 'ROADMAP', [
         '# M001: Test',
         '',
@@ -136,18 +134,19 @@ describe("cache-staleness-regression", () => {
         '',
       ].join('\n'));
 
-      // Immediately after writing (within 100ms TTL), the cache might be stale
+      // Within the TTL window, deriveState() must return the cached
+      // pre-planning state — this is the "cached" half of the TTL
+      // contract and the reason invalidateStateCache() exists.
       const state2 = await deriveState(base);
-      // This MAY still show pre-planning if within TTL — that's expected behavior
+      assert.strictEqual(state2.phase, 'pre-planning', 'within TTL: cached pre-planning is returned');
 
-      // Wait past TTL
+      // Past the TTL + explicit parse-cache flush, the fresh derive must
+      // see the new roadmap. invalidateAllCaches() is required because
+      // the file-parse cache is independent of the state TTL.
       await new Promise(r => setTimeout(r, 150));
-
-      // ALSO invalidate parse cache (not just state cache)
       invalidateAllCaches();
-      invalidateStateCache();
       const state3 = await deriveState(base);
-      assert.strictEqual(state3.phase, 'planning', 'after TTL expiry + invalidation → planning');
+      assert.strictEqual(state3.phase, 'planning', 'past TTL: re-derive sees new roadmap');
     } finally {
       cleanup(base);
     }
@@ -194,7 +193,6 @@ describe("cache-staleness-regression", () => {
         '- [ ] **T02: Second Task** `est:1h`',
       ].join('\n'));
 
-      await new Promise(r => setTimeout(r, 150));
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -242,7 +240,6 @@ describe("cache-staleness-regression", () => {
         '- [x] **T01: Task** `est:1h`',
       ].join('\n'));
 
-      await new Promise(r => setTimeout(r, 150));
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -282,7 +279,6 @@ describe("cache-staleness-regression", () => {
         '',
       ].join('\n'));
 
-      await new Promise(r => setTimeout(r, 150));
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);

package/src/resources/extensions/gsd/tests/canonical-milestone-root.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for resolveCanonicalMilestoneRoot — the worktree-aware reader
+ * that fixes #4761 (worktree work stranded when auto-loop exits without
+ * milestone completion).
+ *
+ * Contract: given (basePath, milestoneId), return the worktree path if a
+ * live git worktree exists for that milestone at .gsd/worktrees/<MID>/;
+ * otherwise return basePath unchanged. A live worktree has a .git file
+ * (not directory) — a bare directory without .git is a stale leftover.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-canon-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+/**
+ * Create a worktree directory shape that looks live: the .gsd/worktrees/<MID>/
+ * directory with a .git file containing a gitdir: pointer. We don't need a
+ * real git worktree — the resolver only checks for the .git file's presence.
+ */
+function makeLiveWorktree(base: string, mid: string): string {
+  const wtPath = join(base, ".gsd", "worktrees", mid);
+  mkdirSync(wtPath, { recursive: true });
+  writeFileSync(
+    join(wtPath, ".git"),
+    `gitdir: ${join(base, ".git", "worktrees", mid)}\n`,
+  );
+  return wtPath;
+}
+
+function makeStaleWorktree(base: string, mid: string): string {
+  const wtPath = join(base, ".gsd", "worktrees", mid);
+  mkdirSync(wtPath, { recursive: true });
+  // No .git file — this is the stale-leftover shape createWorktree() sees
+  // and cleans up.
+  return wtPath;
+}
+
+test("returns worktree path when a live worktree exists for the milestone", () => {
+  const base = makeTmpBase();
+  try {
+    const wtPath = makeLiveWorktree(base, "M001");
+    const result = resolveCanonicalMilestoneRoot(base, "M001");
+    assert.equal(result, wtPath);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("returns basePath when no worktree directory exists", () => {
+  const base = makeTmpBase();
+  try {
+    const result = resolveCanonicalMilestoneRoot(base, "M001");
+    assert.equal(result, base);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("returns basePath when worktree directory exists but has no .git file (stale)", () => {
+  const base = makeTmpBase();
+  try {
+    makeStaleWorktree(base, "M001");
+    const result = resolveCanonicalMilestoneRoot(base, "M001");
+    assert.equal(result, base);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("returns basePath for invalid milestoneId (path separators)", () => {
+  const base = makeTmpBase();
+  try {
+    // Even if a worktree coincidentally exists, the guard should reject.
+    assert.equal(resolveCanonicalMilestoneRoot(base, "../evil"), base);
+    assert.equal(resolveCanonicalMilestoneRoot(base, "M001/subdir"), base);
+    assert.equal(resolveCanonicalMilestoneRoot(base, "M001\\subdir"), base);
+    assert.equal(resolveCanonicalMilestoneRoot(base, ""), base);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("only returns the worktree for the requested milestone, not siblings", () => {
+  const base = makeTmpBase();
+  try {
+    makeLiveWorktree(base, "M001");
+    const result = resolveCanonicalMilestoneRoot(base, "M002");
+    assert.equal(result, base, "M002 has no worktree → basePath");
+  } finally {
+    cleanup(base);
+  }
+});