gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

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

@@ -0,0 +1,210 @@
+/**
+ * Tests for worktree telemetry — #4764.
+ *
+ * Covers emit helpers (writing to the journal) and the aggregator
+ * (summarizeWorktreeTelemetry).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import {
+  emitWorktreeCreated,
+  emitWorktreeMerged,
+  emitWorktreeOrphaned,
+  emitAutoExit,
+  emitCanonicalRootRedirect,
+  summarizeWorktreeTelemetry,
+  percentile,
+} from "../worktree-telemetry.ts";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.ts";
+import { queryJournal } from "../journal.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-tel-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+test("emitWorktreeCreated writes a worktree-created journal event", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeCreated(base, "M001", { reason: "create-milestone" });
+    const entries = queryJournal(base, { eventType: "worktree-created" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M001");
+    assert.equal(entries[0].data?.reason, "create-milestone");
+    assert.ok(typeof entries[0].data?.startedAt === "string");
+  } finally { cleanup(base); }
+});
+
+test("emitWorktreeMerged records duration and conflict fields", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeMerged(base, "M001", {
+      reason: "milestone-complete",
+      durationMs: 1234,
+      sliceCount: 3,
+      taskCount: 9,
+      conflict: false,
+    });
+    const entries = queryJournal(base, { eventType: "worktree-merged" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M001");
+    assert.equal(entries[0].data?.durationMs, 1234);
+    assert.equal(entries[0].data?.sliceCount, 3);
+    assert.equal(entries[0].data?.conflict, false);
+  } finally { cleanup(base); }
+});
+
+test("emitWorktreeOrphaned captures reason and commits-ahead", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeOrphaned(base, "M002", {
+      reason: "in-progress-unmerged",
+      commitsAhead: 4,
+      worktreeDirExists: true,
+    });
+    const entries = queryJournal(base, { eventType: "worktree-orphaned" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M002");
+    assert.equal(entries[0].data?.reason, "in-progress-unmerged");
+    assert.equal(entries[0].data?.commitsAhead, 4);
+    assert.equal(entries[0].data?.worktreeDirExists, true);
+  } finally { cleanup(base); }
+});
+
+test("emitAutoExit records reason and unmerged-work signal", () => {
+  const base = makeTmpBase();
+  try {
+    emitAutoExit(base, {
+      reason: "pause",
+      milestoneId: "M003",
+      milestoneMerged: false,
+    });
+    const entries = queryJournal(base, { eventType: "auto-exit" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.reason, "pause");
+    assert.equal(entries[0].data?.milestoneMerged, false);
+  } finally { cleanup(base); }
+});
+
+test("summarizeWorktreeTelemetry aggregates events correctly", () => {
+  const base = makeTmpBase();
+  try {
+    // Two created, one merged, two orphans (different reasons), three exits,
+    // two of which left work unmerged.
+    emitWorktreeCreated(base, "M001");
+    emitWorktreeCreated(base, "M002");
+
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", durationMs: 500, conflict: false });
+
+    emitWorktreeOrphaned(base, "M002", { reason: "in-progress-unmerged", commitsAhead: 2 });
+    emitWorktreeOrphaned(base, "M003", { reason: "complete-unmerged" });
+
+    emitAutoExit(base, { reason: "pause", milestoneId: "M002", milestoneMerged: false });
+    emitAutoExit(base, { reason: "stop", milestoneId: "M002", milestoneMerged: false });
+    emitAutoExit(base, { reason: "all-complete", milestoneId: "M001", milestoneMerged: true });
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.worktreesCreated, 2);
+    assert.equal(summary.worktreesMerged, 1);
+    assert.equal(summary.orphansDetected, 2);
+    assert.deepStrictEqual(summary.orphansByReason, {
+      "in-progress-unmerged": 1,
+      "complete-unmerged": 1,
+    });
+    assert.deepStrictEqual(summary.mergeDurationsMs, [500]);
+    assert.equal(summary.mergeConflicts, 0);
+    assert.deepStrictEqual(summary.exitsByReason, {
+      "pause": 1,
+      "stop": 1,
+      "all-complete": 1,
+    });
+    assert.equal(summary.exitsWithUnmergedWork, 2, "pause and stop each left work unmerged");
+  } finally { cleanup(base); }
+});
+
+test("summarizeWorktreeTelemetry counts merge conflicts", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", durationMs: 100, conflict: false });
+    emitWorktreeMerged(base, "M002", { reason: "milestone-complete", durationMs: 200, conflict: true, conflictedFiles: 3 });
+    emitWorktreeMerged(base, "M003", { reason: "milestone-complete", durationMs: 150, conflict: false });
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.worktreesMerged, 3);
+    assert.equal(summary.mergeConflicts, 1);
+    // Durations are sorted
+    assert.deepStrictEqual(summary.mergeDurationsMs, [100, 150, 200]);
+  } finally { cleanup(base); }
+});
+
+test("resolveCanonicalMilestoneRoot emits canonical-root-redirect on redirect", () => {
+  const base = makeTmpBase();
+  try {
+    // Create the live-worktree shape the resolver looks for
+    const wtDir = join(base, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(base, ".git", "worktrees", "M001")}\n`);
+
+    const result = resolveCanonicalMilestoneRoot(base, "M001");
+    assert.equal(result, wtDir);
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.canonicalRedirects, 1, "redirect should emit exactly one event");
+  } finally { cleanup(base); }
+});
+
+test("resolveCanonicalMilestoneRoot emits nothing when it doesn't redirect", () => {
+  const base = makeTmpBase();
+  try {
+    const result = resolveCanonicalMilestoneRoot(base, "M999");
+    assert.equal(result, base);
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.canonicalRedirects, 0, "no worktree → no redirect event");
+  } finally { cleanup(base); }
+});
+
+test("percentile helper returns quantiles of a sorted array (nearest-rank)", () => {
+  assert.equal(percentile([], 0.5), null);
+  assert.equal(percentile([10], 0.5), 10);
+  // Boundary behavior
+  assert.equal(percentile([10, 20, 30, 40], 0), 10);
+  assert.equal(percentile([10, 20, 30, 40], 1), 40);
+  // Nearest-rank: idx = ceil(q*n) - 1
+  // q=0.5, n=4 → idx = 2-1 = 1 → 20
+  assert.equal(percentile([10, 20, 30, 40], 0.5), 20);
+  // p95 on 20 values = idx ceil(0.95*20)-1 = 19-1 = 18 → value at index 18 (19th sample)
+  const twenty = Array.from({ length: 20 }, (_, i) => (i + 1) * 10); // [10..200]
+  assert.equal(percentile(twenty, 0.95), 190, "p95 should be the 19th of 20 sorted values, not the max");
+});
+
+test("summarizeWorktreeTelemetry supports time-window filtering", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeCreated(base, "M001");
+    const midpoint = new Date().toISOString();
+    // Brief delay to ensure the next event has a later ts
+    const start = Date.now();
+    while (Date.now() - start < 10) { /* spin */ }
+    emitWorktreeCreated(base, "M002");
+
+    const beforeOnly = summarizeWorktreeTelemetry(base, { before: midpoint });
+    const afterOnly = summarizeWorktreeTelemetry(base, { after: midpoint });
+    // The sum of the two partitions covers all events (may overlap by 1 at
+    // exact-ts boundary — assert each partition is a proper subset).
+    assert.ok(beforeOnly.worktreesCreated >= 1);
+    assert.ok(afterOnly.worktreesCreated >= 1);
+    assert.ok(beforeOnly.worktreesCreated + afterOnly.worktreesCreated >= 2);
+  } finally { cleanup(base); }
+});

