gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/tests/stash-queued-context-files.test.ts

@@ -378,3 +378,59 @@ test("#2505: back-to-back merges preserve queued CONTEXT files", () => {
     rmSync(repo, { recursive: true, force: true });
   }
 });
+
+// #4573: When `.gsd` is a gitignored symlink (ADR-002 layout) and the project
+// `.gitignore` contains `.gsd`, `git stash push --include-untracked -- <pathspec>`
+// fatals with "The following paths are ignored by one of your .gitignore files".
+// The prior tests used a symlinked `.gsd` but no `.gitignore`, so this failure
+// mode was invisible to CI. Fixture must include BOTH the symlink AND the
+// ignore rule to reproduce the bug on pre-fix code.
+test("#4573: gitignored .gsd symlink does not break pre-merge stash", () => {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "wt-4573-ignored-symlink-")));
+  const stateDir = realpathSync(mkdtempSync(join(tmpdir(), "wt-4573-state-")));
+  try {
+    run("git init", repo);
+    run("git config user.email test@test.com", repo);
+    run("git config user.name Test", repo);
+    writeFileSync(join(repo, "README.md"), "# test\n");
+    // Matches what BASELINE_PATTERNS in gitignore.ts writes for real projects.
+    writeFileSync(join(repo, ".gitignore"), ".gsd\n.gsd-id\n");
+    symlinkSync(stateDir, join(repo, ".gsd"));
+    run("git add README.md .gitignore", repo);
+    run("git commit -m init", repo);
+    run("git branch -M main", repo);
+
+    const wtPath = createAutoWorktree(repo, "M001");
+    const worktreeName = wtPath.replaceAll("\\", "/").split("/").pop() || "M001";
+    const sliceBranch = `slice/${worktreeName}/S01`;
+    run(`git checkout -b "${sliceBranch}"`, wtPath);
+    writeFileSync(join(wtPath, "app.ts"), "export const app = true;\n");
+    run("git add app.ts", wtPath);
+    run('git commit -m "add feature"', wtPath);
+    run("git checkout milestone/M001", wtPath);
+    run(`git merge --no-ff "${sliceBranch}" -m "merge S01"`, wtPath);
+
+    // Dirty a tracked file so the pre-merge stash branch actually runs.
+    writeFileSync(join(repo, "README.md"), "# test\n\nDirty.\n");
+
+    const result = mergeMilestoneToMain(
+      repo,
+      "M001",
+      makeRoadmap("M001", "Feature", [{ id: "S01", title: "Feature" }]),
+    );
+
+    assert.ok(
+      result.commitMessage.includes("GSD-Milestone: M001"),
+      "merge must succeed despite gitignored .gsd symlink",
+    );
+    assert.ok(existsSync(join(repo, "app.ts")), "milestone code merged to main");
+    assert.equal(
+      lstatSync(join(repo, ".gsd")).isSymbolicLink(),
+      true,
+      ".gsd symlink remains in place",
+    );
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(stateDir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/state-machine-full-walkthrough.test.ts

@@ -13,6 +13,7 @@ import {
   isValidationTerminal,
   isGhostMilestone,
   invalidateStateCache,
+  getActiveMilestoneId,
 } from "../state.ts";
 import {
   openDatabase,
@@ -667,6 +668,29 @@ describe("state-machine-full-walkthrough", () => {
       assert.notEqual(state.phase, "completing-milestone", "should be complete, not completing");
       assert.equal(state.phase, "complete");
     });
+
+    test("failure-path milestone SUMMARY is not terminal completion", async () => {
+      const base = createFixtureBase();
+      writeRoadmap(base, "M001", doneSliceRoadmap());
+      writeMilestoneValidation(base, "M001", "pass");
+      const dir = join(base, ".gsd", "milestones", "M001");
+      writeFileSync(join(dir, "M001-SUMMARY.md"), [
+        "---",
+        "status: failed",
+        "---",
+        "",
+        "# BLOCKER",
+        "",
+        "auto-mode recovery failed; milestone is not complete.",
+      ].join("\n"));
+      invalidateStateCache();
+
+      const state = await deriveState(base);
+
+      assert.equal(state.phase, "completing-milestone");
+      assert.equal(state.registry[0]?.status, "active");
+      assert.equal(await getActiveMilestoneId(base), "M001");
+    });
   });
 
   // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/state-transition-matrix.test.ts

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  STATE_TRANSITION_MATRIX,
+  findTransition,
+  validateTransitionMatrix,
+} from "../state-transition-matrix.ts";
+
+test("state transition matrix covers required swarm hardening events", () => {
+  const result = validateTransitionMatrix([
+    "context-ready",
+    "research-ready",
+    "plan-ready",
+    "task-dispatched",
+    "slice-complete",
+    "validation-pass",
+    "recovery-plan-ready",
+    "closeout-complete",
+  ]);
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.missingEvents, []);
+  assert.deepEqual(result.duplicateKeys, []);
+});
+
+test("state transition matrix fails closed for recovery and closeout guards", () => {
+  const recovery = findTransition("blocked", "recovery-plan-ready");
+  assert.equal(recovery?.to, "executing");
+  assert.equal(recovery?.onFail, "blocked");
+  assert.equal(recovery?.reasonCode, "recovery");
+
+  const closeout = findTransition("completing-milestone", "closeout-complete");
+  assert.equal(closeout?.to, "complete");
+  assert.equal(closeout?.onFail, "blocked");
+});
+
+test("state transition matrix entries all have guard and reason codes", () => {
+  assert.ok(STATE_TRANSITION_MATRIX.length >= 8);
+  for (const entry of STATE_TRANSITION_MATRIX) {
+    assert.ok(entry.guard.length > 0, `${entry.event} must document its guard`);
+    assert.ok(entry.reasonCode.length > 0, `${entry.event} must include reason code`);
+  }
+});

