gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/src/resources/extensions/gsd/auto-supervisor.ts

@@ -1,17 +1,16 @@
 /**
- * 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.
@@ -22,25 +21,19 @@ export function registerSigtermHandler(
   currentBasePath: string,
   previousHandler: (() => void) | null,
 ): () => void {
-  if (previousHandler) {
-    process.off("SIGTERM", previousHandler);
-    process.off("SIGINT", previousHandler);
-  }
+  if (previousHandler) process.off("SIGTERM", 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: (() => void) | null): void {
   if (handler) {
     process.off("SIGTERM", handler);
-    process.off("SIGINT", handler);
   }
 }
 

package/src/resources/extensions/gsd/auto-timeout-recovery.ts

@@ -18,14 +18,14 @@ import {
   writeBlockerPlaceholder,
 } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
-import { parseUnitId } from "./unit-id.js";
+
+import { resolveAgentEnd } from "./auto-loop.js";
 
 export interface RecoveryContext {
   basePath: string;
   verbose: boolean;
   currentUnitStartedAt: number;
   unitRecoveryCount: Map<string, number>;
-  dispatchNextUnit: (ctx: ExtensionContext, pi: ExtensionAPI) => Promise<void>;
 }
 
 export async function recoverTimedOutUnit(
@@ -36,7 +36,7 @@ export async function recoverTimedOutUnit(
   reason: "idle" | "hard",
   rctx: RecoveryContext,
 ): Promise<"recovered" | "paused"> {
-  const { basePath, verbose, currentUnitStartedAt, unitRecoveryCount, dispatchNextUnit } = rctx;
+  const { basePath, verbose, currentUnitStartedAt, unitRecoveryCount } = rctx;
 
   const runtime = readUnitRuntimeRecord(basePath, unitType, unitId);
   const recoveryAttempts = runtime?.recoveryAttempts ?? 0;
@@ -75,7 +75,7 @@ export async function recoverTimedOutUnit(
         "info",
       );
       unitRecoveryCount.delete(recoveryKey);
-      await dispatchNextUnit(ctx, pi);
+      resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" } as any);
       return "recovered";
     }
 
@@ -129,7 +129,7 @@ export async function recoverTimedOutUnit(
 
     // 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;
@@ -146,7 +146,7 @@ export async function recoverTimedOutUnit(
         "warning",
       );
       unitRecoveryCount.delete(recoveryKey);
-      await dispatchNextUnit(ctx, pi);
+      resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" } as any);
       return "recovered";
     }
 
@@ -180,7 +180,7 @@ export async function recoverTimedOutUnit(
       "info",
     );
     unitRecoveryCount.delete(recoveryKey);
-    await dispatchNextUnit(ctx, pi);
+    resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" } as any);
     return "recovered";
   }
 
@@ -249,7 +249,7 @@ export async function recoverTimedOutUnit(
       "warning",
     );
     unitRecoveryCount.delete(recoveryKey);
-    await dispatchNextUnit(ctx, pi);
+    resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" } as any);
     return "recovered";
   }
 

package/src/resources/extensions/gsd/auto-timers.ts

@@ -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().
  */
 
@@ -20,7 +20,6 @@ import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
 import { saveActivityLog } from "./activity-log.js";
 import { recoverTimedOutUnit, type RecoveryContext } from "./auto-timeout-recovery.js";
 import type { AutoSession } from "./auto/session.js";
-import { getErrorMessage } from "./error-utils.js";
 
 export interface SupervisionContext {
   s: AutoSession;
@@ -128,7 +127,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       );
       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");
@@ -160,7 +159,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       );
       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/src/resources/extensions/gsd/auto-verification.ts

@@ -21,11 +21,8 @@ import {
   runDependencyAudit,
 } from "./verification-gate.js";
 import { writeVerificationJSON } from "./verification-evidence.js";
-import { removePersistedKey } from "./auto-recovery.js";
-import type { AutoSession, PendingVerificationRetry } from "./auto/session.js";
+import type { AutoSession } from "./auto/session.js";
 import { join } from "node:path";
