gsd-pi 2.33.1-dev.ee47f1b → 2.34.0-dev.0150ae9

package/dist/resources/extensions/gsd/auto-supervisor.js

@@ -1,14 +1,13 @@
 /**
- * Auto-mode Supervisor — signal handling and working-tree activity detection.
+ * Auto-mode Supervisor — SIGTERM handling and working-tree activity detection.
  *
  * Pure functions — no module-level globals or AutoContext dependency.
  */
 import { clearLock } from "./crash-recovery.js";
-import { releaseSessionLock } from "./session-lock.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
-// ─── Signal Handling ──────────────────────────────────────────────────────────
+// ─── SIGTERM Handling ─────────────────────────────────────────────────────────
 /**
- * Register SIGTERM and SIGINT handlers that clear lock files and exit cleanly.
+ * Register a SIGTERM handler that clears the lock file and exits cleanly.
  * Captures the active base path at registration time so the handler
  * always references the correct path even if the module variable changes.
  * Removes any previously registered handler before installing the new one.
@@ -16,24 +15,19 @@ import { nativeHasChanges } from "./native-git-bridge.js";
  * Returns the new handler so the caller can store and deregister it later.
  */
 export function registerSigtermHandler(currentBasePath, previousHandler) {
-    if (previousHandler) {
+    if (previousHandler)
         process.off("SIGTERM", previousHandler);
-        process.off("SIGINT", previousHandler);
-    }
     const handler = () => {
-        releaseSessionLock(currentBasePath);
         clearLock(currentBasePath);
         process.exit(0);
     };
     process.on("SIGTERM", handler);
-    process.on("SIGINT", handler);
     return handler;
 }
-/** Deregister signal handlers (called on stop/pause). */
+/** Deregister the SIGTERM handler (called on stop/pause). */
 export function deregisterSigtermHandler(handler) {
     if (handler) {
         process.off("SIGTERM", handler);
-        process.off("SIGINT", handler);
     }
 }
 // ─── Working Tree Activity Detection ──────────────────────────────────────────

package/dist/resources/extensions/gsd/auto-timeout-recovery.js

@@ -6,9 +6,9 @@
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord, formatExecuteTaskRecoveryStatus, inspectExecuteTaskDurability, } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, skipExecuteTask, writeBlockerPlaceholder, } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
-import { parseUnitId } from "./unit-id.js";
+import { resolveAgentEnd } from "./auto-loop.js";
 export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rctx) {
-    const { basePath, verbose, currentUnitStartedAt, unitRecoveryCount, dispatchNextUnit } = rctx;
+    const { basePath, verbose, currentUnitStartedAt, unitRecoveryCount } = rctx;
     const runtime = readUnitRuntimeRecord(basePath, unitType, unitId);
     const recoveryAttempts = runtime?.recoveryAttempts ?? 0;
     const maxRecoveryAttempts = reason === "idle" ? 2 : 1;
@@ -36,7 +36,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
             });
             ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} already completed on disk. Continuing auto-mode. (attempt ${attemptNumber})`, "info");
             unitRecoveryCount.delete(recoveryKey);
-            await dispatchNextUnit(ctx, pi);
+            resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
             return "recovered";
         }
         if (recoveryAttempts < maxRecoveryAttempts) {
@@ -80,7 +80,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         }
         // Retries exhausted — write missing durable artifacts and advance.
         const diagnostic = formatExecuteTaskRecoveryStatus(status);
-        const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+        const [mid, sid, tid] = unitId.split("/");
         const skipped = mid && sid && tid
             ? skipExecuteTask(basePath, mid, sid, tid, status, reason, maxRecoveryAttempts)
             : false;
@@ -93,7 +93,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
             });
             ctx.ui.notify(`${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts (${diagnostic}). Blocker artifacts written. Advancing pipeline. (attempt ${attemptNumber})`, "warning");
             unitRecoveryCount.delete(recoveryKey);
-            await dispatchNextUnit(ctx, pi);
+            resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
             return "recovered";
         }
         // Fallback: couldn't write skip artifacts — pause as before.
@@ -118,7 +118,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         });
         ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} artifact already exists on disk. Advancing. (attempt ${attemptNumber})`, "info");
         unitRecoveryCount.delete(recoveryKey);
-        await dispatchNextUnit(ctx, pi);
+        resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
         return "recovered";
     }
     if (recoveryAttempts < maxRecoveryAttempts) {
@@ -170,7 +170,7 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         });
         ctx.ui.notify(`${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts. Blocker placeholder written to ${placeholder}. Advancing pipeline. (attempt ${attemptNumber})`, "warning");
         unitRecoveryCount.delete(recoveryKey);
