gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -3,9 +3,17 @@
  * Tracks every bash command, file write, and file edit during a unit execution.
  * Evidence is compared against LLM completion claims in evidence-cross-ref.ts.
  *
+ * Evidence is persisted to .gsd/safety/evidence-<mid>-<sid>-<tid>.json so it
+ * survives session restarts (pause/resume, crash recovery). On unit start,
+ * call resetEvidence() then loadEvidenceFromDisk(). On every new tool call,
+ * saveEvidenceToDisk() is called automatically by recordToolCall/recordToolResult.
+ *
  * Follows the same module-level Map pattern as auto-tool-tracking.ts.
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -27,6 +35,94 @@ export function getFilePaths() {
         .filter((e) => e.kind === "write" || e.kind === "edit")
         .map(e => e.path);
 }
+// ─── Persistence (Bug #4385 — evidence must survive session restarts) ────────
+/**
+ * Build the path for the evidence JSON file for a given unit.
+ * Lives under .gsd/safety/ which is gitignored and session-scoped.
+ */
+function evidencePath(basePath, milestoneId, sliceId, taskId) {
+    return join(basePath, ".gsd", "safety", `evidence-${milestoneId}-${sliceId}-${taskId}.json`);
+}
+/**
+ * Validate that a parsed value is an array of EvidenceEntry objects.
+ * Rejects corrupt / schema-mismatch data rather than letting it poison state.
+ */
+function isEvidenceArray(data) {
+    if (!Array.isArray(data))
+        return false;
+    return data.every((e) => {
+        if (e === null || typeof e !== "object")
+            return false;
+        const rec = e;
+        if (typeof rec.toolCallId !== "string")
+            return false;
+        if (typeof rec.timestamp !== "number")
+            return false;
+        if (rec.kind === "bash") {
+            return (typeof rec.command === "string" &&
+                typeof rec.exitCode === "number" &&
+                typeof rec.outputSnippet === "string");
+        }
+        if (rec.kind === "write" || rec.kind === "edit") {
+            return typeof rec.path === "string";
+        }
+        return false;
+    });
+}
+/**
+ * Persist the current in-memory evidence to disk so it survives a session
+ * restart. Called from saveEvidenceToDisk after recordToolCall/recordToolResult.
+ * Non-fatal — persistence failures must never break unit execution.
+ */
+export function saveEvidenceToDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+        renameSync(tmp, path);
+    }
+    catch {
+        // Non-fatal — don't let persistence failures break unit execution
+    }
+}
+/**
+ * Load persisted evidence from disk into the in-memory array.
+ * Call after resetEvidence() on session resume to restore context for a
+ * partially-executed unit. If the file does not exist (fresh unit), this
+ * is a no-op — getEvidence() will return [] which is correct.
+ */
+export function loadEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        if (!existsSync(path))
+            return;
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (isEvidenceArray(parsed)) {
+            unitEvidence = parsed;
+        }
+    }
+    catch {
+        // Non-fatal — corrupt / missing file is treated as empty evidence
+    }
+}
+/**
+ * Delete the persisted evidence file for a unit after it has been fully
+ * processed. Prevents stale evidence from affecting future retries of
+ * the same unit ID.
+ */
+export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        if (existsSync(path)) {
+            unlinkSync(path);
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
 // ─── Recording (called from register-hooks.ts) ─────────────────────────────
 /**
  * Record a tool call at dispatch time (before execution).

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -4,13 +4,18 @@
  *
  * Uses tasks.expected_output (DB column, populated from per-task ## Expected Output)
  * and tasks.files (from slice PLAN.md - Files: subline) as the expected set.
- * Compares against git diff HEAD~1 --name-only after auto-commit.
+ * Compares against `git diff-tree --root --no-commit-id -r --name-only HEAD` after auto-commit.
+ * Using diff-tree --root handles initial commits, shallow clones, and merge commits correctly
+ * (Bug #4385 — git diff HEAD~1 failed on initial commits).
  *
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
+import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
 import { normalizePlannedFileReference } from "../files.js";
 import { logWarning } from "../workflow-logger.js";
+const _require = createRequire(import.meta.url);
+const picomatch = _require("picomatch");
 // ─── Public API ─────────────────────────────────────────────────────────────
 /**
  * Validate file changes after auto-commit for an execute-task unit.
@@ -20,7 +25,7 @@ import { logWarning } from "../workflow-logger.js";
  * @param expectedOutput - JSON array from tasks.expected_output DB column
  * @param plannedFiles - JSON array from tasks.files DB column
  */
-export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
+export function validateFileChanges(basePath, expectedOutput, plannedFiles, fileChangeAllowlist = []) {
     const allExpected = new Set([...expectedOutput, ...plannedFiles]);
     // If no expected files were planned, skip validation
     if (allExpected.size === 0)
@@ -33,8 +38,11 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
     const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
     // Normalize expected paths (strip leading ./ or /)
     const normalizedExpected = new Set([...allExpected].map((f) => normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, "")));
-    // Compute symmetric difference
-    const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f));
+    // Build allowlist matchers once (dot: true so patterns like `**/.hidden` work).
+    const allowlistMatchers = fileChangeAllowlist.map(p => picomatch(p, { dot: true }));
+    const isAllowlisted = (f) => allowlistMatchers.some(m => m(f));
+    // Compute symmetric difference, excluding allowlisted files
+    const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f) && !isAllowlisted(f));
     const missingFiles = [...normalizedExpected].filter(f => !projectFiles.includes(f));
     const violations = [];
     for (const f of unexpectedFiles) {
@@ -62,7 +70,7 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
 // ─── Internals ──────────────────────────────────────────────────────────────
 function getChangedFilesFromLastCommit(basePath) {
     try {
-        const result = execFileSync("git", ["diff", "--name-only", "HEAD~1", "HEAD"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+        const result = execFileSync("git", ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
         return result ? result.split("\n").filter(Boolean) : [];
     }
     catch (e) {

package/dist/resources/extensions/gsd/safety/safety-harness.js

@@ -23,6 +23,7 @@ const DEFAULTS = {
     checkpoints: true,
     auto_rollback: false,
     timeout_scale_cap: 6,
+    file_change_allowlist: [],
 };
 // ─── Public API ─────────────────────────────────────────────────────────────
 /**
@@ -42,6 +43,9 @@ export function resolveSafetyHarnessConfig(raw) {
         checkpoints: typeof raw.checkpoints === "boolean" ? raw.checkpoints : DEFAULTS.checkpoints,
         auto_rollback: typeof raw.auto_rollback === "boolean" ? raw.auto_rollback : DEFAULTS.auto_rollback,
         timeout_scale_cap: typeof raw.timeout_scale_cap === "number" ? raw.timeout_scale_cap : DEFAULTS.timeout_scale_cap,
+        file_change_allowlist: Array.isArray(raw.file_change_allowlist)
+            ? raw.file_change_allowlist.filter((p) => typeof p === "string")
+            : DEFAULTS.file_change_allowlist,
     };
 }
 /**
@@ -56,7 +60,7 @@ export function isHarnessEnabled(raw) {
     return DEFAULTS.enabled;
 }
 // ─── Re-exports ─────────────────────────────────────────────────────────────
-export { resetEvidence, getEvidence, getBashEvidence, getFilePaths, recordToolCall, recordToolResult, } from "./evidence-collector.js";
+export { resetEvidence, getEvidence, getBashEvidence, getFilePaths, recordToolCall, recordToolResult, saveEvidenceToDisk, loadEvidenceFromDisk, clearEvidenceFromDisk, } from "./evidence-collector.js";
 export { classifyCommand } from "./destructive-guard.js";
 export { validateFileChanges } from "./file-change-validator.js";
 export { crossReferenceEvidence } from "./evidence-cross-ref.js";

package/dist/resources/extensions/gsd/state-transition-matrix.js

@@ -0,0 +1,118 @@
+export const STATE_TRANSITION_MATRIX = [
+    {
+        from: "needs-discussion",
+        event: "context-ready",
+        guard: "CONTEXT artifact exists or PRD/context express path produced context",
+        to: "researching",
+        onFail: "needs-discussion",
+        reasonCode: "state",
+    },
+    {
+        from: "researching",
+        event: "research-ready",
+        guard: "RESEARCH artifact exists or research is explicitly skipped",
+        to: "planning",
+        onFail: "researching",
+        reasonCode: "state",
+    },
+    {
+        from: "planning",
+        event: "plan-ready",
+        guard: "ROADMAP/PLAN artifacts exist and plan gate passes",
+        to: "executing",
+        onFail: "replanning-slice",
+        reasonCode: "state",
+    },
+    {
+        from: "executing",
+        event: "task-dispatched",
+        guard: "task inputs are ready and dependencies are closed",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "dependency",
+    },
+    {
+        from: "executing",
+        event: "slice-complete",
+        guard: "all slice tasks are closed and verification gate passes",
+        to: "summarizing",
+        onFail: "validating-milestone",
+        reasonCode: "state",
+    },
+    {
+        from: "summarizing",
+        event: "summary-ready",
+        guard: "SUMMARY artifact exists for the completed work unit",
+        to: "validating-milestone",
+        onFail: "summarizing",
+        reasonCode: "state",
+    },
+    {
+        from: "validating-milestone",
+        event: "validation-pass",
+        guard: "validation verdict is terminal and not remediation-required",
+        to: "completing-milestone",
+        onFail: "blocked",
+        reasonCode: "state",
+    },
+    {
+        from: "blocked",
+        event: "recovery-plan-ready",
+        guard: "reassessment produced an executable next action",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "recovery",
+    },
+    {
+        from: "replanning-slice",
+        event: "replan-ready",
+        guard: "replacement slice/task plan exists and plan gate passes",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "recovery",
+    },
+    {
+        from: "completing-milestone",
+        event: "closeout-complete",
+        guard: "closeout gate passes and git transaction succeeds",
+        to: "complete",
+        onFail: "blocked",
+        reasonCode: "state",
+    },
+    {
+        from: "*",
+        event: "manual-block",
+        guard: "operator or hard gate requested manual attention",
+        to: "blocked",
+        onFail: "manual-attention",
+        reasonCode: "manual",
+    },
+    {
+        from: "*",
+        event: "retryable-failure",
+        guard: "retry budget remains for failure class",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "retry",
+    },
+];
+export function findTransition(from, event) {
+    return STATE_TRANSITION_MATRIX.find((entry) => (entry.from === from || entry.from === "*") && entry.event === event);
+}
+export function validateTransitionMatrix(requiredEvents) {
+    const seen = new Set();
+    const duplicateKeys = [];
+    for (const entry of STATE_TRANSITION_MATRIX) {
+        const key = `${entry.from}:${entry.event}`;
+        if (seen.has(key))
+            duplicateKeys.push(key);
+        seen.add(key);
+    }
+    const availableEvents = new Set(STATE_TRANSITION_MATRIX.map((entry) => entry.event));
+    const missingEvents = requiredEvents.filter((event) => !availableEvents.has(event));
+    return {
+        ok: missingEvents.length === 0 && duplicateKeys.length === 0,
+        missingEvents,
+        duplicateKeys,
+    };
+}

package/dist/resources/extensions/gsd/state.js

@@ -15,6 +15,7 @@ import { logWarning, logError } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { loadEffectiveGSDPreferences } from './preferences.js';
 import { detectPendingEscalation } from './escalation.js';
+import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
 import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, insertSlice, insertTask, updateSliceStatus, updateTaskStatus, getPendingGateCountForTurn, autoHealSketchFlags, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -81,6 +82,10 @@ export function isMilestoneComplete(roadmap) {
 export function isValidationTerminal(validationContent) {
     return extractVerdict(validationContent) != null;
 }
+async function isTerminalMilestoneSummaryFile(path, loader) {
+    const content = await loader(path);
+    return content != null && isTerminalMilestoneSummaryContent(content);
+}
 const CACHE_TTL_MS = 100;
 let _stateCache = null;
 // ── Telemetry counters for derive-path observability ────────────────────────
@@ -138,18 +143,19 @@ export async function getActiveMilestoneId(basePath) {
         const content = roadmapFile ? await loadFile(roadmapFile) : null;
         if (!content) {
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile)
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile))
                 continue;
             if (isGhostMilestone(basePath, mid))
                 continue;
             return mid;
         }
         const roadmap = parseRoadmap(content);
-        if (!isMilestoneComplete(roadmap)) {
-            const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (!summaryFile)
-                return mid;
-        }
+        const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+        if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile))
+            continue;
+        if (!isMilestoneComplete(roadmap))
+            return mid;
+        return mid;
     }
     return null;
 }
@@ -501,7 +507,7 @@ async function handleAllSlicesDone(basePath, activeMilestone, registry, requirem
     const validationContent = validationFile ? await loadFile(validationFile) : null;
     const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false;
     const verdict = validationContent ? extractVerdict(validationContent) : undefined;
-    if (!validationTerminal || verdict === 'needs-remediation') {
+    if (!validationTerminal) {
         return {
             activeMilestone, activeSlice: null, activeTask: null,
             phase: 'validating-milestone',
@@ -511,6 +517,23 @@ async function handleAllSlicesDone(basePath, activeMilestone, registry, requirem
             progress: { milestones: milestoneProgress, slices: sliceProgress },
         };
     }
+    // All roadmap slices are done (enforced by caller) and verdict is
+    // needs-remediation — remediation cannot progress without new slices.
+    // Return blocked instead of re-dispatching validate-milestone (#4506).
+    if (verdict === 'needs-remediation') {
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase: 'blocked',
+            recentDecisions: [],
+            blockers: [
+                `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
+                    `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+            ],
+            nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
     return {
         activeMilestone, activeSlice: null, activeTask: null,
         phase: 'completing-milestone',
@@ -533,7 +556,6 @@ function resolveSliceDependencies(activeMilestoneSlices) {
             return { activeSlice: null, activeSliceRow: null };
         }
     }
-    // First pass: find a slice with ALL dependencies satisfied (strict)
     let bestFallback = null;
     let bestFallbackSatisfied = -1;
     for (const s of activeMilestoneSlices) {
@@ -544,17 +566,12 @@ function resolveSliceDependencies(activeMilestoneSlices) {
         if (s.depends.every(dep => doneSliceIds.has(dep))) {
             return { activeSlice: { id: s.id, title: s.title }, activeSliceRow: s };
         }
-        // Track the slice with the most satisfied dependencies as fallback
         const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
         if (satisfied > bestFallbackSatisfied || (satisfied === bestFallbackSatisfied && !bestFallback)) {
             bestFallback = s;
             bestFallbackSatisfied = satisfied;
         }
     }
-    // Fallback: if no slice has all deps met but there ARE incomplete non-deferred
-    // slices, pick the one with the most deps satisfied. This prevents hard-blocking
-    // when dependency metadata is stale (e.g. after reassessment added/removed slices)
-    // or when deps reference slices from previous milestones.
     if (bestFallback) {
         const unmet = bestFallback.depends.filter(dep => !doneSliceIds.has(dep));
         logWarning("state", `No slice has all deps satisfied — falling back to ${bestFallback.id} ` +
@@ -971,7 +988,7 @@ export async function _deriveStateImpl(basePath) {
         const rc = rf ? await cachedLoadFile(rf) : null;
         if (!rc) {
             const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (sf)
+            if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
                 completeMilestoneIds.add(mid);
             continue;
         }
@@ -981,12 +998,12 @@ export async function _deriveStateImpl(basePath) {
             // Summary is the terminal artifact — if it exists, the milestone is
             // complete even when roadmap checkboxes weren't ticked (#864).
             const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (sf)
+            if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
                 completeMilestoneIds.add(mid);
             continue;
         }
         const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-        if (sf)
+        if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
             completeMilestoneIds.add(mid);
     }
     // Phase 2: Build registry using cached roadmaps (no re-parsing or re-reading)
@@ -1011,12 +1028,14 @@ export async function _deriveStateImpl(basePath) {
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
             if (summaryFile) {
                 const summaryContent = await cachedLoadFile(summaryFile);
-                const summaryTitle = summaryContent
-                    ? (parseSummary(summaryContent).title || mid)
-                    : mid;
-                registry.push({ id: mid, title: summaryTitle, status: 'complete' });
-                completeMilestoneIds.add(mid);
-                continue;
+                if (summaryContent != null && isTerminalMilestoneSummaryContent(summaryContent)) {
+                    const summaryTitle = summaryContent
+                        ? (parseSummary(summaryContent).title || mid)
+                        : mid;
+                    registry.push({ id: mid, title: summaryTitle, status: 'complete' });
+                    completeMilestoneIds.add(mid);
+                    continue;
+                }
             }
             // Ghost milestone (only META.json, no CONTEXT/ROADMAP/SUMMARY) — skip entirely
             if (isGhostMilestone(basePath, mid))
@@ -1070,7 +1089,7 @@ export async function _deriveStateImpl(basePath) {
             const verdict = validationContent ? extractVerdict(validationContent) : undefined;
             // needs-remediation is terminal but requires re-validation (#3596)
             const needsRevalidation = !validationTerminal || verdict === 'needs-remediation';
-            if (summaryFile) {
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
                 // Summary exists → milestone is complete regardless of validation state.
                 // The summary is the terminal artifact (#864).
                 registry.push({ id: mid, title, status: 'complete' });
@@ -1101,7 +1120,7 @@ export async function _deriveStateImpl(basePath) {
             // Roadmap slices not all checked — but if a summary exists, the milestone
             // is still complete. The summary is the terminal artifact (#864).
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile) {
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
                 registry.push({ id: mid, title, status: 'complete' });
             }
             else if (!activeMilestoneFound) {
@@ -1278,9 +1297,11 @@ export async function _deriveStateImpl(basePath) {
             done: activeRoadmap.slices.length,
             total: activeRoadmap.slices.length,
         };
-        // Force re-validation when verdict is needs-remediation — remediation slices
-        // may have completed since the stale validation was written (#3596).
-        if (!validationTerminal || verdict === 'needs-remediation') {
+        // Force re-validation when VALIDATION.md is absent or non-terminal —
+        // remediation slices may have completed since the stale validation was
+        // written (#3596). But needs-remediation with all slices done is a dead
+        // end — return blocked to avoid an infinite dispatch loop (#4506).
+        if (!validationTerminal) {
             return {
                 activeMilestone,
                 activeSlice: null,
@@ -1297,6 +1318,26 @@ export async function _deriveStateImpl(basePath) {
                 },
             };
         }
+        if (verdict === 'needs-remediation') {
+            return {
+                activeMilestone,
+                activeSlice: null,
+                activeTask: null,
+                phase: 'blocked',
+                recentDecisions: [],
+                blockers: [
+                    `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
+                        `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+                ],
+                nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+                registry,
+                requirements,
+                progress: {
+                    milestones: milestoneProgress,
+                    slices: sliceProgress,
+                },
+            };
+        }
         return {
             activeMilestone,
             activeSlice: null,
@@ -1357,14 +1398,12 @@ export async function _deriveStateImpl(basePath) {
                 activeSlice = { id: s.id, title: s.title };
                 break;
             }
-            // Track best fallback
             const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
             if (satisfied > bestFallbackLegacySatisfied) {
                 bestFallbackLegacy = s;
                 bestFallbackLegacySatisfied = satisfied;
             }
         }
-        // Fallback: if no slice has all deps met, pick the one with the most deps satisfied
         if (!activeSlice && bestFallbackLegacy) {
             const unmet = bestFallbackLegacy.depends.filter(dep => !doneSliceIds.has(dep));
             logWarning("state", `No slice has all deps satisfied — falling back to ${bestFallbackLegacy.id} ` +

package/dist/resources/extensions/gsd/token-counter.js

@@ -16,7 +16,11 @@ async function getEncoder() {
     try {
         // @ts-ignore — tiktoken may not have type declarations in extensions tsconfig
         const tiktoken = await import("tiktoken");
-        encoder = tiktoken.encoding_for_model("gpt-4o");
+        // 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");
         return encoder;
     }
     catch {
@@ -24,19 +28,32 @@ async function getEncoder() {
         return null;
     }
 }
-export async function countTokens(text) {
+/**
+ * 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, provider) {
     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) {
+/**
+ * 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, provider) {
     if (encoder) {
         return encoder.encode(text).length;
     }
-    return Math.ceil(text.length / 4);
+    return estimateTokensForProvider(text, provider ?? "unknown");
 }
 export async function initTokenCounter() {
     const enc = await getEncoder();

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -6,7 +6,7 @@
  * for recovery, and invalidates caches.
  */
 import { join } from "node:path";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, existsSync } from "node:fs";
 import { transaction, getMilestone, getMilestoneSlices, getSliceTasks, updateMilestoneStatus, } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { isClosedStatus } from "../status-guards.js";
@@ -141,15 +141,21 @@ export async function handleCompleteMilestone(params, basePath) {
         mkdirSync(manualDir, { recursive: true });
         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.message}`);
-        updateMilestoneStatus(params.milestoneId, 'active', null);
-        invalidateStateCache();
-        return { error: `disk render failed: ${renderErr.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.message}`);
+            updateMilestoneStatus(params.milestoneId, 'active', null);
+            invalidateStateCache();
+            return { error: `disk render failed: ${renderErr.message}` };
+        }
     }
     // Invalidate all caches
     invalidateStateCache();

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -16,6 +16,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";
@@ -228,6 +229,10 @@ export async function handleCompleteSlice(params, basePath) {
         }
         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;
         }
@@ -248,6 +253,22 @@ export async function handleCompleteSlice(params, basePath) {
         insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId });
         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 };
     }