-import { getErrorMessage } from "./error-utils.js";
-import { parseUnitId } from "./unit-id.js";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -35,17 +32,21 @@ export interface VerificationContext {
 
 export type VerificationResult = "continue" | "retry" | "pause";
 
+function isInfraVerificationFailure(stderr: string): boolean {
+  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: VerificationContext,
-  dispatchNextUnit: (ctx: ExtensionContext, pi: ExtensionAPI) => Promise<void>,
-  startDispatchGapWatchdog: (ctx: ExtensionContext, pi: ExtensionAPI) => void,
   pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>,
 ): Promise<VerificationResult> {
   const { s, ctx, pi } = vctx;
@@ -59,15 +60,16 @@ export async function runPostUnitVerification(
     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: string | undefined;
-    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;
         }
       }
@@ -85,7 +87,7 @@ export async function runPostUnitVerification(
     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;
       }
     }
@@ -94,7 +96,9 @@ export async function runPostUnitVerification(
     const auditWarnings = runDependencyAudit(s.basePath);
     if (auditWarnings.length > 0) {
       result.auditWarnings = auditWarnings;
-      process.stderr.write(`verification-gate: ${auditWarnings.length} audit warning(s)\n`);
+      process.stderr.write(
+        `verification-gate: ${auditWarnings.length} audit warning(s)\n`,
+      );
       for (const w of auditWarnings) {
         process.stderr.write(`  [${w.severity}] ${w.name}: ${w.title}\n`);
       }
@@ -102,59 +106,49 @@ export async function runPostUnitVerification(
 
     // 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`);
+          if (f.stderr)
+            process.stderr.write(`  stderr: ${f.stderr.slice(0, 500)}\n`);
         }
       }
     }
 
     // Log blocking runtime errors
-    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`);
+    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`);
+        process.stderr.write(
+          `  [${err.source}] ${err.severity}: ${err.message.slice(0, 200)}\n`,
+        );
       }
     }
 
     // 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");
@@ -162,30 +156,44 @@ export async function runPostUnitVerification(
             writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id);
           } else {
             const nextAttempt = attempt + 1;
-            writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, nextAttempt, maxRetries);
+            writeVerificationJSON(
+              result,
+              tasksDir,
+              tid,
+              s.currentUnit.id,
+              nextAttempt,
+              maxRetries,
+            );
           }
         }
       } catch (evidenceErr) {
-        process.stderr.write(`verification-evidence: write error — ${(evidenceErr as Error).message}\n`);
+        process.stderr.write(
+          `verification-evidence: write error — ${(evidenceErr as Error).message}\n`,
+        );
       }
     }
 
-    // ── Auto-fix retry logic ──
-    if (result.passed) {
+    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;
-      return "continue";
-    } else 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.`,
+        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";
+    }
+
+    // ── Auto-fix retry logic ──
+    if (result.passed) {
       s.verificationRetryCount.delete(s.currentUnit.id);
       s.pendingVerificationRetry = null;
       return "continue";
@@ -197,17 +205,11 @@ export async function runPostUnitVerification(
         failureContext: formatFailureContext(result),
         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);
-      }
+      ctx.ui.notify(
+        `Verification failed — auto-fix attempt ${nextAttempt}/${maxRetries}`,
+        "warning",
+      );
+      // Return "retry" — the autoLoop while loop will re-iterate with the retry context
       return "retry";
     } else {
       // Gate failed, retries exhausted
@@ -223,7 +225,9 @@ export async function runPostUnitVerification(
     }
   } catch (err) {
     // Gate errors are non-fatal
-    process.stderr.write(`verification-gate: error — ${(err as Error).message}\n`);
+    process.stderr.write(
+      `verification-gate: error — ${(err as Error).message}\n`,
+    );
     return "continue";
   }
 }

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -0,0 +1,204 @@
+/**
+ * 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,
+  mkdirSync,
+  readFileSync,
+  cpSync,
+  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: string,
+  worktreePath: string,
+  milestoneId: string | null,
+): void {
+  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: string,
+  projectRoot: string,
+  milestoneId: string | null,
+): void {
+  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(): string | null {
+  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: string | null,
+): string | null {
+  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: string): string {
+  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: string,
+  hasMilestoneSummary: (mid: string) => boolean,
+): number {
+  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;
+}