gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

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

@@ -0,0 +1,180 @@
+/**
+ * Unit supervision timers — soft timeout warning, idle watchdog,
+ * hard timeout, and context-pressure monitor.
+ *
+ * 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";
+import { resolveAutoSupervisorConfig } from "./preferences.js";
+import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
+import { getInFlightToolCount, getOldestInFlightToolStart, } from "./auto-tool-tracking.js";
+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";
+/**
+ * Set up all four supervision timers for the current unit:
+ * 1. Soft timeout warning (wrapup)
+ * 2. Idle watchdog (progress polling, stuck tool detection)
+ * 3. Hard timeout (pause + recovery)
+ * 4. Context-pressure monitor (continue-here)
+ */
+export function startUnitSupervision(sctx) {
+    const { s, ctx, pi, unitType, unitId, prefs, buildSnapshotOpts, buildRecoveryContext, pauseAuto } = sctx;
+    const supervisor = resolveAutoSupervisorConfig();
+    const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000;
+    const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;
+    const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000;
+    // ── 1. Soft timeout warning ──
+    s.wrapupWarningHandle = setTimeout(() => {
+        s.wrapupWarningHandle = null;
+        if (!s.active || !s.currentUnit)
+            return;
+        writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+            phase: "wrapup-warning-sent",
+            wrapupWarningSent: true,
+        });
+        pi.sendMessage({
+            customType: "gsd-auto-wrapup",
+            display: s.verbose,
+            content: [
+                "**TIME BUDGET WARNING — keep going only if progress is real.**",
+                "This unit crossed the soft time budget.",
+                "If you are making progress, continue. If not, switch to wrap-up mode now:",
+                "1. rerun the minimal required verification",
+                "2. write or update the required durable artifacts",
+                "3. mark task or slice state on disk correctly",
+                "4. leave precise resume notes if anything remains unfinished",
+            ].join("\n"),
+        }, { triggerTurn: true });
+    }, softTimeoutMs);
+    // ── 2. Idle watchdog ──
+    s.idleWatchdogHandle = setInterval(async () => {
+        try {
+            if (!s.active || !s.currentUnit)
+                return;
+            const runtime = readUnitRuntimeRecord(s.basePath, unitType, unitId);
+            if (!runtime)
+                return;
+            if (Date.now() - runtime.lastProgressAt < idleTimeoutMs)
+                return;
+            // Agent has tool calls currently executing — not idle, just waiting.
+            // But only suppress recovery if the tool started recently.
+            if (getInFlightToolCount() > 0) {
+                const oldestStart = getOldestInFlightToolStart();
+                const toolAgeMs = Date.now() - oldestStart;
+                if (toolAgeMs < idleTimeoutMs) {
+                    writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+                        lastProgressAt: Date.now(),
+                        lastProgressKind: "tool-in-flight",
+                    });
+                    return;
+                }
+                ctx.ui.notify(`Stalled tool detected: a tool has been in-flight for ${Math.round(toolAgeMs / 60000)}min. Treating as hung — attempting idle recovery.`, "warning");
+            }
+            // Check if the agent is producing work on disk.
+            if (detectWorkingTreeActivity(s.basePath)) {
+                writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+                    lastProgressAt: Date.now(),
+                    lastProgressKind: "filesystem-activity",
+                });
+                return;
+            }
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts());
+            }
+            else {
+                saveActivityLog(ctx, s.basePath, unitType, unitId);
+            }
+            const recovery = await recoverTimedOutUnit(ctx, pi, unitType, unitId, "idle", buildRecoveryContext());
+            if (recovery === "recovered")
+                return;
+            writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+                phase: "paused",
+            });
+            ctx.ui.notify(`Unit ${unitType} ${unitId} made no meaningful progress for ${supervisor.idle_timeout_minutes}min. Pausing auto-mode.`, "warning");
+            await pauseAuto(ctx, pi);
+        }
+        catch (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");
+            }
+            catch { /* best effort */ }
+        }
+    }, 15000);
+    // ── 3. Hard timeout ──
+    s.unitTimeoutHandle = setTimeout(async () => {
+        try {
+            s.unitTimeoutHandle = null;
+            if (!s.active)
+                return;
+            if (s.currentUnit) {
+                writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+                    phase: "timeout",
+                    timeoutAt: Date.now(),
+                });
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts());
+            }
+            else {
+                saveActivityLog(ctx, s.basePath, unitType, unitId);
+            }
+            const recovery = await recoverTimedOutUnit(ctx, pi, unitType, unitId, "hard", buildRecoveryContext());
+            if (recovery === "recovered")
+                return;
+            ctx.ui.notify(`Unit ${unitType} ${unitId} exceeded ${supervisor.hard_timeout_minutes}min hard timeout. Pausing auto-mode.`, "warning");
+            await pauseAuto(ctx, pi);
+        }
+        catch (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");
+            }
+            catch { /* best effort */ }
+        }
+    }, hardTimeoutMs);
+    // ── 4. Context-pressure continue-here monitor ──
+    if (s.continueHereHandle) {
+        clearInterval(s.continueHereHandle);
+        s.continueHereHandle = null;
+    }
+    const executorContextWindow = resolveExecutorContextWindow(ctx.modelRegistry, prefs, ctx.model?.contextWindow);
+    const continueHereThreshold = computeBudgets(executorContextWindow).continueThresholdPercent;
+    s.continueHereHandle = setInterval(() => {
+        if (!s.active || !s.currentUnit || !s.cmdCtx)
+            return;
+        const runtime = readUnitRuntimeRecord(s.basePath, unitType, unitId);
+        if (runtime?.continueHereFired)
+            return;
+        const contextUsage = s.cmdCtx.getContextUsage();
+        if (!contextUsage || contextUsage.percent == null || contextUsage.percent < continueHereThreshold)
+            return;
+        writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+            continueHereFired: true,
+        });
+        if (s.verbose) {
+            ctx.ui.notify(`Context at ${contextUsage.percent}% (threshold: ${continueHereThreshold}%) — sending wrap-up signal.`, "info");
+        }
+        pi.sendMessage({
+            customType: "gsd-auto-wrapup",
+            display: s.verbose,
+            content: [
+                "**CONTEXT BUDGET WARNING — wrap up this unit now.**",
+                `Context window is at ${contextUsage.percent}% (threshold: ${continueHereThreshold}%).`,
+                "The next unit needs a fresh context to work effectively. Wrap up now:",
+                "1. Finish any in-progress file writes",
+                "2. Write or update the required durable artifacts (summary, checkboxes)",
+                "3. Mark task state on disk correctly",
+                "4. Leave precise resume notes if anything remains unfinished",
+                "Do NOT start new sub-tasks or investigations.",
+            ].join("\n"),
+        }, { triggerTurn: true });
+        if (s.continueHereHandle) {
+            clearInterval(s.continueHereHandle);
+            s.continueHereHandle = null;
+        }
+    }, 15_000);
+}

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -0,0 +1,50 @@
+/**
+ * In-flight tool call tracking for auto-mode idle detection.
+ * Tracks which tool calls are currently executing so the idle watchdog
+ * can distinguish "waiting for tool completion" from "truly idle".
+ */
+const inFlightTools = new Map();
+/**
+ * Mark a tool execution as in-flight.
+ * Records start time so the idle watchdog can detect tools hung longer than the idle timeout.
+ */
+export function markToolStart(toolCallId, isActive) {
+    if (!isActive)
+        return;
+    inFlightTools.set(toolCallId, Date.now());
+}
+/**
+ * Mark a tool execution as completed.
+ */
+export function markToolEnd(toolCallId) {
+    inFlightTools.delete(toolCallId);
+}
+/**
+ * Returns the age (ms) of the oldest currently in-flight tool, or 0 if none.
+ */
+export function getOldestInFlightToolAgeMs() {
+    if (inFlightTools.size === 0)
+        return 0;
+    const oldestStart = Math.min(...inFlightTools.values());
+    return Date.now() - oldestStart;
+}
+/**
+ * Returns the number of currently in-flight tools.
+ */
+export function getInFlightToolCount() {
+    return inFlightTools.size;
+}
+/**
+ * Returns the start timestamp of the oldest in-flight tool, or undefined if none.
+ */
+export function getOldestInFlightToolStart() {
+    if (inFlightTools.size === 0)
+        return undefined;
+    return Math.min(...inFlightTools.values());
+}
+/**
+ * Clear all in-flight tool tracking state.
+ */
+export function clearInFlightTools() {
+    inFlightTools.clear();
+}