-        await dispatchNextUnit(ctx, pi);
+        resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
         return "recovered";
     }
     // Fallback: couldn't resolve artifact path — pause as before.

package/dist/resources/extensions/gsd/auto-timers.js

@@ -2,7 +2,7 @@
  * Unit supervision timers — soft timeout warning, idle watchdog,
  * hard timeout, and context-pressure monitor.
  *
- * Extracted from dispatchNextUnit() in auto.ts. All timers are set up
+ * Originally extracted from dispatchNextUnit() in auto.ts (now deleted — replaced by autoLoop).
  * via startUnitSupervision() and torn down by the caller via clearUnitTimeout().
  */
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "./unit-runtime.js";
@@ -13,7 +13,6 @@ import { detectWorkingTreeActivity } from "./auto-supervisor.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { saveActivityLog } from "./activity-log.js";
 import { recoverTimedOutUnit } from "./auto-timeout-recovery.js";
-import { getErrorMessage } from "./error-utils.js";
 /**
  * Set up all four supervision timers for the current unit:
  * 1. Soft timeout warning (wrapup)
@@ -98,7 +97,7 @@ export function startUnitSupervision(sctx) {
             await pauseAuto(ctx, pi);
         }
         catch (err) {
-            const message = getErrorMessage(err);
+            const message = err instanceof Error ? err.message : String(err);
             console.error(`[idle-watchdog] Unhandled error: ${message}`);
             try {
                 ctx.ui.notify(`Idle watchdog error: ${message}`, "warning");
@@ -129,7 +128,7 @@ export function startUnitSupervision(sctx) {
             await pauseAuto(ctx, pi);
         }
         catch (err) {
-            const message = getErrorMessage(err);
+            const message = err instanceof Error ? err.message : String(err);
             console.error(`[hard-timeout] Unhandled error: ${message}`);
             try {
                 ctx.ui.notify(`Hard timeout error: ${message}`, "warning");

package/dist/resources/extensions/gsd/auto-verification.js

@@ -14,18 +14,18 @@ import { resolveSliceFile, resolveSlicePath } from "./paths.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
-import { removePersistedKey } from "./auto-recovery.js";
 import { join } from "node:path";
-import { getErrorMessage } from "./error-utils.js";
-import { parseUnitId } from "./unit-id.js";
+function isInfraVerificationFailure(stderr) {
+    return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(stderr);
+}
 /**
  * Run the verification gate for the current execute-task unit.
  * Returns:
  * - "continue" — gate passed (or no checks configured), proceed normally
- * - "retry" — gate failed with retries remaining, dispatchNextUnit already called
+ * - "retry" — gate failed with retries remaining, s.pendingVerificationRetry set for loop re-iteration
  * - "pause" — gate failed with retries exhausted, pauseAuto already called
  */
