gsd-pi 2.77.0 → 2.78.0

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;
 }
@@ -182,7 +188,7 @@ export async function deriveState(basePath) {
             let synced = false;
             for (const diskId of diskIds) {
                 if (!isGhostMilestone(basePath, diskId)) {
-                    insertMilestone({ id: diskId, status: 'active' });
+                    insertMilestone(diskMilestoneInsert(basePath, diskId));
                     synced = true;
                 }
             }
@@ -240,6 +246,36 @@ function extractContextTitle(content, fallback) {
 // isStatusDone replaced by isClosedStatus from status-guards.ts (single source of truth).
 // Alias kept for backward compatibility within this file.
 const isStatusDone = isClosedStatus;
+function loadSync(path) {
+    if (!path)
+        return null;
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function diskMilestoneInsert(basePath, mid) {
+    const contextContent = loadSync(resolveMilestoneFile(basePath, mid, "CONTEXT"));
+    const draftContent = !contextContent ? loadSync(resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT")) : null;
+    const roadmapContent = loadSync(resolveMilestoneFile(basePath, mid, "ROADMAP"));
+    const summaryContent = loadSync(resolveMilestoneFile(basePath, mid, "SUMMARY"));
+    const roadmap = roadmapContent ? parseRoadmap(roadmapContent) : null;
+    const summary = summaryContent ? parseSummary(summaryContent) : null;
+    const summaryTerminal = summaryContent != null && isTerminalMilestoneSummaryContent(summaryContent);
+    const parked = resolveMilestoneFile(basePath, mid, "PARKED") !== null;
+    return {
+        id: mid,
+        title: roadmap
+            ? stripMilestonePrefix(roadmap.title)
+            : (contextContent || draftContent)
+                ? extractContextTitle(contextContent || draftContent, mid)
+                : (summary?.title || mid),
+        status: parked ? "parked" : summaryTerminal ? "complete" : "active",
+        depends_on: parseContextDependsOn(contextContent ?? draftContent),
+    };
+}
 /**
  * Derive GSD state from the milestones/slices/tasks DB tables.
  * Flag files (PARKED, VALIDATION, CONTINUE, REPLAN, REPLAN-TRIGGER, CONTEXT-DRAFT)
@@ -255,7 +291,7 @@ function reconcileDiskToDb(basePath) {
     let synced = false;
     for (const diskId of diskIds) {
         if (!dbIdSet.has(diskId) && !isGhostMilestone(basePath, diskId)) {
-            insertMilestone({ id: diskId, status: 'active' });
+            insertMilestone(diskMilestoneInsert(basePath, diskId));
             synced = true;
         }
     }
@@ -550,9 +586,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) {
         if (isStatusDone(s.status))
             continue;
@@ -561,36 +594,25 @@ 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} ` +
-            `(${bestFallbackSatisfied}/${bestFallback.depends.length} deps met, ` +
-            `unmet: ${unmet.join(", ")})`, { mid: activeMilestoneSlices[0]?.milestone_id, sid: bestFallback.id });
-        return { activeSlice: { id: bestFallback.id, title: bestFallback.title }, activeSliceRow: bestFallback };
     }
     return { activeSlice: null, activeSliceRow: null };
 }
 async function reconcileSliceTasks(basePath, milestoneId, sliceId, planFile) {
     let tasks = getSliceTasks(milestoneId, sliceId);
-    if (tasks.length === 0 && planFile) {
+    // #3600/#4974: import missing plan-file tasks even when the DB already has
+    // a partial task set. Existing DB task statuses stay authoritative.
+    if (planFile) {
         try {
             const planContent = await loadFile(planFile);
             if (planContent) {
                 const diskPlan = parsePlan(planContent);
                 if (diskPlan.tasks.length > 0) {
+                    const dbTaskIds = new Set(tasks.map(t => t.id));
+                    let inserted = 0;
                     for (let i = 0; i < diskPlan.tasks.length; i++) {
                         const t = diskPlan.tasks[i];
+                        if (dbTaskIds.has(t.id))
+                            continue;
                         try {
                             insertTask({
                                 id: t.id,
@@ -600,13 +622,16 @@ async function reconcileSliceTasks(basePath, milestoneId, sliceId, planFile) {
                                 status: t.done ? 'complete' : 'pending',
                                 sequence: i + 1,
                             });
+                            inserted++;
                         }
                         catch (insertErr) {
                             logWarning("reconcile", `failed to insert task ${t.id} from plan file: ${insertErr instanceof Error ? insertErr.message : String(insertErr)}`);
                         }
                     }
-                    tasks = getSliceTasks(milestoneId, sliceId);
-                    logWarning("reconcile", `imported ${tasks.length} tasks from plan file for ${milestoneId}/${sliceId} — DB was empty (#3600)`, { mid: milestoneId, sid: sliceId });
+                    if (inserted > 0) {
+                        tasks = getSliceTasks(milestoneId, sliceId);
+                        logWarning("reconcile", `imported ${inserted} missing task(s) from plan file for ${milestoneId}/${sliceId}`, { mid: milestoneId, sid: sliceId });
+                    }
                 }
             }
         }
@@ -988,7 +1013,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;
         }
@@ -998,12 +1023,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)
@@ -1028,12 +1053,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))
@@ -1087,7 +1114,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' });
@@ -1118,7 +1145,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) {
@@ -1387,8 +1414,6 @@ export async function _deriveStateImpl(basePath) {
         }
     }
     else {
-        let bestFallbackLegacy = null;
-        let bestFallbackLegacySatisfied = -1;
         for (const s of activeRoadmap.slices) {
             if (s.done)
                 continue;
@@ -1396,20 +1421,6 @@ 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} ` +
-                `(${bestFallbackLegacySatisfied}/${bestFallbackLegacy.depends.length} deps met, ` +
-                `unmet: ${unmet.join(", ")})`);
-            activeSlice = { id: bestFallbackLegacy.id, title: bestFallbackLegacy.title };
         }
     }
     if (!activeSlice) {

package/dist/resources/extensions/gsd/sync-lock.js

@@ -1,10 +1,9 @@
 // GSD Extension — Advisory Sync Lock
 // Prevents concurrent worktree syncs from colliding via a simple file lock.
-// Stale locks (mtime > 60s) are auto-overridden. Lock acquisition waits up
-// to 5 seconds then skips non-fatally.
-import { existsSync, statSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { atomicWriteSync } from "./atomic-write.js";
+// Stale locks (mtime > 60s, owner PID confirmed dead) are overridden. Lock
+// acquisition waits up to 5 seconds then skips non-fatally.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
 const DEFAULT_TIMEOUT_MS = 5_000; // 5 seconds
 const SPIN_INTERVAL_MS = 100; // 100ms polling interval
@@ -17,60 +16,117 @@ function lockFilePath(basePath) {
 function sleepSync(ms) {
     Atomics.wait(SLEEP_VIEW, 0, 0, ms);
 }
+/** True if the given PID is alive in the current process namespace. */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EPERM")
+            return true;
+        return false;
+    }
+}
+/**
+ * Atomically create the lock file with `O_EXCL` semantics. Returns true on
+ * exclusive create, false if the file already existed. Any other error
+ * propagates.
+ */
+function tryCreateLockFile(lp, payload) {
+    // Ensure parent dir exists (`atomicWriteSync` previously did this implicitly).
+    try {
+        mkdirSync(dirname(lp), { recursive: true });
+    }
+    catch {
+        /* best-effort */
+    }
+    let fd;
+    try {
+        // "wx" → O_WRONLY | O_CREAT | O_EXCL — atomic create-if-not-exists on POSIX.
+        fd = openSync(lp, "wx");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST")
+            return false;
+        throw err;
+    }
+    try {
+        writeSync(fd, payload);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return true;
+}
 /**
  * Acquire an advisory sync lock for the given basePath.
  * Returns { acquired: true } on success, { acquired: false } after timeout.
  *
- * - Creates lock file at {basePath}/.gsd/sync.lock with JSON { pid, acquired_at }
- * - If lock exists and mtime > 60s (stale), overrides it
- * - If lock exists and not stale, spins up to timeoutMs before giving up
+ * Replaces a non-atomic `existsSync` + `atomicWriteSync` (write-temp+rename,
+ * which is not exclusive-create) sequence that allowed two callers to both
+ * believe they had acquired the lock, corrupting the event log.
+ * (Issue #4980 CRIT-4)
+ *
+ * Stale-lock override now also verifies the recorded owner PID is dead
+ * before stealing — prevents a slow event-loop pause (>60s under heavy I/O)
+ * from making a legitimately-held lock appear stale and get stolen.
+ * (Issue #4980 M-concurrency-3)
  */
 export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lp = lockFilePath(basePath);
     const deadline = Date.now() + timeoutMs;
+    const lockData = JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }, null, 2);
     while (true) {
-        // Check if lock file exists
-        if (existsSync(lp)) {
-            // Check staleness
-            try {
-                const stat = statSync(lp);
-                const age = Date.now() - stat.mtimeMs;
-                if (age > STALE_THRESHOLD_MS) {
-                    // Stale lock — override it
-                    try {
-                        unlinkSync(lp);
+        // First try the fast path: atomic create. No check-then-write race.
+        try {
+            if (tryCreateLockFile(lp, lockData)) {
+                return { acquired: true };
+            }
+        }
+        catch {
+            /* unexpected — fall through to retry */
+        }
+        // File exists. Decide whether to steal (stale + owner dead) or wait.
+        let canSteal = false;
+        try {
+            const stat = statSync(lp);
+            const age = Date.now() - stat.mtimeMs;
+            if (age > STALE_THRESHOLD_MS) {
+                // Verify the recorded owner PID is dead before stealing.
+                let ownerAlive = false;
+                try {
+                    const data = JSON.parse(readFileSync(lp, "utf-8"));
+                    if (typeof data.pid === "number" && data.pid !== process.pid) {
+                        ownerAlive = isPidAlive(data.pid);
                     }
-                    catch { /* race: already removed */ }
                 }
-                else {
-                    // Lock is held and not stale — wait or give up
-                    if (Date.now() >= deadline) {
-                        return { acquired: false };
-                    }
-                    sleepSync(SPIN_INTERVAL_MS);
-                    continue;
+                catch {
+                    // Lock contents unreadable — be conservative and steal only on age.
+                    // A garbage lock file that we cannot parse is safer to remove than
+                    // to leave wedging the lock indefinitely.
                 }
+                canSteal = !ownerAlive;
             }
-            catch {
-                // stat failed (file removed between exists check and stat) — try to acquire
-            }
-        }
-        // Lock file does not exist (or was just removed) — try to write it
-        try {
-            const lockData = {
-                pid: process.pid,
-                acquired_at: new Date().toISOString(),
-            };
-            atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
-            return { acquired: true };
         }
         catch {
-            // Write failed (race condition with another process) — retry or give up
-            if (Date.now() >= deadline) {
-                return { acquired: false };
+            // stat failed (file removed between exists and stat) — retry create.
+            continue;
+        }
+        if (canSteal) {
+            try {
+                unlinkSync(lp);
             }
-            sleepSync(SPIN_INTERVAL_MS);
+            catch { /* race: already removed */ }
+            // Loop back to retry create.
+            continue;
+        }
+        // Lock is held and not stale (or owner is alive) — wait or give up.
+        if (Date.now() >= deadline) {
+            return { acquired: false };
         }
+        sleepSync(SPIN_INTERVAL_MS);
     }
 }
 /**

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 };
     }

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

@@ -21,6 +21,7 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose
@@ -167,6 +168,18 @@ export async function handleCompleteTask(params, basePath) {
         }
         const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
         if (existingTask && isClosedStatus(existingTask.status)) {
+            // Stale-turn path: a timed-out turn that was superseded by recovery
+            // can still reach this code when its LLM call eventually returns and
+            // invokes gsd_complete_task. Returning an error would produce noisy
+            // "already complete — use reopen first" logs in the orphaned turn.
+            // Instead, signal the duplicate via a non-mutating success shape that
+            // callers can detect via `duplicate: true` / `stale: true`.
+            if (isStaleWrite("complete-task")) {
+                // Sentinel handled below — outside the transaction — so we don't
+                // render SUMMARY.md or flip plan checkboxes for a stale duplicate.
+                guardError = "__stale_duplicate__";
+                return;
+            }
             guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
             return;
         }
@@ -201,6 +214,24 @@ export async function handleCompleteTask(params, basePath) {
             });
         }
     });
+    if (guardError === "__stale_duplicate__") {
+        // Orphaned-turn duplicate: the task is already complete from the
+        // superseded turn's earlier (real) call. Return a non-mutating success
+        // so the stale LLM tool call unwinds cleanly. summaryPath is synthesized
+        // from the existing on-disk layout; no file is written.
+        const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+        const staleSummaryPath = tasksDir
+            ? join(tasksDir, `${params.taskId}-SUMMARY.md`)
+            : join(basePath, ".gsd", "milestones", params.milestoneId, "slices", params.sliceId, "tasks", `${params.taskId}-SUMMARY.md`);
+        return {
+            taskId: params.taskId,
+            sliceId: params.sliceId,
+            milestoneId: params.milestoneId,
+            summaryPath: staleSummaryPath,
+            duplicate: true,
+            stale: true,
+        };
+    }
     if (guardError) {
         return { error: guardError };
     }