package/dist/resources/extensions/gsd/auto-unit-closeout.js

@@ -0,0 +1,30 @@
+/**
+ * Unit closeout helper — consolidates the repeated pattern of
+ * snapshotting metrics + saving activity log + extracting memories
+ * that appears 6+ times in auto.ts.
+ */
+import { snapshotUnitMetrics } from "./metrics.js";
+import { saveActivityLog } from "./activity-log.js";
+/**
+ * Snapshot metrics, save activity log, and fire-and-forget memory extraction
+ * for a completed unit. Returns the activity log file path (if any).
+ */
+export async function closeoutUnit(ctx, basePath, unitType, unitId, startedAt, opts) {
+    const modelId = ctx.model?.id ?? "unknown";
+    snapshotUnitMetrics(ctx, unitType, unitId, startedAt, modelId, opts);
+    const activityFile = saveActivityLog(ctx, basePath, unitType, unitId);
+    if (activityFile) {
+        try {
+            const { buildMemoryLLMCall, extractMemoriesFromUnit } = await import('./memory-extractor.js');
+            const llmCallFn = buildMemoryLLMCall(ctx);
+            if (llmCallFn) {
+                extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn).catch((err) => {
+                    if (process.env.GSD_DEBUG)
+                        console.error(`[gsd] memory extraction failed for ${unitType}/${unitId}:`, err);
+                });
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    return activityFile ?? undefined;
+}

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

@@ -0,0 +1,171 @@
+/**
+ * Post-unit verification gate for auto-mode.
+ *
+ * Runs typecheck/lint/test checks, captures runtime errors, performs
+ * dependency audits, handles auto-fix retry logic, and writes
+ * verification evidence JSON.
+ *
+ * Extracted from handleAgentEnd() in auto.ts. Returns a sentinel
+ * value instead of calling return/pauseAuto directly — the caller
+ * checks the result and handles control flow.
+ */
+import { loadFile, parsePlan } from "./files.js";
+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 { join } from "node:path";
+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, s.pendingVerificationRetry set for loop re-iteration
+ * - "pause" — gate failed with retries exhausted, pauseAuto already called
+ */
+export async function runPostUnitVerification(vctx, pauseAuto) {
+    const { s, ctx, pi } = vctx;
+    if (!s.currentUnit || s.currentUnit.type !== "execute-task") {
+        return "continue";
+    }
+    try {
+        const effectivePrefs = loadEffectiveGSDPreferences();
+        const prefs = effectivePrefs?.preferences;
+        // Read task plan verify field
+        const parts = s.currentUnit.id.split("/");
+        let taskPlanVerify;
+        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);
+                    taskPlanVerify = taskEntry?.verify;
+                }
+            }
+        }
+        const result = runVerificationGate({
+            basePath: s.basePath,
+            unitId: s.currentUnit.id,
+            cwd: s.basePath,
+            preferenceCommands: prefs?.verification_commands,
+            taskPlanVerify,
+        });
+        // Capture runtime errors
+        const runtimeErrors = await captureRuntimeErrors();
+        if (runtimeErrors.length > 0) {
+            result.runtimeErrors = runtimeErrors;
+            if (runtimeErrors.some((e) => e.blocking)) {
+                result.passed = false;
+            }
+        }
+        // Dependency audit
+        const auditWarnings = runDependencyAudit(s.basePath);
+        if (auditWarnings.length > 0) {
+            result.auditWarnings = auditWarnings;
+            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`);
+            }
+        }
+        // Auto-fix retry preferences
+        const autoFixEnabled = prefs?.verification_auto_fix !== false;
+        const maxRetries = typeof prefs?.verification_max_retries === "number"
+            ? prefs.verification_max_retries
+            : 2;
+        if (result.checks.length > 0) {
+            const passCount = result.checks.filter((c) => c.exitCode === 0).length;
+            const total = result.checks.length;
+            if (result.passed) {
+                ctx.ui.notify(`Verification gate: ${passCount}/${total} checks passed`);
+            }
+            else {
+                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: ${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`);
+                }
+            }
+        }
+        // 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`);
+            for (const err of blockingErrors) {
+                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 (parts.length >= 3) {
+            try {
+                const [mid, sid, tid] = parts;
+                const sDir = resolveSlicePath(s.basePath, mid, sid);
+                if (sDir) {
+                    const tasksDir = join(sDir, "tasks");
+                    if (result.passed) {
+                        writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id);
+                    }
+                    else {
+                        const nextAttempt = attempt + 1;
+                        writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, nextAttempt, maxRetries);
+                    }
+                }
+            }
+            catch (evidenceErr) {
+                process.stderr.write(`verification-evidence: write error — ${evidenceErr.message}\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";
+        }
+        // ── Auto-fix retry logic ──
+        if (result.passed) {
+            s.verificationRetryCount.delete(s.currentUnit.id);
+            s.pendingVerificationRetry = null;
+            return "continue";
+        }
+        else if (autoFixEnabled && attempt + 1 <= maxRetries) {
+            const nextAttempt = attempt + 1;
+            s.verificationRetryCount.set(s.currentUnit.id, nextAttempt);
+            s.pendingVerificationRetry = {
+                unitId: s.currentUnit.id,
+                failureContext: formatFailureContext(result),
+                attempt: nextAttempt,
+            };
+            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
+            const exhaustedAttempt = attempt + 1;
+            s.verificationRetryCount.delete(s.currentUnit.id);
+            s.pendingVerificationRetry = null;
+            ctx.ui.notify(`Verification gate FAILED after ${exhaustedAttempt > maxRetries ? exhaustedAttempt - 1 : exhaustedAttempt} retries — pausing for human review`, "error");
+            await pauseAuto(ctx, pi);
+            return "pause";
+        }
+    }
+    catch (err) {
+        // Gate errors are non-fatal
+        process.stderr.write(`verification-gate: error — ${err.message}\n`);
+        return "continue";
+    }
+}

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