package/src/resources/extensions/gsd/tests/stuck-detection-coverage.test.ts

@@ -142,9 +142,9 @@ test("Rule 3: A-A-A-A triggers Rule 2 not Rule 3", () => {
 
 test("Rule 4: same ENOENT path in two entries triggers stuck", () => {
   const result = detectStuck([
-    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.gsd/agent/skills/debug-like-expert/SKILL.md'" },
+    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.agents/skills/debug-like-expert/SKILL.md'" },
     { key: "B" },
-    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.gsd/agent/skills/debug-like-expert/SKILL.md'" },
+    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.agents/skills/debug-like-expert/SKILL.md'" },
   ]);
   assert.notEqual(result, null);
   assert.equal(result!.stuck, true);

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

@@ -102,7 +102,8 @@ describe("token-counter: estimateTokensForProvider", () => {
 
 describe("token-counter: backward compatibility", () => {
   it("countTokensSync returns heuristic estimate when tiktoken is not loaded", () => {
-    // Without tiktoken loaded, countTokensSync falls back to ceil(len/4)
+    // Without tiktoken loaded, countTokensSync falls back to estimateTokensForProvider.
+    // With no provider (defaults to "unknown", ratio 4.0): ceil(100/4) = 25.
     const text = "A".repeat(100);
     const result = countTokensSync(text);
     // Either tiktoken is loaded (exact count) or heuristic (ceil(100/4) = 25)
@@ -127,3 +128,106 @@ describe("token-counter: backward compatibility", () => {
     assert.equal(result, 0);
   });
 });
+
+// ─── provider-aware fallback (issue #4529) ───────────────────────────────────
+// Regression tests: countTokens/countTokensSync must use provider-specific
+// ratios for their heuristic fallback, not a hardcoded GPT-4o / 4 divisor.
+
+describe("token-counter: provider-aware heuristic fallback", () => {
+  // These tests exercise the heuristic path (no tiktoken or before init).
+  // We call estimateTokensForProvider directly to validate expected values,
+  // then verify countTokens/countTokensSync return the same values when
+  // tiktoken is unavailable.
+
+  it("countTokensSync uses anthropic ratio (3.5) when provider is 'anthropic'", () => {
+    const text = "A".repeat(350);
+    // anthropic: ceil(350 / 3.5) = 100
+    // openai/unknown: ceil(350 / 4.0) = 88
+    // These are different — the provider must matter.
+    const anthropicEstimate = estimateTokensForProvider(text, "anthropic");
+    const unknownEstimate = estimateTokensForProvider(text, "unknown");
+    assert.equal(anthropicEstimate, 100, "anthropic ratio should give 100 tokens for 350 chars");
+    assert.equal(unknownEstimate, 88, "unknown ratio should give 88 tokens for 350 chars");
+    assert.notEqual(
+      anthropicEstimate,
+      unknownEstimate,
+      "anthropic and unknown estimates must differ — if they are equal the provider is being ignored",
+    );
+
+    // Actually call countTokensSync with the anthropic provider.
+    // When tiktoken is not loaded, this must return the provider-aware estimate (100).
+    // When tiktoken is loaded, it returns the tiktoken count (which is also > 0 and
+    // will be in the range [88, 120] for 350 "A" characters with cl100k_base).
+    const syncResult = countTokensSync(text, "anthropic");
+    assert.ok(typeof syncResult === "number", "countTokensSync must return a number");
+    assert.ok(syncResult > 0, "countTokensSync must return a positive count");
+    // If tiktoken is unavailable the result must exactly match the anthropic heuristic.
+    // If tiktoken is available we cannot assert the exact value, but we know it will
+    // not equal the unknown-provider heuristic (88) for 350 identical characters.
+    const tiktokenAvailable = syncResult !== anthropicEstimate;
+    if (!tiktokenAvailable) {
+      assert.equal(
+        syncResult,
+        anthropicEstimate,
+        `countTokensSync with 'anthropic' provider must return ${anthropicEstimate} (not the unknown-provider value ${unknownEstimate}) when tiktoken is unavailable`,
+      );
+    }
+  });
+
+  it("countTokens uses anthropic ratio when provider='anthropic' and tiktoken unavailable", async () => {
+    const text = "A".repeat(350);
+    // anthropic heuristic: ceil(350 / 3.5) = 100
+    // unknown/hardcoded-4 heuristic: ceil(350 / 4.0) = 88
+    const anthropicEstimate = estimateTokensForProvider(text, "anthropic"); // 100
+    const unknownEstimate = estimateTokensForProvider(text, "unknown");     // 88
+    const hardcodedFallback = Math.ceil(text.length / 4);                   // 88
+
+    // The anthropic heuristic must produce more tokens than the old /4 fallback.
+    assert.equal(anthropicEstimate, 100, "anthropic heuristic should give 100 tokens for 350 chars");
+    assert.ok(
+      anthropicEstimate > hardcodedFallback,
+      `anthropic estimate (${anthropicEstimate}) must exceed the hardcoded /4 fallback (${hardcodedFallback})`,
+    );
+    assert.notEqual(
+      anthropicEstimate,
+      unknownEstimate,
+      "anthropic and unknown estimates must differ — provider is being ignored if equal",
+    );
+
+    // Call countTokens with the anthropic provider and verify the result.
+    const result = await countTokens(text, "anthropic");
+    assert.ok(typeof result === "number", "should return a number");
+    assert.ok(result > 0, "should return a positive token count");
+
+    // When tiktoken is unavailable: result must equal the anthropic heuristic (100),
+    // NOT the unknown-provider heuristic (88). This is the core regression guard for #4529.
+    // When tiktoken IS available: result is the tiktoken count, which will differ from
+    // the heuristic — but it must never equal the wrong (unknown) heuristic for this text.
+    if (result === anthropicEstimate || result === unknownEstimate) {
+      // We are on the heuristic path — assert the correct provider ratio was used.
+      assert.equal(
+        result,
+        anthropicEstimate,
+        `countTokens with 'anthropic' provider returned ${result} but expected ${anthropicEstimate} (anthropic heuristic) not ${unknownEstimate} (unknown/hardcoded heuristic)`,
+      );
+    } else {
+      // tiktoken is active — result is an exact BPE count.
+      // For 350 identical "A" characters cl100k_base produces a count in [80, 130].
+      assert.ok(
+        result >= 80 && result <= 130,
+        `tiktoken count ${result} for 350 "A" chars is outside expected range [80, 130]`,
+      );
+    }
+  });
+
+  it("countTokens with provider='anthropic' yields more tokens than provider='openai' (heuristic)", () => {
+    const text = "A".repeat(400);
+    // anthropic: ceil(400/3.5) = 115, openai: ceil(400/4.0) = 100
+    const anthropic = estimateTokensForProvider(text, "anthropic");
+    const openai = estimateTokensForProvider(text, "openai");
+    assert.ok(
+      anthropic > openai,
+      `anthropic estimate (${anthropic}) must exceed openai estimate (${openai}) for same text`,
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/tool-compatibility.test.ts

@@ -14,6 +14,7 @@ import {
   isToolCompatibleWithProvider,
   filterToolsForProvider,
   adjustToolSet,
+  GROQ_MAX_TOOLS,
 } from "../model-router.js";
 
 import {
@@ -197,3 +198,109 @@ describe("adjustToolSet", () => {
     assert.deepEqual(removedTools, ["mcp_complex"]);
   });
 });
+
+// ─── GROQ_MAX_TOOLS constant ─────────────────────────────────────────────────
+
+describe("GROQ_MAX_TOOLS", () => {
+  test("equals 128", () => {
+    assert.equal(GROQ_MAX_TOOLS, 128);
+  });
+});
+
+// ─── Groq tool-count cap (#4376) ────────────────────────────────────────────
+
+describe("filterToolsForProvider — Groq 128-tool cap", () => {
+  beforeEach(() => {
+    resetToolCompatibilityRegistry();
+  });
+
+  test("does not cap when provider is not groq", () => {
+    const toolNames = Array.from({ length: 200 }, (_, i) => `tool_${i}`);
+    const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-completions");
+    assert.equal(compatible.length, 200);
+    assert.equal(filtered.length, 0);
+  });
+
+  test("does not cap when <= 128 tools with groq provider", () => {
+    const toolNames = Array.from({ length: 128 }, (_, i) => `tool_${i}`);
+    const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(compatible.length, 128);
+    assert.equal(filtered.length, 0);
+  });
+
+  test("caps to 128 when >128 tools with groq provider", () => {
+    const toolNames = Array.from({ length: 200 }, (_, i) => `tool_${i}`);
+    const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(compatible.length, 128);
+    assert.equal(filtered.length, 72);
+  });
+
+  test("keeps the first 128 tools when capping", () => {
+    const toolNames = Array.from({ length: 200 }, (_, i) => `tool_${i}`);
+    const { compatible } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(compatible[0], "tool_0");
+    assert.equal(compatible[127], "tool_127");
+  });
+
+  test("trimmed tools appear in filtered list", () => {
+    const toolNames = Array.from({ length: 130 }, (_, i) => `tool_${i}`);
+    const { filtered } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(filtered.length, 2);
+    assert.equal(filtered[0], "tool_128");
+    assert.equal(filtered[1], "tool_129");
+  });
+
+  test("emits a warning when tools are trimmed", () => {
+    const warnings: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => { warnings.push(String(args[0])); };
+    try {
+      const toolNames = Array.from({ length: 129 }, (_, i) => `tool_${i}`);
+      filterToolsForProvider(toolNames, "openai-completions", "groq");
+      assert.equal(warnings.length, 1);
+      assert.ok(warnings[0].includes("128"), "warning mentions Groq limit");
+    } finally {
+      console.warn = original;
+    }
+  });
+
+  test("does not warn when tools are at the limit", () => {
+    const warnings: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => { warnings.push(String(args[0])); };
+    try {
+      const toolNames = Array.from({ length: 128 }, (_, i) => `tool_${i}`);
+      filterToolsForProvider(toolNames, "openai-completions", "groq");
+      assert.equal(warnings.length, 0);
+    } finally {
+      console.warn = original;
+    }
+  });
+});
+
+describe("adjustToolSet — Groq 128-tool cap", () => {
+  beforeEach(() => {
+    resetToolCompatibilityRegistry();
+  });
+
+  test("caps to 128 tools when provider is groq and >128 tools active", () => {
+    const toolNames = Array.from({ length: 150 }, (_, i) => `tool_${i}`);
+    const { toolNames: result, removedTools } = adjustToolSet(toolNames, "openai-completions", "groq");
+    assert.equal(result.length, 128);
+    assert.equal(removedTools.length, 22);
+  });
+
+  test("does not cap for non-groq providers even with >128 tools", () => {
+    const toolNames = Array.from({ length: 150 }, (_, i) => `tool_${i}`);
+    const { toolNames: result, removedTools } = adjustToolSet(toolNames, "openai-completions", "openai");
+    assert.equal(result.length, 150);
+    assert.equal(removedTools.length, 0);
+  });
+
+  test("does not cap when provider is omitted", () => {
+    const toolNames = Array.from({ length: 150 }, (_, i) => `tool_${i}`);
+    const { toolNames: result, removedTools } = adjustToolSet(toolNames, "openai-completions");
+    assert.equal(result.length, 150);
+    assert.equal(removedTools.length, 0);
+  });
+});

package/src/resources/extensions/gsd/tests/triage-resolution.test.ts

@@ -258,6 +258,55 @@ test("resolution: markCaptureExecuted is idempotent", () => {
   }
 });
 
+// ─── executeTriageResolutions + note execution (#3578) ──────────────────────
+
+test("resolution: executeTriageResolutions stamps note captures as executed", () => {
+  const tmp = makeTempDir("res-exec-note");
+  try {
+    const id = appendCapture(tmp, "FYI the API changed");
+    markCaptureResolved(tmp, id, "note", "acknowledged", "informational");
+
+    const result = executeTriageResolutions(tmp, "M001", "S01");
+
+    // The note should now be marked as executed
+    const all = loadAllCaptures(tmp);
+    assert.strictEqual(all.length, 1);
+    assert.strictEqual(all[0].executed, true, "note capture should be marked as executed");
+
+    // It should appear in the actions log
+    assert.ok(
+      result.actions.some(a => a.includes(id) && a.includes("Note acknowledged")),
+      "actions should include a note-acknowledged entry",
+    );
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("resolution: executeTriageResolutions does not double-stamp already-executed notes", () => {
+  const tmp = makeTempDir("res-exec-note-idem");
+  try {
+    const id = appendCapture(tmp, "informational note");
+    markCaptureResolved(tmp, id, "note", "acknowledged", "info");
+
+    // First execution — stamps the note
+    executeTriageResolutions(tmp, "M001", "S01");
+
+    // Second execution — should be a no-op for the note
+    const result2 = executeTriageResolutions(tmp, "M001", "S01");
+
+    assert.strictEqual(result2.actions.length, 0, "second call should produce no actions");
+
+    // Verify the Executed field was not duplicated in the file
+    const filePath = join(tmp, ".gsd", "CAPTURES.md");
+    const content = readFileSync(filePath, "utf-8");
+    const executedMatches = content.match(/\*\*Executed:\*\*/g);
+    assert.strictEqual(executedMatches?.length, 1, "should have exactly one Executed field");
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
 // ─── loadActionableCaptures ──────────────────────────────────────────────────
 
 test("resolution: loadActionableCaptures returns only unexecuted actionable captures", () => {
@@ -387,8 +436,7 @@ test("resolution: executeTriageResolutions handles mixed classifications", () =>
     assert.strictEqual(result.injected, 1, "should inject 1 task");
     assert.strictEqual(result.replanned, 0);
     assert.strictEqual(result.quickTasks.length, 1, "should queue 1 quick-task");
-    // inject + quick-task + note acknowledged = 3 actions (defer still excluded)
-    assert.strictEqual(result.actions.length, 3, "should have 3 action entries (defer excluded, note now included)");
+    assert.strictEqual(result.actions.length, 3, "should have 3 action entries (inject + quick-task + note acknowledged; defer excluded)");
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }

package/src/resources/extensions/gsd/tests/turn-epoch.test.ts

@@ -0,0 +1,162 @@
+// Project: gsd-pi — Tests for the auto/turn-epoch stale-write guard.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  _resetTurnEpoch,
+  bumpTurnGeneration,
+  describeTurnEpoch,
+  getCurrentTurnGeneration,
+  isStaleWrite,
+  runWithTurnGeneration,
+} from "../auto/turn-epoch.ts";
+
+test("turn-epoch: generation starts at 0 and bumps monotonically", () => {
+  _resetTurnEpoch();
+  assert.equal(getCurrentTurnGeneration(), 0);
+  assert.equal(bumpTurnGeneration("test-a"), 1);
+  assert.equal(bumpTurnGeneration("test-b"), 2);
+  assert.equal(getCurrentTurnGeneration(), 2);
+});
+
+test("turn-epoch: isStaleWrite returns false when no turn context captured", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("no-context");
+  // Called outside runWithTurnGeneration — safe default is false.
+  assert.equal(isStaleWrite("out-of-band"), false);
+});
+
+test("turn-epoch: isStaleWrite returns false inside a fresh turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    assert.equal(isStaleWrite("fresh"), false);
+  });
+});
+
+test("turn-epoch: isStaleWrite returns true after the epoch bumps mid-turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    bumpTurnGeneration("recovery-fires");
+    assert.equal(isStaleWrite("stale"), true);
+  });
+});
+
+test("turn-epoch: nested turns each see their own captured generation", () => {
+  _resetTurnEpoch();
+  const outerGen = getCurrentTurnGeneration();
+  runWithTurnGeneration(outerGen, () => {
+    assert.equal(isStaleWrite("outer-fresh"), false);
+    bumpTurnGeneration("bump-between");
+    const innerGen = getCurrentTurnGeneration();
+    runWithTurnGeneration(innerGen, () => {
+      // Inner context saw the bumped generation at capture time — fresh.
+      assert.equal(isStaleWrite("inner-fresh"), false);
+    });
+    // Back to outer context — still stale because outerGen < current.
+    assert.equal(isStaleWrite("outer-after-bump"), true);
+  });
+});
+
+test("turn-epoch: describeTurnEpoch surfaces captured vs current", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("seed");
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    let snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured);
+    assert.equal(snapshot.stale, false);
+
+    bumpTurnGeneration("supersede");
+    snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured + 1);
+    assert.equal(snapshot.stale, true);
+  });
+
+  // Outside the turn — captured is null, stale is false.
+  const outside = describeTurnEpoch();
+  assert.equal(outside.captured, null);
+  assert.equal(outside.stale, false);
+});
+
+test("turn-epoch: AsyncLocalStorage propagates across awaits", async () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  await runWithTurnGeneration(captured, async () => {
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 1));
+    bumpTurnGeneration("async-bump");
+    await Promise.resolve();
+    assert.equal(isStaleWrite("post-await"), true);
+  });
+});
+
+// ─── Source-level invariant checks for recoverTimedOutUnit ──────────────────
+//
+// The recoverTimedOutUnit function has two branch families:
+// - ADVANCE branches: the unit is done, loop moves on — these MUST bump.
+// - STEERING branches: the same LLM turn is kept alive with a steering
+//   message — these MUST NOT bump (otherwise the retry's legitimate writes
+//   get marked stale).
+//
+// The whole function must contain zero raw `resolveAgentEnd` calls with the
+// "timeout-recovery" _synthetic marker — all advance paths go through
+// bumpAndResolveSynthetic. And there must be no top-level bump call.
+
+test("recoverTimedOutUnit: no raw `resolveAgentEnd({ _synthetic: \"timeout-recovery\" })` calls remain", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const rawSyntheticResolve =
+    /resolveAgentEnd\s*\(\s*\{\s*messages:\s*\[\s*\]\s*,\s*_synthetic:\s*["']timeout-recovery/;
+  assert.equal(
+    rawSyntheticResolve.test(src),
+    false,
+    "auto-timeout-recovery.ts must funnel advance paths through bumpAndResolveSynthetic — a raw resolveAgentEnd with _synthetic:\"timeout-recovery\" would leak orphan writes",
+  );
+});
+
+test("recoverTimedOutUnit: no top-level bumpTurnGeneration — steering branches must not supersede", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  // The only bump surface allowed is via bumpAndResolveSynthetic (advance
+  // paths) — a direct bumpTurnGeneration call in this file would bump even
+  // when the function later decides to take a steering retry branch.
+  assert.equal(
+    /\bbumpTurnGeneration\s*\(/.test(src),
+    false,
+    "auto-timeout-recovery.ts must not call bumpTurnGeneration directly — use bumpAndResolveSynthetic so bump and supersede are atomic and tied to advance-only branches",
+  );
+});
+
+test("recoverTimedOutUnit: bumpAndResolveSynthetic appears exactly four times (one per advance branch)", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const matches = src.match(/bumpAndResolveSynthetic\s*\(/g) ?? [];
+  assert.equal(
+    matches.length,
+    4,
+    `expected 4 advance-branch supersede sites (durableComplete, execute-task-exhausted, artifact-already-exists, non-execute-exhausted); found ${matches.length}`,
+  );
+});