package/src/resources/extensions/gsd/tests/write-gate.test.ts

@@ -11,6 +11,10 @@
 
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync, unlinkSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
 import {
   isDepthConfirmationAnswer,
   shouldBlockContextWrite,
@@ -20,8 +24,10 @@ import {
   markDepthVerified,
   isMilestoneDepthVerified,
   shouldBlockContextArtifactSave,
+  shouldBlockContextArtifactSaveInSnapshot,
   clearDiscussionFlowState,
   resetWriteGateState,
+  loadWriteGateSnapshot,
 } from '../bootstrap/write-gate.ts';
 
 // ─── Scenario 1: Blocks CONTEXT.md write during discussion without depth verification (absolute path) ──
@@ -488,3 +494,61 @@ test('write-gate: isDepthConfirmationAnswer falls back to (Recommended) match wi
     'should reject non-Recommended via fallback',
   );
 });
+
+// ─── Scenario 29: loadWriteGateSnapshot returns clean state when persist file deleted (#4343) ──
+
+test('write-gate: loadWriteGateSnapshot returns empty default when persist file is deleted (#4343)', () => {
+  const base = join(tmpdir(), `gsd-write-gate-4343-${randomUUID()}`);
+  mkdirSync(join(base, '.gsd', 'runtime'), { recursive: true });
+  const stateFilePath = join(base, '.gsd', 'runtime', 'write-gate-state.json');
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+
+  try {
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = '1';
+
+    // Write a state file with a pending gate and verified milestone
+    writeFileSync(stateFilePath, JSON.stringify({
+      verifiedDepthMilestones: ['M001'],
+      activeQueuePhase: false,
+      pendingGateId: 'depth_verification_M001',
+    }));
+    assert.ok(existsSync(stateFilePath), 'precondition: state file exists');
+
+    // While file exists, snapshot reflects its contents
+    const beforeDeletion = loadWriteGateSnapshot(base);
+    assert.strictEqual(beforeDeletion.pendingGateId, 'depth_verification_M001', 'pending gate from file');
+    assert.deepEqual(beforeDeletion.verifiedDepthMilestones, ['M001'], 'verified milestones from file');
+
+    // User deletes the state file to clear the HARD BLOCK
+    unlinkSync(stateFilePath);
+    assert.ok(!existsSync(stateFilePath), 'state file deleted');
+
+    // After deletion in persist mode, snapshot should be clean (not stale in-memory)
+    const afterDeletion = loadWriteGateSnapshot(base);
+    assert.strictEqual(afterDeletion.pendingGateId, null, 'pendingGateId cleared after file deletion');
+    assert.deepEqual(afterDeletion.verifiedDepthMilestones, [], 'verifiedDepthMilestones cleared after file deletion');
+    assert.strictEqual(afterDeletion.activeQueuePhase, false, 'activeQueuePhase cleared after file deletion');
+
+    // The CONTEXT artifact block check must also resolve to unblocked after deletion+verification
+    // (simulate the re-verify flow users would do: delete → depth verify → save)
+    const stillBlocked = shouldBlockContextArtifactSaveInSnapshot(afterDeletion, 'CONTEXT', 'M001', null);
+    assert.strictEqual(stillBlocked.block, true, 'still blocked without new depth verification');
+
+    const verifiedSnapshot = {
+      ...afterDeletion,
+      verifiedDepthMilestones: ['M001'],
+    };
+    const unblocked = shouldBlockContextArtifactSaveInSnapshot(verifiedSnapshot, 'CONTEXT', 'M001', null);
+    assert.strictEqual(unblocked.block, false, 'unblocked after fresh depth verification');
+  } finally {
+    if (originalEnv === undefined) {
+      delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    } else {
+      process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+    }
+    clearDiscussionFlowState();
+    try {
+      rmSync(base, { recursive: true, force: true });
+    } catch { /* swallow */ }
+  }
+});

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

