gsd-pi 2.33.1 → 2.34.0-dev.6769913

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

@@ -0,0 +1,414 @@
+/**
+ * Auto-mode bootstrap — fresh-start initialization path.
+ *
+ * Git/state bootstrap, crash lock detection, debug init, worktree recovery,
+ * guided flow gate, session init, worktree lifecycle, DB lifecycle,
+ * preflight validation.
+ *
+ * Extracted from startAuto() in auto.ts. The resume path (s.paused)
+ * remains in auto.ts — this module handles only the fresh-start path.
+ */
+import { deriveState } from "./state.js";
+import { loadFile, getManifestStatus } from "./files.js";
+import { loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, getIsolationMode, } from "./preferences.js";
+import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
+import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
+import { synthesizeCrashRecovery } from "./session-forensics.js";
+import { writeLock, clearLock, readCrashLock, formatCrashInfo, isLockProcessAlive, } from "./crash-recovery.js";
+import { acquireSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
+import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
+import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, } from "./native-git-bridge.js";
+import { GitServiceImpl } from "./git-service.js";
+import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree.js";
+import { readResourceVersion } from "./auto-worktree-sync.js";
+import { initMetrics } from "./metrics.js";
+import { initRoutingHistory } from "./routing-history.js";
+import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
+import { resetProactiveHealing } from "./doctor-proactive.js";
+import { snapshotSkills } from "./skill-discovery.js";
+import { isDbAvailable } from "./gsd-db.js";
+import { hideFooter } from "./auto-dashboard.js";
+import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+import { sep as pathSep } from "node:path";
+/**
+ * Bootstrap a fresh auto-mode session. Handles everything from git init
+ * through secrets collection, returning when ready for the first
+ * dispatchNextUnit call.
+ *
+ * Returns false if the bootstrap aborted (e.g., guided flow returned,
+ * concurrent session detected). Returns true when ready to dispatch.
+ */
+export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, deps) {
+    const { shouldUseWorktreeIsolation, registerSigtermHandler, lockBase, buildResolver, } = deps;
+    const lockResult = acquireSessionLock(base);
+    if (!lockResult.acquired) {
+        ctx.ui.notify(lockResult.reason, "error");
+        return false;
+    }
+    function releaseLockAndReturn() {
+        releaseSessionLock(base);
+        clearLock(base);
+        return false;
+    }
+    try {
+        // Ensure git repo exists
+        if (!nativeIsRepo(base)) {
+            const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
+            nativeInit(base, mainBranch);
+        }
+        // Ensure .gitignore has baseline patterns
+        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+        const commitDocs = gitPrefs?.commit_docs;
+        const manageGitignore = gitPrefs?.manage_gitignore;
+        ensureGitignore(base, { commitDocs, manageGitignore });
+        if (manageGitignore !== false)
+            untrackRuntimeFiles(base);
+        // Bootstrap .gsd/ if it doesn't exist
+        const gsdDir = join(base, ".gsd");
+        if (!existsSync(gsdDir)) {
+            mkdirSync(join(gsdDir, "milestones"), { recursive: true });
+            if (commitDocs !== false) {
+                try {
+                    nativeAddAll(base);
+                    nativeCommit(base, "chore: init gsd");
+                }
+                catch {
+                    /* nothing to commit */
+                }
+            }
+        }
+        // Initialize GitServiceImpl
+        s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        // Check for crash from previous session. Skip our own fresh bootstrap lock.
+        const crashLock = readCrashLock(base);
+        if (crashLock && crashLock.pid !== process.pid) {
+            if (isLockProcessAlive(crashLock)) {
+                ctx.ui.notify(`Another auto-mode session (PID ${crashLock.pid}) appears to be running.\nStop it with \`kill ${crashLock.pid}\` before starting a new session.`, "error");
+                return releaseLockAndReturn();
+            }
+            const recoveredMid = crashLock.unitId.split("/")[0];
+            const milestoneAlreadyComplete = recoveredMid
+                ? !!resolveMilestoneFile(base, recoveredMid, "SUMMARY")
+                : false;
+            if (milestoneAlreadyComplete) {
+                ctx.ui.notify(`Crash recovery: discarding stale context for ${crashLock.unitId} — milestone ${recoveredMid} is already complete.`, "info");
+            }
+            else {
+                const activityDir = join(gsdRoot(base), "activity");
+                const recovery = synthesizeCrashRecovery(base, crashLock.unitType, crashLock.unitId, crashLock.sessionFile, activityDir);
+                if (recovery && recovery.trace.toolCallCount > 0) {
+                    s.pendingCrashRecovery = recovery.prompt;
+                    ctx.ui.notify(`${formatCrashInfo(crashLock)}\nRecovered ${recovery.trace.toolCallCount} tool calls from crashed session. Resuming with full context.`, "warning");
+                }
+                else {
+                    ctx.ui.notify(`${formatCrashInfo(crashLock)}\nNo session data recovered. Resuming from disk state.`, "warning");
+                }
+            }
+            clearLock(base);
+        }
+        // ── Debug mode ──
+        if (!isDebugEnabled() && process.env.GSD_DEBUG === "1") {
+            enableDebug(base);
+        }
+        if (isDebugEnabled()) {
+            const { isNativeParserAvailable } = await import("./native-parser-bridge.js");
+            debugLog("debug-start", {
+                platform: process.platform,
+                arch: process.arch,
+                node: process.version,
+                model: ctx.model?.id ?? "unknown",
+                provider: ctx.model?.provider ?? "unknown",
+                nativeParser: isNativeParserAvailable(),
+                cwd: base,
+            });
+            ctx.ui.notify(`Debug logging enabled → ${getDebugLogPath()}`, "info");
+        }
+        // Invalidate caches before initial state derivation
+        invalidateAllCaches();
+        // Clean stale runtime unit files for completed milestones (#887)
+        try {
+            const runtimeUnitsDir = join(gsdRoot(base), "runtime", "units");
+            if (existsSync(runtimeUnitsDir)) {
+                for (const file of readdirSync(runtimeUnitsDir)) {
+                    if (!file.endsWith(".json"))
+                        continue;
+                    const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
+                    if (!midMatch)
+                        continue;
+                    const mid = midMatch[1];
+                    if (resolveMilestoneFile(base, mid, "SUMMARY")) {
+                        try {
+                            unlinkSync(join(runtimeUnitsDir, file));
+                        }
+                        catch (e) {
+                            debugLog("stale-unit-cleanup-failed", {
+                                file,
+                                error: e instanceof Error ? e.message : String(e),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch (e) {
+            debugLog("stale-unit-dir-cleanup-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+        let state = await deriveState(base);
+        // Stale worktree state recovery (#654)
+        if (state.activeMilestone &&
+            shouldUseWorktreeIsolation() &&
+            !detectWorktreeName(base)) {
+            const wtPath = getAutoWorktreePath(base, state.activeMilestone.id);
+            if (wtPath) {
+                state = await deriveState(wtPath);
+            }
+        }
+        // Milestone branch recovery (#601)
+        let hasSurvivorBranch = false;
+        if (state.activeMilestone &&
+            (state.phase === "pre-planning" || state.phase === "needs-discussion") &&
+            shouldUseWorktreeIsolation() &&
+            !detectWorktreeName(base) &&
+            !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)) {
+            const milestoneBranch = `milestone/${state.activeMilestone.id}`;
+            const { nativeBranchExists } = await import("./native-git-bridge.js");
+            hasSurvivorBranch = nativeBranchExists(base, milestoneBranch);
+            if (hasSurvivorBranch) {
+                ctx.ui.notify(`Found prior session branch ${milestoneBranch}. Resuming.`, "info");
+            }
+        }
+        if (!hasSurvivorBranch) {
+            // No active work — start a new milestone via discuss flow
+            if (!state.activeMilestone || state.phase === "complete") {
+                const { showSmartEntry } = await import("./guided-flow.js");
+                await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+                invalidateAllCaches();
+                const postState = await deriveState(base);
+                if (postState.activeMilestone &&
+                    postState.phase !== "complete" &&
+                    postState.phase !== "pre-planning") {
+                    state = postState;
+                }
+                else if (postState.activeMilestone &&
+                    postState.phase === "pre-planning") {
+                    const contextFile = resolveMilestoneFile(base, postState.activeMilestone.id, "CONTEXT");
+                    const hasContext = !!(contextFile && (await loadFile(contextFile)));
+                    if (hasContext) {
+                        state = postState;
+                    }
+                    else {
+                        ctx.ui.notify("Discussion completed but no milestone context was written. Run /gsd to try the discussion again, or /gsd auto after creating the milestone manually.", "warning");
+                        return releaseLockAndReturn();
+                    }
+                }
+                else {
+                    return releaseLockAndReturn();
+                }
+            }
+            // Active milestone exists but has no roadmap
+            if (state.phase === "pre-planning") {
+                const mid = state.activeMilestone.id;
+                const contextFile = resolveMilestoneFile(base, mid, "CONTEXT");
+                const hasContext = !!(contextFile && (await loadFile(contextFile)));
+                if (!hasContext) {
+                    const { showSmartEntry } = await import("./guided-flow.js");
+                    await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+                    invalidateAllCaches();
+                    const postState = await deriveState(base);
+                    if (postState.activeMilestone && postState.phase !== "pre-planning") {
+                        state = postState;
+                    }
+                    else {
+                        ctx.ui.notify("Discussion completed but milestone context is still missing. Run /gsd to try again.", "warning");
+                        return releaseLockAndReturn();
+                    }
+                }
+            }
+        }
+        // Unreachable safety check
+        if (!state.activeMilestone) {
+            const { showSmartEntry } = await import("./guided-flow.js");
+            await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
+            return releaseLockAndReturn();
+        }
+        // ── Initialize session state ──
+        s.active = true;
+        s.stepMode = requestedStepMode;
+        s.verbose = verboseMode;
+        s.cmdCtx = ctx;
+        s.basePath = base;
+        s.unitDispatchCount.clear();
+        s.unitRecoveryCount.clear();
+        s.lastBudgetAlertLevel = 0;
+        s.unitLifetimeDispatches.clear();
+        resetHookState();
+        restoreHookState(base);
+        resetProactiveHealing();
+        s.autoStartTime = Date.now();
+        s.resourceVersionOnStart = readResourceVersion();
+        s.completedUnits = [];
+        s.pendingQuickTasks = [];
+        s.currentUnit = null;
+        s.currentMilestoneId = state.activeMilestone?.id ?? null;
+        s.originalModelId = ctx.model?.id ?? null;
+        s.originalModelProvider = ctx.model?.provider ?? null;
+        // Register SIGTERM handler
+        registerSigtermHandler(base);
+        // Capture integration branch
+        if (s.currentMilestoneId) {
+            if (getIsolationMode() !== "none") {
+                captureIntegrationBranch(base, s.currentMilestoneId, { commitDocs });
+            }
+            setActiveMilestoneId(base, s.currentMilestoneId);
+        }
+        // ── Auto-worktree setup ──
+        s.originalBasePath = base;
+        const isUnderGsdWorktrees = (p) => {
+            const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
+            if (p.includes(marker))
+                return true;
+            const worktreesSuffix = `${pathSep}.gsd${pathSep}worktrees`;
+            return p.endsWith(worktreesSuffix);
+        };
+        if (s.currentMilestoneId &&
+            shouldUseWorktreeIsolation() &&
+            !detectWorktreeName(base) &&
+            !isUnderGsdWorktrees(base)) {
+            buildResolver().enterMilestone(s.currentMilestoneId, {
+                notify: ctx.ui.notify.bind(ctx.ui),
+            });
+            if (s.basePath !== base) {
+                // Successfully entered worktree — re-register SIGTERM handler at original base
+                registerSigtermHandler(s.originalBasePath);
+            }
+        }
+        // ── DB lifecycle ──
+        const gsdDbPath = join(s.basePath, ".gsd", "gsd.db");
+        const gsdDirPath = join(s.basePath, ".gsd");
+        if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
+            const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));
+            const hasRequirements = existsSync(join(gsdDirPath, "REQUIREMENTS.md"));
+            const hasMilestones = existsSync(join(gsdDirPath, "milestones"));
+            if (hasDecisions || hasRequirements || hasMilestones) {
+                try {
+                    const { openDatabase: openDb } = await import("./gsd-db.js");
+                    const { migrateFromMarkdown } = await import("./md-importer.js");
+                    openDb(gsdDbPath);
+                    migrateFromMarkdown(s.basePath);
+                }
+                catch (err) {
+                    process.stderr.write(`gsd-migrate: auto-migration failed: ${err.message}\n`);
+                }
+            }
+        }
+        if (existsSync(gsdDbPath) && !isDbAvailable()) {
+            try {
+                const { openDatabase: openDb } = await import("./gsd-db.js");
+                openDb(gsdDbPath);
+            }
+            catch (err) {
+                process.stderr.write(`gsd-db: failed to open existing database: ${err.message}\n`);
+            }
+        }
+        // Initialize metrics
+        initMetrics(s.basePath);
+        // Initialize routing history
+        initRoutingHistory(s.basePath);
+        // Capture session's model at auto-mode start (#650)
+        const currentModel = ctx.model;
+        if (currentModel) {
+            s.autoModeStartModel = {
+                provider: currentModel.provider,
+                id: currentModel.id,
+            };
+        }
+        // Snapshot installed skills
+        if (resolveSkillDiscoveryMode() !== "off") {
+            snapshotSkills();
+        }
+        ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
+        ctx.ui.setFooter(hideFooter);
+        const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
+        const pendingCount = (state.registry ?? []).filter((m) => m.status !== "complete" && m.status !== "parked").length;
+        const scopeMsg = pendingCount > 1
+            ? `Will loop through ${pendingCount} milestones.`
+            : "Will loop until milestone complete.";
+        ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
+        updateSessionLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown", 0);
+        writeLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown", 0);
+        // Secrets collection gate
+        const mid = state.activeMilestone.id;
+        try {
+            const manifestStatus = await getManifestStatus(base, mid);
+            if (manifestStatus && manifestStatus.pending.length > 0) {
+                const result = await collectSecretsFromManifest(base, mid, ctx);
+                if (result &&
+                    result.applied &&
+                    result.skipped &&
+                    result.existingSkipped) {
+                    ctx.ui.notify(`Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`, "info");
+                }
+                else {
+                    ctx.ui.notify("Secrets collection skipped.", "info");
+                }
+            }
+        }
+        catch (err) {
+            ctx.ui.notify(`Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`, "warning");
+        }
+        // Self-heal: remove stale .git/index.lock
+        try {
+            const gitLockFile = join(base, ".git", "index.lock");
+            if (existsSync(gitLockFile)) {
+                const lockAge = Date.now() - statSync(gitLockFile).mtimeMs;
+                if (lockAge > 60_000) {
+                    unlinkSync(gitLockFile);
+                    ctx.ui.notify("Removed stale .git/index.lock from prior crash.", "info");
+                }
+            }
+        }
+        catch (e) {
+            debugLog("git-lock-cleanup-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+        // Pre-flight: validate milestone queue
+        try {
+            const msDir = join(base, ".gsd", "milestones");
+            if (existsSync(msDir)) {
+                const milestoneIds = readdirSync(msDir, { withFileTypes: true })
+                    .filter((d) => d.isDirectory() && /^M\d{3}/.test(d.name))
+                    .map((d) => d.name.match(/^(M\d{3})/)?.[1] ?? d.name);
+                if (milestoneIds.length > 1) {
+                    const issues = [];
+                    for (const id of milestoneIds) {
+                        const draft = resolveMilestoneFile(base, id, "CONTEXT-DRAFT");
+                        if (draft)
+                            issues.push(`${id}: has CONTEXT-DRAFT.md (will pause for discussion)`);
+                    }
+                    if (issues.length > 0) {
+                        ctx.ui.notify(`Pre-flight: ${milestoneIds.length} milestones queued.\n${issues.map((i) => `  ⚠ ${i}`).join("\n")}`, "warning");
+                    }
+                    else {
+                        ctx.ui.notify(`Pre-flight: ${milestoneIds.length} milestones queued. All have full context.`, "info");
+                    }
+                }
+            }
+        }
+        catch {
+            /* non-fatal */
+        }
+        return true;
+    }
+    catch (err) {
+        releaseSessionLock(base);
+        clearLock(base);
+        throw err;
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * 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 { nativeHasChanges } from "./native-git-bridge.js";
+// ─── SIGTERM Handling ─────────────────────────────────────────────────────────
+/**
+ * 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.
+ *
+ * Returns the new handler so the caller can store and deregister it later.
+ */
+export function registerSigtermHandler(currentBasePath, previousHandler) {
+    if (previousHandler)
+        process.off("SIGTERM", previousHandler);
+    const handler = () => {
+        clearLock(currentBasePath);
+        process.exit(0);
+    };
+    process.on("SIGTERM", handler);
+    return handler;
+}
+/** Deregister the SIGTERM handler (called on stop/pause). */
+export function deregisterSigtermHandler(handler) {
+    if (handler) {
+        process.off("SIGTERM", handler);
+    }
+}
+// ─── Working Tree Activity Detection ──────────────────────────────────────────
+/**
+ * Detect whether the agent is producing work on disk by checking git for
+ * any working-tree changes (staged, unstaged, or untracked). Returns true
+ * if there are uncommitted changes — meaning the agent is actively working,
+ * even though it hasn't signaled progress through runtime records.
+ */
+export function detectWorkingTreeActivity(cwd) {
+    try {
+        return nativeHasChanges(cwd);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Timeout recovery logic for auto-mode units.
+ * Handles idle and hard timeout recovery with escalation, steering messages,
+ * and blocker placeholder generation.
+ */
+import { readUnitRuntimeRecord, writeUnitRuntimeRecord, formatExecuteTaskRecoveryStatus, inspectExecuteTaskDurability, } from "./unit-runtime.js";
+import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, skipExecuteTask, writeBlockerPlaceholder, } from "./auto-recovery.js";
+import { existsSync } from "node:fs";
+import { resolveAgentEnd } from "./auto-loop.js";
+export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rctx) {
+    const { basePath, verbose, currentUnitStartedAt, unitRecoveryCount } = rctx;
+    const runtime = readUnitRuntimeRecord(basePath, unitType, unitId);
+    const recoveryAttempts = runtime?.recoveryAttempts ?? 0;
+    const maxRecoveryAttempts = reason === "idle" ? 2 : 1;
+    const recoveryKey = `${unitType}/${unitId}`;
+    const attemptNumber = (unitRecoveryCount.get(recoveryKey) ?? 0) + 1;
+    unitRecoveryCount.set(recoveryKey, attemptNumber);
+    if (attemptNumber > 1) {
+        // Exponential backoff: 2^(n-1) seconds, capped at 30s
+        const backoffMs = Math.min(1000 * Math.pow(2, attemptNumber - 2), 30000);
+        ctx.ui.notify(`Recovery attempt ${attemptNumber} for ${unitType} ${unitId}. Waiting ${backoffMs / 1000}s before retry.`, "info");
+        await new Promise(r => setTimeout(r, backoffMs));
+    }
+    if (unitType === "execute-task") {
+        const status = await inspectExecuteTaskDurability(basePath, unitId);
+        if (!status)
+            return "paused";
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            recovery: status,
+        });
+        const durableComplete = status.summaryExists && status.taskChecked && status.nextActionAdvanced;
+        if (durableComplete) {
+            writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+                phase: "finalized",
+                recovery: status,
+            });
+            ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} already completed on disk. Continuing auto-mode. (attempt ${attemptNumber})`, "info");
+            unitRecoveryCount.delete(recoveryKey);
+            resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+            return "recovered";
+        }
+        if (recoveryAttempts < maxRecoveryAttempts) {
+            const isEscalation = recoveryAttempts > 0;
+            writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+                phase: "recovered",
+                recovery: status,
+                recoveryAttempts: recoveryAttempts + 1,
+                lastRecoveryReason: reason,
+                lastProgressAt: Date.now(),
+                progressCount: (runtime?.progressCount ?? 0) + 1,
+                lastProgressKind: reason === "idle" ? "idle-recovery-retry" : "hard-recovery-retry",
+            });
+            const steeringLines = isEscalation
+                ? [
+                    `**FINAL ${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — last chance before this task is skipped.**`,
+                    `You are still executing ${unitType} ${unitId}.`,
+                    `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts}.`,
+                    `Current durability status: ${formatExecuteTaskRecoveryStatus(status)}.`,
+                    "You MUST finish the durable output NOW, even if incomplete.",
+                    "Write the task summary with whatever you have accomplished so far.",
+                    "Mark the task [x] in the plan. Commit your work.",
+                    "A partial summary is infinitely better than no summary.",
+                ]
+                : [
+                    `**${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — do not stop.**`,
+                    `You are still executing ${unitType} ${unitId}.`,
+                    `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts}.`,
+                    `Current durability status: ${formatExecuteTaskRecoveryStatus(status)}.`,
+                    "Do not keep exploring.",
+                    "Immediately finish the required durable output for this unit.",
+                    "If full completion is impossible, write the partial artifact/state needed for recovery and make the blocker explicit.",
+                ];
+            pi.sendMessage({
+                customType: "gsd-auto-timeout-recovery",
+                display: verbose,
+                content: steeringLines.join("\n"),
+            }, { triggerTurn: true, deliverAs: "steer" });
+            ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: steering ${unitType} ${unitId} to finish durable output (attempt ${attemptNumber}, session ${recoveryAttempts + 1}/${maxRecoveryAttempts}).`, "warning");
+            return "recovered";
+        }
+        // Retries exhausted — write missing durable artifacts and advance.
+        const diagnostic = formatExecuteTaskRecoveryStatus(status);
+        const [mid, sid, tid] = unitId.split("/");
+        const skipped = mid && sid && tid
+            ? skipExecuteTask(basePath, mid, sid, tid, status, reason, maxRecoveryAttempts)
+            : false;
+        if (skipped) {
+            writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+                phase: "skipped",
+                recovery: status,
+                recoveryAttempts: recoveryAttempts + 1,
+                lastRecoveryReason: reason,
+            });
+            ctx.ui.notify(`${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts (${diagnostic}). Blocker artifacts written. Advancing pipeline. (attempt ${attemptNumber})`, "warning");
+            unitRecoveryCount.delete(recoveryKey);
+            resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+            return "recovered";
+        }
+        // Fallback: couldn't write skip artifacts — pause as before.
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            phase: "paused",
+            recovery: status,
+            recoveryAttempts: recoveryAttempts + 1,
+            lastRecoveryReason: reason,
+        });
+        ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery check for ${unitType} ${unitId}: ${diagnostic}`, "warning");
+        return "paused";
+    }
+    const expected = diagnoseExpectedArtifact(unitType, unitId, basePath) ?? "required durable artifact";
+    // Check if the artifact already exists on disk — agent may have written it
+    // without signaling completion.
+    const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
+    if (artifactPath && existsSync(artifactPath)) {
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            phase: "finalized",
+            recoveryAttempts: recoveryAttempts + 1,
+            lastRecoveryReason: reason,
+        });
+        ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} artifact already exists on disk. Advancing. (attempt ${attemptNumber})`, "info");
+        unitRecoveryCount.delete(recoveryKey);
+        resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+        return "recovered";
+    }
+    if (recoveryAttempts < maxRecoveryAttempts) {
+        const isEscalation = recoveryAttempts > 0;
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            phase: "recovered",
+            recoveryAttempts: recoveryAttempts + 1,
+            lastRecoveryReason: reason,
+            lastProgressAt: Date.now(),
+            progressCount: (runtime?.progressCount ?? 0) + 1,
+            lastProgressKind: reason === "idle" ? "idle-recovery-retry" : "hard-recovery-retry",
+        });
+        const steeringLines = isEscalation
+            ? [
+                `**FINAL ${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — last chance before skip.**`,
+                `You are still executing ${unitType} ${unitId}.`,
+                `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts} — next failure skips this unit.`,
+                `Expected durable output: ${expected}.`,
+                "You MUST write the artifact file NOW, even if incomplete.",
+                "Write whatever you have — partial research, preliminary findings, best-effort analysis.",
+                "A partial artifact is infinitely better than no artifact.",
+                "If you are truly blocked, write the file with a BLOCKER section explaining why.",
+            ]
+            : [
+                `**${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — stay in auto-mode.**`,
+                `You are still executing ${unitType} ${unitId}.`,
+                `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts}.`,
+                `Expected durable output: ${expected}.`,
+                "Stop broad exploration.",
+                "Write the required artifact now.",
+                "If blocked, write the partial artifact and explicitly record the blocker instead of going silent.",
+            ];
+        pi.sendMessage({
+            customType: "gsd-auto-timeout-recovery",
+            display: verbose,
+            content: steeringLines.join("\n"),
+        }, { triggerTurn: true, deliverAs: "steer" });
+        ctx.ui.notify(`${reason === "idle" ? "Idle" : "Timeout"} recovery: steering ${unitType} ${unitId} to produce ${expected} (attempt ${attemptNumber}, session ${recoveryAttempts + 1}/${maxRecoveryAttempts}).`, "warning");
+        return "recovered";
+    }
+    // Retries exhausted — write a blocker placeholder and advance the pipeline
+    // instead of silently stalling.
+    const placeholder = writeBlockerPlaceholder(unitType, unitId, basePath, `${reason} recovery exhausted ${maxRecoveryAttempts} attempts without producing the artifact.`);
+    if (placeholder) {
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            phase: "skipped",
+            recoveryAttempts: recoveryAttempts + 1,
+            lastRecoveryReason: reason,
+        });
+        ctx.ui.notify(`${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts. Blocker placeholder written to ${placeholder}. Advancing pipeline. (attempt ${attemptNumber})`, "warning");
+        unitRecoveryCount.delete(recoveryKey);
+        resolveAgentEnd({ messages: [], _synthetic: "timeout-recovery" });
+        return "recovered";
+    }
+    // Fallback: couldn't resolve artifact path — pause as before.
+    writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+        phase: "paused",
+        recoveryAttempts: recoveryAttempts + 1,
+        lastRecoveryReason: reason,
+    });
+    return "paused";
+}