-export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispatchGapWatchdog, pauseAuto) {
+export async function runPostUnitVerification(vctx, pauseAuto) {
     const { s, ctx, pi } = vctx;
     if (!s.currentUnit || s.currentUnit.type !== "execute-task") {
         return "continue";
@@ -34,15 +34,16 @@ export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispa
         const effectivePrefs = loadEffectiveGSDPreferences();
         const prefs = effectivePrefs?.preferences;
         // Read task plan verify field
-        const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
+        const parts = s.currentUnit.id.split("/");
         let taskPlanVerify;
-        if (mid && sid && tid) {
+        if (parts.length >= 3) {
+            const [mid, sid, tid] = parts;
             const planFile = resolveSliceFile(s.basePath, mid, sid, "PLAN");
             if (planFile) {
                 const planContent = await loadFile(planFile);
                 if (planContent) {
                     const slicePlan = parsePlan(planContent);
-                    const taskEntry = slicePlan?.tasks?.find(t => t.id === tid);
+                    const taskEntry = slicePlan?.tasks?.find((t) => t.id === tid);
                     taskPlanVerify = taskEntry?.verify;
                 }
             }
@@ -58,7 +59,7 @@ export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispa
         const runtimeErrors = await captureRuntimeErrors();
         if (runtimeErrors.length > 0) {
             result.runtimeErrors = runtimeErrors;
-            if (runtimeErrors.some(e => e.blocking)) {
+            if (runtimeErrors.some((e) => e.blocking)) {
                 result.passed = false;
             }
         }
@@ -73,48 +74,30 @@ export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispa
         }
         // Auto-fix retry preferences
         const autoFixEnabled = prefs?.verification_auto_fix !== false;
-        const maxRetries = typeof prefs?.verification_max_retries === "number" ? prefs.verification_max_retries : 2;
-        const completionKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
+        const maxRetries = typeof prefs?.verification_max_retries === "number"
+            ? prefs.verification_max_retries
+            : 2;
         if (result.checks.length > 0) {
-            const blockingChecks = result.checks.filter(c => c.blocking);
-            const advisoryChecks = result.checks.filter(c => !c.blocking);
-            const blockingPassCount = blockingChecks.filter(c => c.exitCode === 0).length;
-            const advisoryFailCount = advisoryChecks.filter(c => c.exitCode !== 0).length;
+            const passCount = result.checks.filter((c) => c.exitCode === 0).length;
+            const total = result.checks.length;
             if (result.passed) {
-                let msg = blockingChecks.length > 0
-                    ? `Verification gate: ${blockingPassCount}/${blockingChecks.length} blocking checks passed`
-                    : `Verification gate: passed (no blocking checks)`;
-                if (advisoryFailCount > 0) {
-                    msg += ` (${advisoryFailCount} advisory warning${advisoryFailCount > 1 ? "s" : ""})`;
-                }
-                ctx.ui.notify(msg);
-                // Log advisory warnings to stderr for visibility
-                if (advisoryFailCount > 0) {
-                    const advisoryFailures = advisoryChecks.filter(c => c.exitCode !== 0);
-                    process.stderr.write(`verification-gate: ${advisoryFailCount} advisory (non-blocking) failure(s)\n`);
-                    for (const f of advisoryFailures) {
-                        process.stderr.write(`  [advisory] ${f.command} exited ${f.exitCode}\n`);
-                    }
-                }
+                ctx.ui.notify(`Verification gate: ${passCount}/${total} checks passed`);
             }
             else {
-                const blockingFailures = blockingChecks.filter(c => c.exitCode !== 0);
-                const failNames = blockingFailures.map(f => f.command).join(", ");
+                const failures = result.checks.filter((c) => c.exitCode !== 0);
+                const failNames = failures.map((f) => f.command).join(", ");
                 ctx.ui.notify(`Verification gate: FAILED — ${failNames}`);
-                process.stderr.write(`verification-gate: ${blockingFailures.length}/${blockingChecks.length} blocking checks failed\n`);
-                for (const f of blockingFailures) {
+                process.stderr.write(`verification-gate: ${total - passCount}/${total} checks failed\n`);
+                for (const f of failures) {
                     process.stderr.write(`  ${f.command} exited ${f.exitCode}\n`);
                     if (f.stderr)
                         process.stderr.write(`  stderr: ${f.stderr.slice(0, 500)}\n`);
                 }
-                if (advisoryFailCount > 0) {
-                    process.stderr.write(`verification-gate: ${advisoryFailCount} additional advisory (non-blocking) failure(s)\n`);
-                }
             }
         }
         // Log blocking runtime errors
-        if (result.runtimeErrors?.some(e => e.blocking)) {
-            const blockingErrors = result.runtimeErrors.filter(e => e.blocking);
+        if (result.runtimeErrors?.some((e) => e.blocking)) {
+            const blockingErrors = result.runtimeErrors.filter((e) => e.blocking);
             process.stderr.write(`verification-gate: ${blockingErrors.length} blocking runtime error(s) detected\n`);
             for (const err of blockingErrors) {
                 process.stderr.write(`  [${err.source}] ${err.severity}: ${err.message.slice(0, 200)}\n`);
@@ -122,8 +105,9 @@ export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispa
         }
         // Write verification evidence JSON
         const attempt = s.verificationRetryCount.get(s.currentUnit.id) ?? 0;
-        if (mid && sid && tid) {
+        if (parts.length >= 3) {
             try {
+                const [mid, sid, tid] = parts;
                 const sDir = resolveSlicePath(s.basePath, mid, sid);
                 if (sDir) {
                     const tasksDir = join(sDir, "tasks");
@@ -140,36 +124,24 @@ export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispa
                 process.stderr.write(`verification-evidence: write error — ${evidenceErr.message}\n`);
             }
         }
-        // ── Auto-fix retry logic ──
-        if (result.passed) {
-            s.verificationRetryCount.delete(s.currentUnit.id);
-            s.pendingVerificationRetry = null;
-            return "continue";
-        }
-        // Check if all failures are infra errors (ETIMEDOUT, ENOENT, etc.).
-        // Infra errors are transient OS-level problems the agent cannot fix —
-        // retrying the entire task is wasteful and creates phantom failures.
-        const failedChecks = result.checks.filter(c => c.exitCode !== 0);
-        const allInfraErrors = failedChecks.length > 0 && failedChecks.every(c => c.infraError === true);
-        if (allInfraErrors) {
-            const infraNames = failedChecks.map(f => f.command).join(", ");
-            ctx.ui.notify(`Verification gate: infra error (${infraNames}) — skipping retry, not a code issue`, "warning");
-            process.stderr.write(`verification-gate: all ${failedChecks.length} failure(s) are infra errors — treating as transient, no retry\n`);
+        const advisoryFailure = !result.passed &&
+            (result.discoverySource === "package-json" ||
+                result.checks.some((check) => isInfraVerificationFailure(check.stderr)));
+        if (advisoryFailure) {
             s.verificationRetryCount.delete(s.currentUnit.id);
             s.pendingVerificationRetry = null;
+            ctx.ui.notify(result.discoverySource === "package-json"
+                ? "Verification failed in auto-discovered package.json checks — treating as advisory."
+                : "Verification failed due to infrastructure/runtime environment issues — treating as advisory.", "warning");
             return "continue";
         }
-        if (result.discoverySource === "package-json") {
-            // Auto-discovered checks from package.json may fail on pre-existing errors
-            // that the current task didn't introduce. Don't trigger the retry loop —
-            // log a warning and let the task proceed (#1186).
-            process.stderr.write(`verification-gate: auto-discovered checks failed (source: package-json) — treating as advisory, not blocking\n`);
-            ctx.ui.notify(`Verification: auto-discovered checks failed (pre-existing errors likely). Continuing without retry.`, "warning");
+        // ── Auto-fix retry logic ──
+        if (result.passed) {
             s.verificationRetryCount.delete(s.currentUnit.id);
             s.pendingVerificationRetry = null;
             return "continue";
         }
-        if (autoFixEnabled && attempt + 1 <= maxRetries) {
+        else if (autoFixEnabled && attempt + 1 <= maxRetries) {
             const nextAttempt = attempt + 1;
             s.verificationRetryCount.set(s.currentUnit.id, nextAttempt);
             s.pendingVerificationRetry = {
@@ -178,17 +150,7 @@ export async function runPostUnitVerification(vctx, dispatchNextUnit, startDispa
                 attempt: nextAttempt,
             };
             ctx.ui.notify(`Verification failed — auto-fix attempt ${nextAttempt}/${maxRetries}`, "warning");
-            s.completedKeySet.delete(completionKey);
-            removePersistedKey(s.basePath, completionKey);
-            // Dispatch retry immediately
-            try {
-                await dispatchNextUnit(ctx, pi);
-            }
-            catch (retryDispatchErr) {
-                const msg = getErrorMessage(retryDispatchErr);
-                ctx.ui.notify(`Verification retry dispatch error: ${msg}`, "error");
-                startDispatchGapWatchdog(ctx, pi);
-            }
+            // Return "retry" — the autoLoop while loop will re-iterate with the retry context
             return "retry";
         }
         else {

package/dist/resources/extensions/gsd/auto-worktree-sync.js

@@ -0,0 +1,167 @@
+/**
+ * Worktree ↔ project root state synchronization for auto-mode.
+ *
+ * When auto-mode runs inside a worktree, dispatch-critical state files
+ * (.gsd/ metadata) diverge between the worktree (where work happens)
+ * and the project root (where startAutoMode reads initial state on restart).
+ * Without syncing, restarting auto-mode reads stale state from the project
+ * root and re-dispatches already-completed units.
+ *
+ * Also contains resource staleness detection and stale worktree escape.
+ */
+import { existsSync, readFileSync, unlinkSync, readdirSync, } from "node:fs";
+import { join, sep as pathSep } from "node:path";
+import { homedir } from "node:os";
+import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
+// ─── Project Root → Worktree Sync ─────────────────────────────────────────
+/**
+ * Sync milestone artifacts from project root INTO worktree before deriveState.
+ * Covers the case where the LLM wrote artifacts to the main repo filesystem
+ * (e.g. via absolute paths) but the worktree has stale data. Also deletes
+ * gsd.db in the worktree so it rebuilds from fresh disk state (#853).
+ * Non-fatal — sync failure should never block dispatch.
+ */
+export function syncProjectRootToWorktree(projectRoot, worktreePath, milestoneId) {
+    if (!worktreePath || !projectRoot || worktreePath === projectRoot)
+        return;
+    if (!milestoneId)
+        return;
+    const prGsd = join(projectRoot, ".gsd");
+    const wtGsd = join(worktreePath, ".gsd");
+    // Copy milestone directory from project root to worktree if the project root
+    // has newer artifacts (e.g. slices that don't exist in the worktree yet)
+    safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId));
+    // Delete worktree gsd.db so it rebuilds from the freshly synced files.
+    // Stale DB rows are the root cause of the infinite skip loop (#853).
+    try {
+        const wtDb = join(wtGsd, "gsd.db");
+        if (existsSync(wtDb)) {
+            unlinkSync(wtDb);
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+// ─── Worktree → Project Root Sync ─────────────────────────────────────────
+/**
+ * Sync dispatch-critical .gsd/ state files from worktree to project root.
+ * Only runs when inside an auto-worktree (worktreePath differs from projectRoot).
+ * Copies: STATE.md + active milestone directory (roadmap, slice plans, task summaries).
+ * Non-fatal — sync failure should never block dispatch.
+ */
+export function syncStateToProjectRoot(worktreePath, projectRoot, milestoneId) {
+    if (!worktreePath || !projectRoot || worktreePath === projectRoot)
+        return;
+    if (!milestoneId)
+        return;
+    const wtGsd = join(worktreePath, ".gsd");
+    const prGsd = join(projectRoot, ".gsd");
+    // 1. STATE.md — the quick-glance status used by initial deriveState()
+    safeCopy(join(wtGsd, "STATE.md"), join(prGsd, "STATE.md"), { force: true });
+    // 2. Milestone directory — ROADMAP, slice PLANs, task summaries
+    // Copy the entire milestone .gsd subtree so deriveState reads current checkboxes
+    safeCopyRecursive(join(wtGsd, "milestones", milestoneId), join(prGsd, "milestones", milestoneId), { force: true });
+    // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
+    // Without this, a crash during a unit leaves the runtime record only in the
+    // worktree. If the next session resolves basePath before worktree re-entry,
+    // selfHeal can't find or clear the stale record (#769).
+    safeCopyRecursive(join(wtGsd, "runtime", "units"), join(prGsd, "runtime", "units"), { force: true });
+}
+// ─── Resource Staleness ───────────────────────────────────────────────────
+/**
+ * Read the resource version (semver) from the managed-resources manifest.
+ * Uses gsdVersion instead of syncedAt so that launching a second session
+ * doesn't falsely trigger staleness (#804).
+ */
+export function readResourceVersion() {
+    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+    const manifestPath = join(agentDir, "managed-resources.json");
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return typeof manifest?.gsdVersion === "string"
+            ? manifest.gsdVersion
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if managed resources have been updated since session start.
+ * Returns a warning message if stale, null otherwise.
+ */
+export function checkResourcesStale(versionOnStart) {
+    if (versionOnStart === null)
+        return null;
+    const current = readResourceVersion();
+    if (current === null)
+        return null;
+    if (current !== versionOnStart) {
+        return "GSD resources were updated since this session started. Restart gsd to load the new code.";
+    }
+    return null;
+}
+// ─── Stale Worktree Escape ────────────────────────────────────────────────
+/**
+ * Detect and escape a stale worktree cwd (#608).
+ *
+ * After milestone completion + merge, the worktree directory is removed but
+ * the process cwd may still point inside `.gsd/worktrees/<MID>/`.
+ * When a new session starts, `process.cwd()` is passed as `base` to startAuto
+ * and all subsequent writes land in the wrong directory. This function detects
+ * that scenario and chdir back to the project root.
+ *
+ * Returns the corrected base path.
+ */
+export function escapeStaleWorktree(base) {
+    const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
+    const idx = base.indexOf(marker);
+    if (idx === -1)
+        return base;
+    // base is inside .gsd/worktrees/<something> — extract the project root
+    const projectRoot = base.slice(0, idx);
+    try {
+        process.chdir(projectRoot);
+    }
+    catch {
+        // If chdir fails, return the original — caller will handle errors downstream
+        return base;
+    }
+    return projectRoot;
+}
+/**
+ * Clean stale runtime unit files for completed milestones.
+ *
+ * After restart, stale runtime/units/*.json from prior milestones can
+ * cause deriveState to resume the wrong milestone (#887). Removes files
+ * for milestones that have a SUMMARY (fully complete).
+ */
+export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
+    const runtimeUnitsDir = join(gsdRootPath, "runtime", "units");
+    if (!existsSync(runtimeUnitsDir))
+        return 0;
+    let cleaned = 0;
+    try {
+        for (const file of readdirSync(runtimeUnitsDir)) {
+            if (!file.endsWith(".json"))
+                continue;
+            const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
+            if (!midMatch)
+                continue;
+            if (hasMilestoneSummary(midMatch[1])) {
+                try {
+                    unlinkSync(join(runtimeUnitsDir, file));
+                    cleaned++;
+                }
+                catch {
+                    /* non-fatal */
+                }
+            }
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+    return cleaned;
+}