@@ -1,95 +1,81 @@
-import { readFileSync } from "node:fs";
+/**
+ * zombie-gsd-state.test.ts — #2942
+ *
+ * A partially initialized `.gsd/` (symlink exists but neither `PREFERENCES.md`
+ * nor `milestones/` is present) previously caused the init-wizard gate in
+ * `showSmartEntry` to be skipped. The fix introduces
+ * `hasGsdBootstrapArtifacts`, which requires at least one bootstrap artifact
+ * to be present before treating the project as initialized.
+ *
+ * These tests exercise that helper directly over synthetic filesystems and
+ * injected predicates — replacing the old source-grep assertions that only
+ * verified the function's *text* shape.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-
-import { createTestContext } from "./test-helpers.ts";
-
-const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
-
-// ─── #2942: Zombie .gsd state skips init wizard ─────────────────────────────
-//
-// A partially initialized .gsd/ (symlink exists but no PREFERENCES.md or
-// milestones/) causes the init wizard gate in showSmartEntry to be skipped,
-// resulting in an uninitialized project session.
-
-console.log("\n=== #2942: zombie .gsd state must not skip init wizard ===");
-
-// ── guided-flow.ts — init wizard gate must check bootstrap completeness ──
-
-const guidedFlowSrc = readFileSync(
-  join(import.meta.dirname, "..", "guided-flow.ts"),
-  "utf-8",
-);
-
-// Find the showSmartEntry function
-const smartEntryIdx = guidedFlowSrc.indexOf("export async function showSmartEntry(");
-assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry");
-
-// Extract the region between showSmartEntry and the first showProjectInit call
-// This is where the init wizard gate lives.
-const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : "";
-
-// The gate must NOT be a bare `!existsSync(gsdRoot(basePath))` check.
-// It must also verify that bootstrap artifacts (PREFERENCES.md or milestones/) exist.
-assertTrue(
-  afterSmartEntry.includes("PREFERENCES.md") || afterSmartEntry.includes("PREFERENCES"),
-  "init wizard gate checks for PREFERENCES.md, not just .gsd/ existence (#2942)",
-);
-
-assertTrue(
-  afterSmartEntry.includes("milestones"),
-  "init wizard gate checks for milestones/ directory, not just .gsd/ existence (#2942)",
-);
-
-// The init wizard should be shown when .gsd/ exists but has no bootstrap artifacts.
-// The old code was: if (!existsSync(gsdRoot(basePath))) { ... showProjectInit ... }
-// The fix should use a compound check so zombie states trigger the wizard.
-// Verify we no longer have the bare existence check as the sole gate.
-
-// Find the specific init wizard gate pattern — the detection preamble block.
-const detectionPreambleIdx = afterSmartEntry.indexOf("Detection preamble");
-const detectionRegion = detectionPreambleIdx >= 0
-  ? afterSmartEntry.slice(detectionPreambleIdx, detectionPreambleIdx + 600)
-  : afterSmartEntry.slice(0, 1500);
-
-// The gate condition must reference PREFERENCES.md or milestones (bootstrap artifacts)
-assertMatch(
-  detectionRegion,
-  /PREFERENCES\.md|milestones/,
-  "detection preamble gate references bootstrap artifacts, not just directory existence (#2942)",
-);
-
-// ── auto-start.ts — milestones/ dir creation must not be dead code ──────────
-
-console.log("\n=== #2942: auto-start milestones/ bootstrap not dead code ===");
-
-const autoStartSrc = readFileSync(
-  join(import.meta.dirname, "..", "auto-start.ts"),
-  "utf-8",
-);
-
-// After ensureGsdSymlink, the code that creates milestones/ must check for
-// the milestones directory specifically (not .gsd/ which ensureGsdSymlink already created).
-const symlinkIdx = autoStartSrc.indexOf("ensureGsdSymlink(base)");
-assertTrue(symlinkIdx >= 0, "auto-start.ts calls ensureGsdSymlink(base)");
-
-const afterSymlink = symlinkIdx >= 0 ? autoStartSrc.slice(symlinkIdx, symlinkIdx + 800) : "";
-
-// The milestones bootstrap must check milestones path, not gsdDir
-// Old (dead) code: if (!existsSync(gsdDir)) { mkdirSync(join(gsdDir, "milestones"), ...) }
-// Fixed code should check: if (!existsSync(milestonesPath)) or similar
-assertTrue(
-  afterSymlink.includes("milestones") && afterSymlink.includes("mkdirSync"),
-  "auto-start.ts creates milestones/ directory after ensureGsdSymlink (#2942)",
-);
-
-// The guard for milestones/ creation should NOT be `!existsSync(gsdDir)` —
-// that's dead code since ensureGsdSymlink already created gsdDir.
-// It should check for the milestones/ dir directly.
-const mkdirRegion = afterSymlink.slice(0, afterSymlink.indexOf("mkdirSync") + 200);
-assertMatch(
-  mkdirRegion,
-  /existsSync\([^)]*milestones/,
-  "milestones bootstrap checks milestones path existence, not .gsd/ (#2942)",
-);
-
-report();
+import { tmpdir } from "node:os";
+
+import { hasGsdBootstrapArtifacts } from "../detection.ts";
+
+function makeGsdDir(t: { after: (fn: () => void) => void }): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-zombie-state-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("#2942: missing .gsd/ directory entirely → treated as un-bootstrapped", () => {
+  assert.equal(
+    hasGsdBootstrapArtifacts("/nonexistent/path/does/not/exist/.gsd"),
+    false,
+  );
+});
+
+test("#2942: zombie .gsd/ (empty directory) must NOT count as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  // Only the directory exists — neither PREFERENCES.md nor milestones/
+  assert.equal(
+    hasGsdBootstrapArtifacts(gsd),
+    false,
+    "an empty .gsd/ is a zombie state — init wizard must still run",
+  );
+});
+
+test("#2942: .gsd/ with PREFERENCES.md counts as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  writeFileSync(join(gsd, "PREFERENCES.md"), "# prefs\n");
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: .gsd/ with milestones/ directory counts as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  mkdirSync(join(gsd, "milestones"));
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: both artifacts present → bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  writeFileSync(join(gsd, "PREFERENCES.md"), "# prefs\n");
+  mkdirSync(join(gsd, "milestones"));
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: injected existsFn — zombie via predicate is rejected", () => {
+  // Only the .gsd/ directory exists; artifacts are missing.
+  const existsFn = (p: string) => p === "/proj/.gsd";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), false);
+});
+
+test("#2942: injected existsFn — PREFERENCES.md alone is enough", () => {
+  const existsFn = (p: string) =>
+    p === "/proj/.gsd" || p === "/proj/.gsd/PREFERENCES.md";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
+});
+
+test("#2942: injected existsFn — milestones/ alone is enough", () => {
+  const existsFn = (p: string) =>
+    p === "/proj/.gsd" || p === "/proj/.gsd/milestones";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
+});

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

@@ -22,7 +22,11 @@ async function getEncoder(): Promise<TokenEncoder | null> {
 	try {
 		// @ts-ignore — tiktoken may not have type declarations in extensions tsconfig
 		const tiktoken = await import("tiktoken");
-		encoder = tiktoken.encoding_for_model("gpt-4o") as TokenEncoder;
+		// Use cl100k_base — the most conservative and broadly compatible BPE encoding.
+		// It is shared by GPT-3.5/GPT-4 and gives a safer (larger) estimate than
+		// gpt-4o's o200k_base encoding, which produces fewer tokens for the same text
+		// and would cause context windows for non-OpenAI providers to be under-counted.
+		encoder = tiktoken.get_encoding("cl100k_base") as TokenEncoder;
 		return encoder;
 	} catch {
 		encoderFailed = true;
@@ -30,20 +34,33 @@ async function getEncoder(): Promise<TokenEncoder | null> {
 	}
 }
 
-export async function countTokens(text: string): Promise<number> {
+/**
+ * Count tokens in `text` using tiktoken (cl100k_base) when available.
+ *
+ * When tiktoken is not loaded, falls back to a provider-aware character-ratio
+ * estimate via `estimateTokensForProvider`. Passing `provider` is recommended
+ * so the heuristic fallback is as accurate as possible.
+ */
+export async function countTokens(text: string, provider?: TokenProvider): Promise<number> {
 	const enc = await getEncoder();
 	if (enc) {
 		const tokens = enc.encode(text);
 		return tokens.length;
 	}
-	return Math.ceil(text.length / 4);
+	return estimateTokensForProvider(text, provider ?? "unknown");
 }
 
-export function countTokensSync(text: string): number {
+/**
+ * Synchronous token count — only accurate after `initTokenCounter()` resolves.
+ *
+ * Before init, or when tiktoken is unavailable, falls back to a provider-aware
+ * character-ratio estimate. Passing `provider` is recommended.
+ */
+export function countTokensSync(text: string, provider?: TokenProvider): number {
 	if (encoder) {
 		return encoder.encode(text).length;
 	}
-	return Math.ceil(text.length / 4);
+	return estimateTokensForProvider(text, provider ?? "unknown");
 }
 
 export async function initTokenCounter(): Promise<boolean> {

package/src/resources/extensions/gsd/tools/complete-milestone.ts

@@ -7,7 +7,7 @@
  */
 
 import { join } from "node:path";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, existsSync } from "node:fs";
 
 import {
   transaction,
@@ -202,14 +202,20 @@ export async function handleCompleteMilestone(
     summaryPath = join(manualDir, `${params.milestoneId}-SUMMARY.md`);
   }
 
-  try {
-    await saveFile(summaryPath, summaryMd);
-  } catch (renderErr) {
-    // Disk render failed — roll back DB status so state stays consistent
-    logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
-    updateMilestoneStatus(params.milestoneId, 'active', null);
-    invalidateStateCache();
-    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
+  // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
+  // completion already wrote the file. Overwriting would silently destroy the
+  // richer content the agent produced during the original completion run.
+  if (!existsSync(summaryPath)) {
+    try {
+      await saveFile(summaryPath, summaryMd);
+    } catch (renderErr) {
+      // Disk render failed — roll back DB status so state stays consistent
+      logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
+      updateMilestoneStatus(params.milestoneId, 'active', null);
+      invalidateStateCache();
+      return { error: `disk render failed: ${(renderErr as Error).message}` };
+    }
   }
 
   // Invalidate all caches

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -30,6 +30,7 @@ import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
@@ -40,6 +41,14 @@ export interface CompleteSliceResult {
   milestoneId: string;
   summaryPath: string;
   uatPath: string;
+  /**
+   * True when this call re-completed an already-closed slice from a turn
+   * superseded by timeout recovery or cancellation. Response is shaped like
+   * success so the orphaned LLM tool call unwinds cleanly without mutating
+   * state.
+   */
+  duplicate?: boolean;
+  stale?: boolean;
 }
 
 /**
@@ -283,6 +292,10 @@ export async function handleCompleteSlice(
 
     const slice = getSlice(params.milestoneId, params.sliceId);
     if (slice && isClosedStatus(slice.status)) {
+      if (isStaleWrite("complete-slice")) {
+        guardError = "__stale_duplicate__";
+        return;
+      }
       guardError = `slice ${params.sliceId} is already complete — use gsd_slice_reopen first if you need to redo it`;
       return;
     }
@@ -307,6 +320,31 @@ export async function handleCompleteSlice(
     updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
   });
 
+  if (guardError === "__stale_duplicate__") {
+    // Stale duplicate from a turn superseded by timeout recovery. Return a
+    // non-mutating success so the orphaned LLM tool call unwinds quietly.
+    const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    const staleSummaryPath = sliceDir
+      ? join(sliceDir, `${params.sliceId}-SUMMARY.md`)
+      : join(
+          basePath,
+          ".gsd",
+          "milestones",
+          params.milestoneId,
+          "slices",
+          params.sliceId,
+          `${params.sliceId}-SUMMARY.md`,
+        );
+    return {
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      summaryPath: staleSummaryPath,
+      uatPath: staleSummaryPath.replace(/-SUMMARY\.md$/, "-UAT.md"),
+      duplicate: true,
+      stale: true,
+    };
+  }
+
   if (guardError) {
     return { error: guardError };
   }