gsd-pi 2.33.1-dev.29a8268 → 2.33.1-dev.9bafd68

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

@@ -0,0 +1,1485 @@
+/**
+ * GSD Auto Mode — Fresh Session Per Unit
+ *
+ * State machine driven by .gsd/ files on disk. Each "unit" of work
+ * (plan slice, execute task, complete slice) gets a fresh session via
+ * the stashed ctx.newSession() pattern.
+ *
+ * The extension reads disk state after each agent_end, determines the
+ * next unit type, creates a fresh session, and injects a focused prompt
+ * telling the LLM which files to read and what to do.
+ */
+import { deriveState } from "./state.js";
+import { getManifestStatus } from "./files.js";
+import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
+import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
+import { clearActivityLogState } from "./activity-log.js";
+import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
+import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
+import { acquireSessionLock, validateSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
+import { clearUnitRuntimeRecord, readUnitRuntimeRecord, writeUnitRuntimeRecord, } from "./unit-runtime.js";
+import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { sendDesktopNotification } from "./notifications.js";
+import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, } from "./auto-budget.js";
+import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, } from "./auto-tool-tracking.js";
+import { collectObservabilityWarnings as _collectObservabilityWarnings, buildObservabilityRepairBlock, } from "./auto-observability.js";
+import { closeoutUnit } from "./auto-unit-closeout.js";
+import { selectAndApplyModel } from "./auto-model-selection.js";
+import { checkResourcesStale, escapeStaleWorktree, } from "./resource-version.js";
+import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
+import { resetHookState, runPreDispatchHooks, restoreHookState, clearPersistedHookState, } from "./post-unit-hooks.js";
+import { runGSDDoctor, rebuildState } from "./doctor.js";
+import { preDispatchHealthGate, resetProactiveHealing, } from "./doctor-proactive.js";
+import { clearSkillSnapshot } from "./skill-discovery.js";
+import { captureAvailableSkills, resetSkillTelemetry } from "./skill-telemetry.js";
+import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
+import { join } from "node:path";
+import { parseUnitId } from "./unit-id.js";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
+import { createGitService } from "./git-service.js";
+import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
+import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, } from "./auto-worktree.js";
+import { pruneQueueOrder } from "./queue-order.js";
+import { showNextAction } from "../shared/mod.js";
+import { debugLog, debugTime, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
+import { verifyExpectedArtifact, completedKeysPath, persistCompletedKey, selfHealRuntimeRecords, reconcileMergeState, } from "./auto-recovery.js";
+import { resolveDispatch } from "./auto-dispatch.js";
+import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, describeNextUnit as _describeNextUnit, unitVerb, hideFooter, } from "./auto-dashboard.js";
+import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
+import { isDbAvailable } from "./gsd-db.js";
+import { countPendingCaptures } from "./captures.js";
+// ── Extracted modules ──────────────────────────────────────────────────────
+import { startUnitSupervision } from "./auto-timers.js";
+import { checkIdempotency } from "./auto-idempotency.js";
+import { checkStuckAndRecover } from "./auto-stuck-detection.js";
+import { runPostUnitVerification } from "./auto-verification.js";
+import { postUnitPreVerification, postUnitPostVerification } from "./auto-post-unit.js";
+import { bootstrapAutoSession } from "./auto-start.js";
+// Resource staleness, stale worktree escape → resource-version.ts
+// ─── Session State ─────────────────────────────────────────────────────────
+import { AutoSession, DISPATCH_GAP_TIMEOUT_MS, MAX_SKIP_DEPTH, NEW_SESSION_TIMEOUT_MS, DISPATCH_HANG_TIMEOUT_MS, } from "./auto/session.js";
+import { getErrorMessage } from "./error-utils.js";
+// ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
+// ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
+// This file must NOT declare module-level `let` or `var` variables for state.
+// The single `s` instance below is the only mutable module-level binding.
+//
+// When adding features or fixing bugs:
+//   - New mutable state → add a property to AutoSession, not a module-level variable
+//   - New constants → module-level `const` is fine (immutable)
+//   - New state that needs reset on stopAuto → add to AutoSession.reset()
+//
+// Tests in auto-session-encapsulation.test.ts enforce this invariant.
+// ─────────────────────────────────────────────────────────────────────────────
+const s = new AutoSession();
+export function shouldUseWorktreeIsolation() {
+    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    if (prefs?.isolation === "none")
+        return false;
+    if (prefs?.isolation === "branch")
+        return false;
+    return true; // default: worktree
+}
+// All mutable state lives in AutoSession (auto/session.ts) — see encapsulation invariant above.
+/** Wrapper: register SIGTERM handler and store reference. */
+function registerSigtermHandler(currentBasePath) {
+    s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
+}
+/** Wrapper: deregister SIGTERM handler and clear reference. */
+function deregisterSigtermHandler() {
+    _deregisterSigtermHandler(s.sigtermHandler);
+    s.sigtermHandler = null;
+}
+export function getAutoDashboardData() {
+    const ledger = getLedger();
+    const totals = ledger ? getProjectTotals(ledger.units) : null;
+    // Pending capture count — lazy check, non-fatal
+    let pendingCaptureCount = 0;
+    try {
+        if (s.basePath) {
+            pendingCaptureCount = countPendingCaptures(s.basePath);
+        }
+    }
+    catch {
+        // Non-fatal — captures module may not be loaded
+    }
+    return { active: s.active, paused: s.paused,
+        stepMode: s.stepMode,
+        startTime: s.autoStartTime,
+        elapsed: (s.active || s.paused) ? Date.now() - s.autoStartTime : 0,
+        currentUnit: s.currentUnit ? { ...s.currentUnit } : null,
+        completedUnits: [...s.completedUnits], basePath: s.basePath,
+        totalCost: totals?.cost ?? 0,
+        totalTokens: totals?.tokens.total ?? 0,
+        pendingCaptureCount,
+    };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export function isAutoActive() {
+    return s.active;
+}
+export function isAutoPaused() {
+    return s.paused;
+}
+/**
+ * Return the model captured at auto-mode start for this session.
+ * Used by error-recovery to fall back to the session's own model
+ * instead of reading (potentially stale) preferences from disk (#1065).
+ */
+export function getAutoModeStartModel() {
+    return s.autoModeStartModel;
+}
+// Tool tracking — delegates to auto-tool-tracking.ts
+export function markToolStart(toolCallId) {
+    _markToolStart(toolCallId, s.active);
+}
+export function markToolEnd(toolCallId) {
+    _markToolEnd(toolCallId);
+}
+export function getOldestInFlightToolAgeMs() {
+    return _getOldestInFlightToolAgeMs();
+}
+/**
+ * Return the base path to use for the auto.lock file.
+ * Always uses the original project root (not the worktree) so that
+ * a second terminal can discover and stop a running auto-mode session.
+ */
+function lockBase() {
+    return s.originalBasePath || s.basePath;
+}
+/**
+ * Attempt to stop a running auto-mode session from a different process.
+ * Reads the lock file at the project root, checks if the PID is alive,
+ * and sends SIGTERM to gracefully stop it.
+ *
+ * Returns true if a remote session was found and signaled, false otherwise.
+ */
+export function stopAutoRemote(projectRoot) {
+    const lock = readCrashLock(projectRoot);
+    if (!lock)
+        return { found: false };
+    if (!isLockProcessAlive(lock)) {
+        // Stale lock — clean it up
+        clearLock(projectRoot);
+        return { found: false };
+    }
+    // Send SIGTERM — the auto-mode process has a handler that clears the lock and exits
+    try {
+        process.kill(lock.pid, "SIGTERM");
+        return { found: true, pid: lock.pid };
+    }
+    catch (err) {
+        return { found: false, error: err.message };
+    }
+}
+export function isStepMode() {
+    return s.stepMode;
+}
+function clearUnitTimeout() {
+    if (s.unitTimeoutHandle) {
+        clearTimeout(s.unitTimeoutHandle);
+        s.unitTimeoutHandle = null;
+    }
+    if (s.wrapupWarningHandle) {
+        clearTimeout(s.wrapupWarningHandle);
+        s.wrapupWarningHandle = null;
+    }
+    if (s.idleWatchdogHandle) {
+        clearInterval(s.idleWatchdogHandle);
+        s.idleWatchdogHandle = null;
+    }
+    if (s.continueHereHandle) {
+        clearInterval(s.continueHereHandle);
+        s.continueHereHandle = null;
+    }
+    clearInFlightTools();
+    clearDispatchGapWatchdog();
+}
+function clearDispatchGapWatchdog() {
+    if (s.dispatchGapHandle) {
+        clearTimeout(s.dispatchGapHandle);
+        s.dispatchGapHandle = null;
+    }
+}
+/** Build snapshot metric opts, enriching with continueHereFired from the runtime record. */
+function buildSnapshotOpts(unitType, unitId) {
+    const runtime = s.currentUnit ? readUnitRuntimeRecord(s.basePath, unitType, unitId) : null;
+    return {
+        promptCharCount: s.lastPromptCharCount,
+        baselineCharCount: s.lastBaselineCharCount,
+        ...(s.currentUnitRouting ?? {}),
+        ...(runtime?.continueHereFired ? { continueHereFired: true } : {}),
+    };
+}
+// ─── Extracted Merge Helper ───────────────────────────────────────────────
+/**
+ * Attempt to merge the current milestone branch to main.
+ * Handles both worktree and branch isolation modes with a single code path.
+ * Returns true if merge succeeded, false on error (non-fatal, logged).
+ *
+ * Extracted from 4 duplicate merge blocks in dispatchNextUnit to eliminate
+ * the bug factory where fixing one copy didn't fix the others (#1308).
+ */
+function tryMergeMilestone(ctx, milestoneId, mode) {
+    const isolationMode = getIsolationMode();
+    // Worktree merge path
+    if (isInAutoWorktree(s.basePath) && s.originalBasePath) {
+        try {
+            const roadmapPath = resolveMilestoneFile(s.originalBasePath, milestoneId, "ROADMAP");
+            if (!roadmapPath) {
+                teardownAutoWorktree(s.originalBasePath, milestoneId);
+                ctx.ui.notify(`Exited worktree for ${milestoneId} (no roadmap for merge).`, "info");
+                return false;
+            }
+            const roadmapContent = readFileSync(roadmapPath, "utf-8");
+            const mergeResult = mergeMilestoneToMain(s.originalBasePath, milestoneId, roadmapContent);
+            s.basePath = s.originalBasePath;
+            s.gitService = createGitService(s.basePath);
+            ctx.ui.notify(`Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
+            return true;
+        }
+        catch (err) {
+            ctx.ui.notify(`Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+            if (s.originalBasePath) {
+                s.basePath = s.originalBasePath;
+                try {
+                    process.chdir(s.basePath);
+                }
+                catch { /* best-effort */ }
+            }
+            return false;
+        }
+    }
+    // Branch-mode merge path
+    if (isolationMode === "branch") {
+        try {
+            const currentBranch = getCurrentBranch(s.basePath);
+            const milestoneBranch = autoWorktreeBranch(milestoneId);
+            if (currentBranch === milestoneBranch) {
+                const roadmapPath = resolveMilestoneFile(s.basePath, milestoneId, "ROADMAP");
+                if (roadmapPath) {
+                    const roadmapContent = readFileSync(roadmapPath, "utf-8");
+                    const mergeResult = mergeMilestoneToMain(s.basePath, milestoneId, roadmapContent);
+                    s.gitService = createGitService(s.basePath);
+                    ctx.ui.notify(`Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
+                    return true;
+                }
+            }
+        }
+        catch (err) {
+            ctx.ui.notify(`Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`, "warning");
+        }
+    }
+    return false;
+}
+/**
+ * Start a watchdog that fires if no new unit is dispatched within DISPATCH_GAP_TIMEOUT_MS
+ * after handleAgentEnd completes. This catches the case where the dispatch chain silently
+ * breaks (e.g., unhandled exception in dispatchNextUnit) and auto-mode is left s.active but idle.
+ *
+ * The watchdog is cleared on the next successful unit dispatch (clearUnitTimeout is called
+ * at the start of handleAgentEnd, which calls clearDispatchGapWatchdog).
+ */
+function startDispatchGapWatchdog(ctx, pi) {
+    clearDispatchGapWatchdog();
+    s.dispatchGapHandle = setTimeout(async () => {
+        s.dispatchGapHandle = null;
+        if (!s.active || !s.cmdCtx)
+            return;
+        if (s.verbose) {
+            ctx.ui.notify("Dispatch gap detected — re-evaluating state.", "info");
+        }
+        try {
+            await dispatchNextUnit(ctx, pi);
+        }
+        catch (retryErr) {
+            const message = getErrorMessage(retryErr);
+            await stopAuto(ctx, pi, `Dispatch gap recovery failed: ${message}`);
+            return;
+        }
+        if (s.active && !s.unitTimeoutHandle && !s.wrapupWarningHandle) {
+            await stopAuto(ctx, pi, "Stalled — no dispatchable unit after retry");
+        }
+    }, DISPATCH_GAP_TIMEOUT_MS);
+}
+export async function stopAuto(ctx, pi, reason) {
+    if (!s.active && !s.paused)
+        return;
+    const reasonSuffix = reason ? ` — ${reason}` : "";
+    clearUnitTimeout();
+    if (lockBase()) {
+        releaseSessionLock(lockBase());
+        clearLock(lockBase());
+    }
+    clearSkillSnapshot();
+    resetSkillTelemetry();
+    s.dispatching = false;
+    s.skipDepth = 0;
+    // Remove SIGTERM handler registered at auto-mode start
+    deregisterSigtermHandler();
+    // ── Auto-worktree: exit worktree and reset s.basePath on stop ──
+    if (s.currentMilestoneId && isInAutoWorktree(s.basePath)) {
+        try {
+            try {
+                autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId);
+            }
+            catch (e) {
+                debugLog("stop-auto-commit-failed", { error: getErrorMessage(e) });
+            }
+            teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId, { preserveBranch: true });
+            s.basePath = s.originalBasePath;
+            s.gitService = createGitService(s.basePath);
+            ctx?.ui.notify("Exited auto-worktree (branch preserved for resume).", "info");
+        }
+        catch (err) {
+            ctx?.ui.notify(`Auto-worktree teardown failed: ${getErrorMessage(err)}`, "warning");
+        }
+    }
+    // ── DB cleanup: close the SQLite connection ──
+    if (isDbAvailable()) {
+        try {
+            const { closeDatabase } = await import("./gsd-db.js");
+            closeDatabase();
+        }
+        catch (e) {
+            debugLog("db-close-failed", { error: getErrorMessage(e) });
+        }
+    }
+    if (s.originalBasePath) {
+        s.basePath = s.originalBasePath;
+        try {
+            process.chdir(s.basePath);
+        }
+        catch { /* best-effort */ }
+    }
+    const ledger = getLedger();
+    if (ledger && ledger.units.length > 0) {
+        const totals = getProjectTotals(ledger.units);
+        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}. Session: ${formatCost(totals.cost)} · ${formatTokenCount(totals.tokens.total)} tokens · ${ledger.units.length} units`, "info");
+    }
+    else {
+        ctx?.ui.notify(`Auto-mode stopped${reasonSuffix}.`, "info");
+    }
+    if (s.basePath) {
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("stop-rebuild-state-failed", { error: getErrorMessage(e) });
+        }
+    }
+    if (isDebugEnabled()) {
+        const logPath = writeDebugSummary();
+        if (logPath) {
+            ctx?.ui.notify(`Debug log written → ${logPath}`, "info");
+        }
+    }
+    resetMetrics();
+    resetRoutingHistory();
+    resetHookState();
+    if (s.basePath)
+        clearPersistedHookState(s.basePath);
+    s.active = false;
+    s.paused = false;
+    s.stepMode = false;
+    s.unitDispatchCount.clear();
+    s.unitRecoveryCount.clear();
+    s.unitConsecutiveSkips.clear();
+    clearInFlightTools();
+    s.lastBudgetAlertLevel = 0;
+    s.lastStateRebuildAt = 0;
+    s.unitLifetimeDispatches.clear();
+    s.currentUnit = null;
+    s.autoModeStartModel = null;
+    s.currentMilestoneId = null;
+    s.originalBasePath = "";
+    s.completedUnits = [];
+    s.pendingQuickTasks = [];
+    clearSliceProgressCache();
+    clearActivityLogState();
+    resetProactiveHealing();
+    s.recentlyEvictedKeys.clear();
+    s.pendingCrashRecovery = null;
+    s.pendingVerificationRetry = null;
+    s.verificationRetryCount.clear();
+    s.pausedSessionFile = null;
+    s.handlingAgentEnd = false;
+    ctx?.ui.setStatus("gsd-auto", undefined);
+    ctx?.ui.setWidget("gsd-progress", undefined);
+    ctx?.ui.setFooter(undefined);
+    if (pi && ctx && s.originalModelId && s.originalModelProvider) {
+        const original = ctx.modelRegistry.find(s.originalModelProvider, s.originalModelId);
+        if (original)
+            await pi.setModel(original);
+        s.originalModelId = null;
+        s.originalModelProvider = null;
+    }
+    s.cmdCtx = null;
+}
+/**
+ * Pause auto-mode without destroying state. Context is preserved.
+ * The user can interact with the agent, then `/gsd auto` resumes
+ * from disk state. Called when the user presses Escape during auto-mode.
+ */
+export async function pauseAuto(ctx, _pi) {
+    if (!s.active)
+        return;
+    clearUnitTimeout();
+    s.pausedSessionFile = ctx?.sessionManager?.getSessionFile() ?? null;
+    if (lockBase()) {
+        releaseSessionLock(lockBase());
+        clearLock(lockBase());
+    }
+    deregisterSigtermHandler();
+    s.active = false;
+    s.paused = true;
+    s.pendingVerificationRetry = null;
+    s.verificationRetryCount.clear();
+    ctx?.ui.setStatus("gsd-auto", "paused");
+    ctx?.ui.setWidget("gsd-progress", undefined);
+    ctx?.ui.setFooter(undefined);
+    const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
+    ctx?.ui.notify(`${s.stepMode ? "Step" : "Auto"}-mode paused (Escape). Type to interact, or ${resumeCmd} to resume.`, "info");
+}
+export async function startAuto(ctx, pi, base, verboseMode, options) {
+    const requestedStepMode = options?.step ?? false;
+    // Escape stale worktree cwd from a previous milestone (#608).
+    base = escapeStaleWorktree(base);
+    // If resuming from paused state, just re-activate and dispatch next unit.
+    if (s.paused) {
+        // Re-acquire session lock before resuming
+        const resumeLock = acquireSessionLock(base);
+        if (!resumeLock.acquired) {
+            ctx.ui.notify(`Cannot resume: ${resumeLock.reason}`, "error");
+            return;
+        }
+        s.paused = false;
+        s.active = true;
+        s.verbose = verboseMode;
+        s.stepMode = requestedStepMode;
+        s.cmdCtx = ctx;
+        s.basePath = base;
+        s.unitDispatchCount.clear();
+        s.unitLifetimeDispatches.clear();
+        s.unitConsecutiveSkips.clear();
+        if (!getLedger())
+            initMetrics(base);
+        if (s.currentMilestoneId)
+            setActiveMilestoneId(base, s.currentMilestoneId);
+        // ── Auto-worktree: re-enter worktree on resume ──
+        if (s.currentMilestoneId && shouldUseWorktreeIsolation() && s.originalBasePath && !isInAutoWorktree(s.basePath) && !detectWorktreeName(s.basePath) && !detectWorktreeName(s.originalBasePath)) {
+            try {
+                const existingWtPath = getAutoWorktreePath(s.originalBasePath, s.currentMilestoneId);
+                if (existingWtPath) {
+                    const wtPath = enterAutoWorktree(s.originalBasePath, s.currentMilestoneId);
+                    s.basePath = wtPath;
+                    s.gitService = createGitService(s.basePath);
+                    ctx.ui.notify(`Re-entered auto-worktree at ${wtPath}`, "info");
+                }
+                else {
+                    const wtPath = createAutoWorktree(s.originalBasePath, s.currentMilestoneId);
+                    s.basePath = wtPath;
+                    s.gitService = createGitService(s.basePath);
+                    ctx.ui.notify(`Recreated auto-worktree at ${wtPath}`, "info");
+                }
+            }
+            catch (err) {
+                ctx.ui.notify(`Auto-worktree re-entry failed: ${getErrorMessage(err)}. Continuing at current path.`, "warning");
+            }
+        }
+        registerSigtermHandler(lockBase());
+        ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
+        ctx.ui.setFooter(hideFooter);
+        ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
+        restoreHookState(s.basePath);
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("resume-rebuild-state-failed", { error: getErrorMessage(e) });
+        }
+        try {
+            const report = await runGSDDoctor(s.basePath, { fix: true });
+            if (report.fixesApplied.length > 0) {
+                ctx.ui.notify(`Resume: applied ${report.fixesApplied.length} fix(es) to state.`, "info");
+            }
+        }
+        catch (e) {
+            debugLog("resume-doctor-failed", { error: getErrorMessage(e) });
+        }
+        await selfHealRuntimeRecords(s.basePath, ctx, s.completedKeySet);
+        invalidateAllCaches();
+        if (s.pausedSessionFile) {
+            const activityDir = join(gsdRoot(s.basePath), "activity");
+            const recovery = synthesizeCrashRecovery(s.basePath, s.currentUnit?.type ?? "unknown", s.currentUnit?.id ?? "unknown", s.pausedSessionFile ?? undefined, activityDir);
+            if (recovery && recovery.trace.toolCallCount > 0) {
+                s.pendingCrashRecovery = recovery.prompt;
+                ctx.ui.notify(`Recovered ${recovery.trace.toolCallCount} tool calls from paused session. Resuming with context.`, "info");
+            }
+            s.pausedSessionFile = null;
+        }
+        // If resuming from a secrets pause, re-collect before dispatching (#1146)
+        if (s.pausedForSecrets && s.currentMilestoneId) {
+            try {
+                const manifestStatus = await getManifestStatus(s.basePath, s.currentMilestoneId);
+                if (manifestStatus && manifestStatus.pending.length > 0) {
+                    const result = await collectSecretsFromManifest(s.basePath, s.currentMilestoneId, ctx);
+                    if (result && result.applied.length > 0) {
+                        ctx.ui.notify(`Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`, "info");
+                    }
+                    else if (result && result.applied.length === 0 && result.skipped.length > 0) {
+                        // All keys were skipped — still pending, re-pause
+                        s.paused = true;
+                        s.active = false;
+                        ctx.ui.notify(`All env variables were skipped. Auto-mode remains paused.\nCollect them with /gsd secrets, then resume with /gsd auto.`, "warning");
+                        ctx.ui.setStatus("gsd-auto", "paused");
+                        return;
+                    }
+                }
+            }
+            catch (err) {
+                ctx.ui.notify(`Secrets check error: ${getErrorMessage(err)}. Continuing without secrets.`, "warning");
+            }
+            s.pausedForSecrets = false;
+        }
+        updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
+        writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
+        await dispatchNextUnit(ctx, pi);
+        return;
+    }
+    // ── Fresh start path — delegated to auto-start.ts ──
+    const bootstrapDeps = {
+        shouldUseWorktreeIsolation,
+        registerSigtermHandler,
+        lockBase,
+    };
+    const ready = await bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, bootstrapDeps);
+    if (!ready)
+        return;
+    // Dispatch the first unit
+    await dispatchNextUnit(ctx, pi);
+}
+// ─── Agent End Handler ────────────────────────────────────────────────────────
+/** Guard against concurrent handleAgentEnd execution. */
+export async function handleAgentEnd(ctx, pi) {
+    if (!s.active || !s.cmdCtx)
+        return;
+    if (s.handlingAgentEnd) {
+        // Another agent_end arrived while we're still processing the previous one.
+        // This happens when a unit dispatched inside handleAgentEnd (e.g. via hooks,
+        // triage, or quick-task early-dispatch paths) completes before the outer
+        // handleAgentEnd returns. Queue a retry so the completed unit's agent_end
+        // is not silently dropped (#1072).
+        s.pendingAgentEndRetry = true;
+        return;
+    }
+    s.handlingAgentEnd = true;
+    try {
+        // Unit completed — clear its timeout
+        clearUnitTimeout();
+        // ── Pre-verification processing (commit, doctor, state rebuild, etc.) ──
+        const postUnitCtx = {
+            s,
+            ctx,
+            pi,
+            buildSnapshotOpts,
+            lockBase,
+            stopAuto,
+            pauseAuto,
+            updateProgressWidget,
+        };
+        const preResult = await postUnitPreVerification(postUnitCtx);
+        if (preResult === "dispatched")
+            return;
+        // ── Verification gate: run typecheck/lint/test after execute-task ──
+        const verificationResult = await runPostUnitVerification({ s, ctx, pi }, dispatchNextUnit, startDispatchGapWatchdog, pauseAuto);
+        if (verificationResult === "retry" || verificationResult === "pause")
+            return;
+        // ── Post-verification processing (DB dual-write, hooks, triage, quick-tasks) ──
+        const postResult = await postUnitPostVerification(postUnitCtx);
+        if (postResult === "dispatched" || postResult === "stopped")
+            return;
+        if (postResult === "step-wizard") {
+            await showStepWizard(ctx, pi);
+            return;
+        }
+        // ── Dispatch with hang detection (#1073) ────────────────────────────────
+        // Start a safety watchdog BEFORE calling dispatchNextUnit. If dispatch
+        // hangs at any await (newSession, model selection, etc.), the gap watchdog
+        // inside handleAgentEnd never fires because we never reach the check.
+        // This pre-dispatch watchdog ensures recovery even when dispatchNextUnit
+        // itself is permanently blocked.
+        const dispatchHangGuard = setTimeout(() => {
+            if (!s.active)
+                return;
+            // dispatchNextUnit has been running for too long — it's likely hung.
+            // Start the gap watchdog which will retry dispatch from scratch.
+            if (!s.unitTimeoutHandle && !s.wrapupWarningHandle) {
+                ctx.ui.notify(`Dispatch hang detected (${DISPATCH_HANG_TIMEOUT_MS / 1000}s without completion). Starting recovery watchdog.`, "warning");
+                startDispatchGapWatchdog(ctx, pi);
+            }
+        }, DISPATCH_HANG_TIMEOUT_MS);
+        try {
+            await dispatchNextUnit(ctx, pi);
+        }
+        catch (dispatchErr) {
+            const message = getErrorMessage(dispatchErr);
+            ctx.ui.notify(`Dispatch error after unit completion: ${message}. Retrying in ${DISPATCH_GAP_TIMEOUT_MS / 1000}s.`, "error");
+            startDispatchGapWatchdog(ctx, pi);
+            return;
+        }
+        finally {
+            clearTimeout(dispatchHangGuard);
+        }
+        if (s.active && !s.unitTimeoutHandle && !s.wrapupWarningHandle) {
+            startDispatchGapWatchdog(ctx, pi);
+        }
+    }
+    finally {
+        s.handlingAgentEnd = false;
+        // If an agent_end event was dropped by the reentrancy guard while we were
+        // processing, re-enter handleAgentEnd on the next microtask. This prevents
+        // the summarizing phase stall (#1072) where a unit dispatched inside
+        // handleAgentEnd (hooks, triage, quick-task) completes before we return,
+        // and its agent_end is silently dropped — leaving auto-mode active but
+        // permanently stalled with no unit running and no watchdog set.
+        if (s.pendingAgentEndRetry) {
+            s.pendingAgentEndRetry = false;
+            // Clear gap watchdog from the previous cycle to prevent concurrent
+            // dispatch when the deferred handleAgentEnd calls dispatchNextUnit (#1272).
+            clearDispatchGapWatchdog();
+            setImmediate(() => {
+                handleAgentEnd(ctx, pi).catch((err) => {
+                    const msg = getErrorMessage(err);
+                    ctx.ui.notify(`Deferred agent_end retry failed: ${msg}`, "error");
+                    pauseAuto(ctx, pi).catch(() => { });
+                });
+            });
+        }
+    }
+}
+// ─── Step Mode Wizard ─────────────────────────────────────────────────────
+/**
+ * Show the step-mode wizard after a unit completes.
+ */
+async function showStepWizard(ctx, pi) {
+    if (!s.cmdCtx)
+        return;
+    const state = await deriveState(s.basePath);
+    const mid = state.activeMilestone?.id;
+    const justFinished = s.currentUnit
+        ? `${unitVerb(s.currentUnit.type)} ${s.currentUnit.id}`
+        : "previous unit";
+    if (!mid || state.phase === "complete") {
+        const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
+        if (incomplete.length > 0 && state.phase !== "complete" && state.phase !== "blocked" && state.phase !== "pre-planning") {
+            const ids = incomplete.map(m => m.id).join(", ");
+            const diag = `basePath=${s.basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
+            ctx.ui.notify(`Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`, "error");
+            await stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids})`);
+        }
+        else {
+            await stopAuto(ctx, pi, state.phase === "complete" ? "All work complete" : "No active milestone");
+        }
+        return;
+    }
+    const nextDesc = _describeNextUnit(state);
+    const choice = await showNextAction(s.cmdCtx, {
+        title: `GSD — ${justFinished} complete`,
+        summary: [
+            `${mid}: ${state.activeMilestone?.title ?? mid}`,
+            ...(state.activeSlice ? [`${state.activeSlice.id}: ${state.activeSlice.title}`] : []),
+        ],
+        actions: [
+            {
+                id: "continue",
+                label: nextDesc.label,
+                description: nextDesc.description,
+                recommended: true,
+            },
+            {
+                id: "auto",
+                label: "Switch to auto",
+                description: "Continue without pausing between steps.",
+            },
+            {
+                id: "status",
+                label: "View status",
+                description: "Open the dashboard.",
+            },
+        ],
+        notYetMessage: "Run /gsd next when ready to continue.",
+    });
+    if (choice === "continue") {
+        await dispatchNextUnit(ctx, pi);
+    }
+    else if (choice === "auto") {
+        s.stepMode = false;
+        ctx.ui.setStatus("gsd-auto", "auto");
+        ctx.ui.notify("Switched to auto-mode.", "info");
+        await dispatchNextUnit(ctx, pi);
+    }
+    else if (choice === "status") {
+        const { fireStatusViaCommand } = await import("./commands.js");
+        await fireStatusViaCommand(ctx);
+        await showStepWizard(ctx, pi);
+    }
+    else {
+        await pauseAuto(ctx, pi);
+    }
+}
+/** Thin wrapper: delegates to auto-dashboard.ts, passing state accessors. */
+function updateProgressWidget(ctx, unitType, unitId, state) {
+    const badge = s.currentUnitRouting?.tier
+        ? ({ light: "L", standard: "S", heavy: "H" }[s.currentUnitRouting.tier] ?? undefined)
+        : undefined;
+    _updateProgressWidget(ctx, unitType, unitId, state, widgetStateAccessors, badge);
+}
+/** State accessors for the widget — closures over module globals. */
+const widgetStateAccessors = {
+    getAutoStartTime: () => s.autoStartTime,
+    isStepMode: () => s.stepMode,
+    getCmdCtx: () => s.cmdCtx,
+    getBasePath: () => s.basePath,
+    isVerbose: () => s.verbose,
+};
+// ─── Core Loop ────────────────────────────────────────────────────────────────
+async function dispatchNextUnit(ctx, pi) {
+    if (!s.active || !s.cmdCtx) {
+        debugLog(`dispatchNextUnit early return — active=${s.active}, cmdCtx=${!!s.cmdCtx}`);
+        if (s.active && !s.cmdCtx) {
+            ctx.ui.notify("Auto-mode session expired. Run /gsd auto to restart.", "info");
+        }
+        return;
+    }
+    // ── Session lock validation: detect if another process has taken over ──
+    if (lockBase() && !validateSessionLock(lockBase())) {
+        debugLog("dispatchNextUnit session-lock-lost — another process may have taken over");
+        ctx.ui.notify("Session lock lost — another GSD process appears to have taken over. Stopping gracefully.", "error");
+        // Don't call stopAuto here to avoid releasing the lock we don't own
+        s.active = false;
+        s.paused = false;
+        clearUnitTimeout();
+        deregisterSigtermHandler();
+        ctx.ui.setStatus("gsd-auto", undefined);
+        ctx.ui.setWidget("gsd-progress", undefined);
+        ctx.ui.setFooter(undefined);
+        return;
+    }
+    // Reentrancy guard — unconditional to prevent concurrent dispatch from
+    // gap watchdog or pendingAgentEndRetry during skip chains (#1272).
+    // Previously the guard was bypassed when skipDepth > 0, but the recursive
+    // skip chain's inner finally block resets s.dispatching = false before the
+    // outer call's finally runs, opening a window for concurrent entry.
+    if (s.dispatching) {
+        debugLog("dispatchNextUnit reentrancy guard — another dispatch in progress, bailing");
+        return;
+    }
+    s.dispatching = true;
+    try {
+        // Recursion depth guard
+        if (s.skipDepth > MAX_SKIP_DEPTH) {
+            s.skipDepth = 0;
+            ctx.ui.notify(`Skipped ${MAX_SKIP_DEPTH}+ completed units. Yielding to UI before continuing.`, "info");
+            await new Promise(r => setTimeout(r, 200));
+        }
+        // Resource version guard
+        const staleMsg = checkResourcesStale(s.resourceVersionOnStart);
+        if (staleMsg) {
+            await stopAuto(ctx, pi, staleMsg);
+            return;
+        }
+        invalidateAllCaches();
+        s.lastPromptCharCount = undefined;
+        s.lastBaselineCharCount = undefined;
+        // ── Pre-dispatch health gate ──
+        try {
+            const healthGate = await preDispatchHealthGate(s.basePath);
+            if (healthGate.fixesApplied.length > 0) {
+                ctx.ui.notify(`Pre-dispatch: ${healthGate.fixesApplied.join(", ")}`, "info");
+            }
+            if (!healthGate.proceed) {
+                ctx.ui.notify(healthGate.reason ?? "Pre-dispatch health check failed.", "error");
+                await pauseAuto(ctx, pi);
+                return;
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+        const stopDeriveTimer = debugTime("derive-state");
+        let state = await deriveState(s.basePath);
+        stopDeriveTimer({
+            phase: state.phase,
+            milestone: state.activeMilestone?.id,
+            slice: state.activeSlice?.id,
+            task: state.activeTask?.id,
+        });
+        let mid = state.activeMilestone?.id;
+        let midTitle = state.activeMilestone?.title;
+        // Detect milestone transition
+        if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) {
+            ctx.ui.notify(`Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}: ${midTitle}.`, "info");
+            sendDesktopNotification("GSD", `Milestone ${s.currentMilestoneId} complete!`, "success", "milestone");
+            const vizPrefs = loadEffectiveGSDPreferences()?.preferences;
+            if (vizPrefs?.auto_visualize) {
+                ctx.ui.notify("Run /gsd visualize to see progress overview.", "info");
+            }
+            if (vizPrefs?.auto_report !== false) {
+                try {
+                    const { loadVisualizerData } = await import("./visualizer-data.js");
+                    const { generateHtmlReport } = await import("./export-html.js");
+                    const { writeReportSnapshot, reportsDir } = await import("./reports.js");
+                    const { basename } = await import("node:path");
+                    const snapData = await loadVisualizerData(s.basePath);
+                    const completedMs = snapData.milestones.find(m => m.id === s.currentMilestoneId);
+                    const msTitle = completedMs?.title ?? s.currentMilestoneId;
+                    const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
+                    const projName = basename(s.basePath);
+                    const doneSlices = snapData.milestones.reduce((s, m) => s + m.slices.filter(sl => sl.done).length, 0);
+                    const totalSlices = snapData.milestones.reduce((s, m) => s + m.slices.length, 0);
+                    const outPath = writeReportSnapshot({ basePath: s.basePath,
+                        html: generateHtmlReport(snapData, {
+                            projectName: projName,
+                            projectPath: s.basePath,
+                            gsdVersion,
+                            milestoneId: s.currentMilestoneId,
+                            indexRelPath: "index.html",
+                        }),
+                        milestoneId: s.currentMilestoneId,
+                        milestoneTitle: msTitle,
+                        kind: "milestone",
+                        projectName: projName,
+                        projectPath: s.basePath,
+                        gsdVersion,
+                        totalCost: snapData.totals?.cost ?? 0,
+                        totalTokens: snapData.totals?.tokens.total ?? 0,
+                        totalDuration: snapData.totals?.duration ?? 0,
+                        doneSlices,
+                        totalSlices,
+                        doneMilestones: snapData.milestones.filter(m => m.status === "complete").length,
+                        totalMilestones: snapData.milestones.length,
+                        phase: snapData.phase,
+                    });
+                    ctx.ui.notify(`Report saved: .gsd/reports/${basename(outPath)} — open index.html to browse progression.`, "info");
+                }
+                catch (err) {
+                    ctx.ui.notify(`Report generation failed: ${getErrorMessage(err)}`, "warning");
+                }
+            }
+            // Reset stuck detection for new milestone
+            s.unitDispatchCount.clear();
+            s.unitRecoveryCount.clear();
+            s.unitConsecutiveSkips.clear();
+            s.unitLifetimeDispatches.clear();
+            try {
+                const file = completedKeysPath(s.basePath);
+                if (existsSync(file)) {
+                    atomicWriteSync(file, JSON.stringify([]));
+                }
+                s.completedKeySet.clear();
+            }
+            catch (e) {
+                debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) });
+            }
+            // ── Worktree lifecycle on milestone transition (#616) ──
+            if ((isInAutoWorktree(s.basePath) || getIsolationMode() === "branch") && shouldUseWorktreeIsolation()) {
+                tryMergeMilestone(ctx, s.currentMilestoneId, "transition");
+                // Reset to project root and re-derive state for the new milestone
+                if (s.originalBasePath) {
+                    s.basePath = s.originalBasePath;
+                    s.gitService = createGitService(s.basePath);
+                }
+                invalidateAllCaches();
+                state = await deriveState(s.basePath);
+                mid = state.activeMilestone?.id;
+                midTitle = state.activeMilestone?.title;
+                if (mid) {
+                    captureIntegrationBranch(s.basePath, mid);
+                    try {
+                        const wtPath = createAutoWorktree(s.basePath, mid);
+                        s.basePath = wtPath;
+                        s.gitService = createGitService(s.basePath);
+                        ctx.ui.notify(`Created auto-worktree for ${mid} at ${wtPath}`, "info");
+                    }
+                    catch (err) {
+                        ctx.ui.notify(`Auto-worktree creation for ${mid} failed: ${getErrorMessage(err)}. Continuing in project root.`, "warning");
+                    }
+                }
+            }
+            else {
+                if (getIsolationMode() !== "none") {
+                    captureIntegrationBranch(s.originalBasePath || s.basePath, mid);
+                }
+            }
+            const pendingIds = (state.registry ?? [])
+                .filter(m => m.status !== "complete")
+                .map(m => m.id);
+            pruneQueueOrder(s.basePath, pendingIds);
+        }
+        if (mid) {
+            s.currentMilestoneId = mid;
+            setActiveMilestoneId(s.basePath, mid);
+        }
+        if (!mid) {
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            }
+            const incomplete = (state.registry ?? []).filter(m => m.status !== "complete" && m.status !== "parked");
+            if (incomplete.length === 0) {
+                // Genuinely all complete (parked milestones excluded) — merge milestone branch to main before stopping (#962)
+                if (s.currentMilestoneId) {
+                    tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
+                }
+                sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
+                await stopAuto(ctx, pi, "All milestones complete");
+            }
+            else if (state.phase === "blocked") {
+                const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+                await stopAuto(ctx, pi, blockerMsg);
+                ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+                sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+            }
+            else {
+                const ids = incomplete.map(m => m.id).join(", ");
+                const diag = `basePath=${s.basePath}, milestones=[${state.registry.map(m => `${m.id}:${m.status}`).join(", ")}], phase=${state.phase}`;
+                ctx.ui.notify(`Unexpected: ${incomplete.length} incomplete milestone(s) (${ids}) but no active milestone.\n   Diagnostic: ${diag}`, "error");
+                await stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids}), see diagnostic above`);
+            }
+            return;
+        }
+        if (!midTitle) {
+            midTitle = mid;
+            ctx.ui.notify(`Milestone ${mid} has no title in roadmap — using ID as fallback.`, "warning");
+        }
+        // ── Mid-merge safety check ──
+        if (reconcileMergeState(s.basePath, ctx)) {
+            invalidateAllCaches();
+            state = await deriveState(s.basePath);
+            mid = state.activeMilestone?.id;
+            midTitle = state.activeMilestone?.title;
+        }
+        if (!mid || !midTitle) {
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            }
+            const noMilestoneReason = !mid
+                ? "No active milestone after merge reconciliation"
+                : `Milestone ${mid} has no title after reconciliation`;
+            await stopAuto(ctx, pi, noMilestoneReason);
+            return;
+        }
+        // Determine next unit
+        let unitType;
+        let unitId;
+        let prompt;
+        if (state.phase === "complete") {
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            }
+            try {
+                const file = completedKeysPath(s.basePath);
+                if (existsSync(file)) {
+                    atomicWriteSync(file, JSON.stringify([]));
+                }
+                s.completedKeySet.clear();
+            }
+            catch (e) {
+                debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) });
+            }
+            // ── Milestone merge ──
+            if (s.currentMilestoneId) {
+                tryMergeMilestone(ctx, s.currentMilestoneId, "complete");
+            }
+            sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
+            await stopAuto(ctx, pi, `Milestone ${mid} complete`);
+            return;
+        }
+        if (state.phase === "blocked") {
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            }
+            const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+            await stopAuto(ctx, pi, blockerMsg);
+            ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+            sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+            return;
+        }
+        // Budget ceiling guard, context window guard, secrets gate, dispatch table
+        const prefs = loadEffectiveGSDPreferences()?.preferences;
+        const budgetCeiling = prefs?.budget_ceiling;
+        if (budgetCeiling !== undefined && budgetCeiling > 0) {
+            const currentLedger = getLedger();
+            const totalCost = currentLedger ? getProjectTotals(currentLedger.units).cost : 0;
+            const budgetPct = totalCost / budgetCeiling;
+            const budgetAlertLevel = getBudgetAlertLevel(budgetPct);
+            const newBudgetAlertLevel = getNewBudgetAlertLevel(s.lastBudgetAlertLevel, budgetPct);
+            const enforcement = prefs?.budget_enforcement ?? "pause";
+            const budgetEnforcementAction = getBudgetEnforcementAction(enforcement, budgetPct);
+            if (newBudgetAlertLevel === 100 && budgetEnforcementAction !== "none") {
+                const msg = `Budget ceiling ${formatCost(budgetCeiling)} reached (spent ${formatCost(totalCost)}).`;
+                s.lastBudgetAlertLevel = newBudgetAlertLevel;
+                if (budgetEnforcementAction === "halt") {
+                    sendDesktopNotification("GSD", msg, "error", "budget");
+                    await stopAuto(ctx, pi, "Budget ceiling reached");
+                    return;
+                }
+                if (budgetEnforcementAction === "pause") {
+                    ctx.ui.notify(`${msg} Pausing auto-mode — /gsd auto to override and continue.`, "warning");
+                    sendDesktopNotification("GSD", msg, "warning", "budget");
+                    await pauseAuto(ctx, pi);
+                    return;
+                }
+                ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
+                sendDesktopNotification("GSD", msg, "warning", "budget");
+            }
+            else if (newBudgetAlertLevel === 90) {
+                s.lastBudgetAlertLevel = newBudgetAlertLevel;
+                ctx.ui.notify(`Budget 90%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning");
+                sendDesktopNotification("GSD", `Budget 90%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning", "budget");
+            }
+            else if (newBudgetAlertLevel === 80) {
+                s.lastBudgetAlertLevel = newBudgetAlertLevel;
+                ctx.ui.notify(`Approaching budget ceiling — 80%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning");
+                sendDesktopNotification("GSD", `Approaching budget ceiling — 80%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "warning", "budget");
+            }
+            else if (newBudgetAlertLevel === 75) {
+                s.lastBudgetAlertLevel = newBudgetAlertLevel;
+                ctx.ui.notify(`Budget 75%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "info");
+                sendDesktopNotification("GSD", `Budget 75%: ${formatCost(totalCost)} / ${formatCost(budgetCeiling)}`, "info", "budget");
+            }
+            else if (budgetAlertLevel === 0) {
+                s.lastBudgetAlertLevel = 0;
+            }
+        }
+        else {
+            s.lastBudgetAlertLevel = 0;
+        }
+        const contextThreshold = prefs?.context_pause_threshold ?? 0;
+        if (contextThreshold > 0 && s.cmdCtx) {
+            const contextUsage = s.cmdCtx.getContextUsage();
+            if (contextUsage && contextUsage.percent !== null && contextUsage.percent >= contextThreshold) {
+                const msg = `Context window at ${contextUsage.percent}% (threshold: ${contextThreshold}%). Pausing to prevent truncated output.`;
+                ctx.ui.notify(`${msg} Run /gsd auto to continue (will start fresh session).`, "warning");
+                sendDesktopNotification("GSD", `Context ${contextUsage.percent}% — paused`, "warning", "attention");
+                await pauseAuto(ctx, pi);
+                return;
+            }
+        }
+        // Secrets re-check gate
+        const runSecretsGate = async () => {
+            try {
+                const manifestStatus = await getManifestStatus(s.basePath, mid);
+                if (manifestStatus && manifestStatus.pending.length > 0) {
+                    const result = await collectSecretsFromManifest(s.basePath, 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: ${getErrorMessage(err)}. Continuing with next task.`, "warning");
+            }
+        };
+        await runSecretsGate();
+        // ── Interactive discussion gate ──
+        // If the active milestone needs discussion (has CONTEXT-DRAFT.md but no roadmap),
+        // stop auto-mode and route to the interactive discussion flow. The guided-flow
+        // handles needs-discussion correctly — it just needs to be called instead of
+        // letting the dispatch table fire "needs-discussion → stop" (#1170).
+        if (state.phase === "needs-discussion") {
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            }
+            const cmdCtx = s.cmdCtx;
+            const basePath = s.basePath;
+            await stopAuto(ctx, pi, `${mid}: ${midTitle} needs discussion before planning.`);
+            const { showSmartEntry } = await import("./guided-flow.js");
+            await showSmartEntry(cmdCtx, pi, basePath);
+            return;
+        }
+        // ── Dispatch table ──
+        const dispatchResult = await resolveDispatch({ basePath: s.basePath, mid, midTitle: midTitle, state, prefs, });
+        if (dispatchResult.action === "stop") {
+            if (s.currentUnit) {
+                await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            }
+            await stopAuto(ctx, pi, dispatchResult.reason);
+            return;
+        }
+        if (dispatchResult.action !== "dispatch") {
+            // Defer re-dispatch to next microtask so s.dispatching is released first,
+            // preventing reentrancy guard bypass during concurrent entry (#1272).
+            setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
+                ctx.ui.notify(`Deferred dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+                pauseAuto(ctx, pi).catch(() => { });
+            }));
+            return;
+        }
+        unitType = dispatchResult.unitType;
+        unitId = dispatchResult.unitId;
+        prompt = dispatchResult.prompt;
+        // ── Pre-dispatch hooks ──
+        const preDispatchResult = runPreDispatchHooks(unitType, unitId, prompt, s.basePath);
+        if (preDispatchResult.firedHooks.length > 0) {
+            ctx.ui.notify(`Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`, "info");
+        }
+        if (preDispatchResult.action === "skip") {
+            ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
+            setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
+                ctx.ui.notify(`Deferred dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+                pauseAuto(ctx, pi).catch(() => { });
+            }));
+            return;
+        }
+        if (preDispatchResult.action === "replace") {
+            prompt = preDispatchResult.prompt ?? prompt;
+            if (preDispatchResult.unitType)
+                unitType = preDispatchResult.unitType;
+        }
+        else if (preDispatchResult.prompt) {
+            prompt = preDispatchResult.prompt;
+        }
+        const priorSliceBlocker = getPriorSliceCompletionBlocker(s.basePath, getMainBranch(s.basePath), unitType, unitId);
+        if (priorSliceBlocker) {
+            await stopAuto(ctx, pi, priorSliceBlocker);
+            return;
+        }
+        const observabilityIssues = await _collectObservabilityWarnings(ctx, s.basePath, unitType, unitId);
+        // ── Idempotency check (delegated to auto-idempotency.ts) ──
+        const idempotencyResult = checkIdempotency({
+            s,
+            unitType,
+            unitId,
+            basePath: s.basePath,
+            notify: (msg, level) => ctx.ui.notify(msg, level),
+        });
+        if (idempotencyResult.action === "skip") {
+            if (idempotencyResult.reason === "completed" || idempotencyResult.reason === "fallback-persisted" || idempotencyResult.reason === "phantom-loop-cleared" || idempotencyResult.reason === "evicted") {
+                if (!s.active)
+                    return;
+                s.skipDepth++;
+                const skipDelay = idempotencyResult.reason === "phantom-loop-cleared" ? 50 : 150;
+                // Defer re-dispatch so s.dispatching is released first (#1272).
+                setTimeout(() => {
+                    dispatchNextUnit(ctx, pi).catch(err => {
+                        ctx.ui.notify(`Deferred skip-dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+                        pauseAuto(ctx, pi).catch(() => { });
+                    }).finally(() => {
+                        s.skipDepth = Math.max(0, s.skipDepth - 1);
+                    });
+                }, skipDelay);
+                return;
+            }
+        }
+        else if (idempotencyResult.action === "stop") {
+            await stopAuto(ctx, pi, idempotencyResult.reason);
+            ctx.ui.notify(`Hard loop detected: ${unitType} ${unitId} hit lifetime cap during skip cycle.`, "error");
+            return;
+        }
+        // "rerun" and "proceed" fall through to stuck detection
+        // ── Stuck detection (delegated to auto-stuck-detection.ts) ──
+        const stuckResult = await checkStuckAndRecover({
+            s,
+            ctx,
+            unitType,
+            unitId,
+            basePath: s.basePath,
+            buildSnapshotOpts: () => buildSnapshotOpts(unitType, unitId),
+        });
+        if (stuckResult.action === "stop") {
+            await stopAuto(ctx, pi, stuckResult.reason);
+            if (stuckResult.notifyMessage) {
+                ctx.ui.notify(stuckResult.notifyMessage, "error");
+            }
+            return;
+        }
+        if (stuckResult.action === "recovered" && stuckResult.dispatchAgain) {
+            // Defer re-dispatch so s.dispatching is released first (#1272).
+            setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
+                ctx.ui.notify(`Deferred recovery-dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+                pauseAuto(ctx, pi).catch(() => { });
+            }));
+            return;
+        }
+        // Snapshot metrics + activity log for the PREVIOUS unit before we reassign.
+        if (s.currentUnit) {
+            await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+            if (s.currentUnitRouting) {
+                const isRetry = s.currentUnit.type === unitType && s.currentUnit.id === unitId;
+                recordOutcome(s.currentUnit.type, s.currentUnitRouting.tier, !isRetry);
+            }
+            const closeoutKey = `${s.currentUnit.type}/${s.currentUnit.id}`;
+            const incomingKey = `${unitType}/${unitId}`;
+            const isHookUnit = s.currentUnit.type.startsWith("hook/");
+            const artifactVerified = isHookUnit || verifyExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
+            if (closeoutKey !== incomingKey && artifactVerified) {
+                if (!isHookUnit) {
+                    persistCompletedKey(s.basePath, closeoutKey);
+                    s.completedKeySet.add(closeoutKey);
+                }
+                s.completedUnits.push({
+                    type: s.currentUnit.type,
+                    id: s.currentUnit.id,
+                    startedAt: s.currentUnit.startedAt,
+                    finishedAt: Date.now(),
+                });
+                if (s.completedUnits.length > 200) {
+                    s.completedUnits = s.completedUnits.slice(-200);
+                }
+                clearUnitRuntimeRecord(s.basePath, s.currentUnit.type, s.currentUnit.id);
+                s.unitDispatchCount.delete(`${s.currentUnit.type}/${s.currentUnit.id}`);
+                s.unitRecoveryCount.delete(`${s.currentUnit.type}/${s.currentUnit.id}`);
+            }
+        }
+        s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
+        captureAvailableSkills();
+        writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+            phase: "dispatched",
+            wrapupWarningSent: false,
+            timeoutAt: null,
+            lastProgressAt: s.currentUnit.startedAt,
+            progressCount: 0,
+            lastProgressKind: "dispatch",
+        });
+        // Status bar + progress widget
+        ctx.ui.setStatus("gsd-auto", "auto");
+        if (mid)
+            updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
+        updateProgressWidget(ctx, unitType, unitId, state);
+        ensurePreconditions(unitType, unitId, s.basePath, state);
+        // Fresh session — with timeout to prevent permanent hangs (#1073).
+        // If newSession() hangs (e.g., session manager deadlock, network issue),
+        // without this timeout the entire dispatch chain stalls permanently: no
+        // timeouts are set, no gap watchdog fires, and auto-mode is left active
+        // but idle until the user Ctrl+C's.
+        let result;
+        try {
+            const sessionPromise = s.cmdCtx.newSession();
+            const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve({ cancelled: true }), NEW_SESSION_TIMEOUT_MS));
+            result = await Promise.race([sessionPromise, timeoutPromise]);
+        }
+        catch (sessionErr) {
+            const msg = getErrorMessage(sessionErr);
+            ctx.ui.notify(`Session creation failed: ${msg}. Retrying via watchdog.`, "error");
+            throw new Error(`newSession() failed: ${msg}`);
+        }
+        if (result.cancelled) {
+            ctx.ui.notify(`Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`, "warning");
+            await stopAuto(ctx, pi, "Session creation failed");
+            return;
+        }
+        const sessionFile = ctx.sessionManager.getSessionFile();
+        updateSessionLock(lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
+        writeLock(lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
+        // Prompt injection
+        const MAX_RECOVERY_CHARS = 50_000;
+        let finalPrompt = prompt;
+        if (s.pendingVerificationRetry) {
+            const retryCtx = s.pendingVerificationRetry;
+            s.pendingVerificationRetry = null;
+            const capped = retryCtx.failureContext.length > MAX_RECOVERY_CHARS
+                ? retryCtx.failureContext.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...failure context truncated]"
+                : retryCtx.failureContext;
+            finalPrompt = `**VERIFICATION FAILED — AUTO-FIX ATTEMPT ${retryCtx.attempt}**\n\nThe verification gate ran after your previous attempt and found failures. Fix these issues before completing the task.\n\n${capped}\n\n---\n\n${finalPrompt}`;
+        }
+        if (s.pendingCrashRecovery) {
+            const capped = s.pendingCrashRecovery.length > MAX_RECOVERY_CHARS
+                ? s.pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
+                : s.pendingCrashRecovery;
+            finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
+            s.pendingCrashRecovery = null;
+        }
+        else if ((s.unitDispatchCount.get(`${unitType}/${unitId}`) ?? 0) > 1) {
+            const diagnostic = getDeepDiagnostic(s.basePath);
+            if (diagnostic) {
+                const cappedDiag = diagnostic.length > MAX_RECOVERY_CHARS
+                    ? diagnostic.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...diagnostic truncated to prevent memory exhaustion]"
+                    : diagnostic;
+                finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
+            }
+        }
+        const repairBlock = buildObservabilityRepairBlock(observabilityIssues);
+        if (repairBlock) {
+            finalPrompt = `${finalPrompt}${repairBlock}`;
+        }
+        // ── Prompt char measurement ──
+        s.lastPromptCharCount = finalPrompt.length;
+        s.lastBaselineCharCount = undefined;
+        if (isDbAvailable()) {
+            try {
+                const { inlineGsdRootFile } = await import("./auto-prompts.js");
+                const [decisionsContent, requirementsContent, projectContent] = await Promise.all([
+                    inlineGsdRootFile(s.basePath, "decisions.md", "Decisions"),
+                    inlineGsdRootFile(s.basePath, "requirements.md", "Requirements"),
+                    inlineGsdRootFile(s.basePath, "project.md", "Project"),
+                ]);
+                s.lastBaselineCharCount =
+                    (decisionsContent?.length ?? 0) +
+                        (requirementsContent?.length ?? 0) +
+                        (projectContent?.length ?? 0);
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+        // Cache-optimize prompt section ordering
+        try {
+            const { reorderForCaching } = await import("./prompt-ordering.js");
+            finalPrompt = reorderForCaching(finalPrompt);
+        }
+        catch (reorderErr) {
+            const msg = getErrorMessage(reorderErr);
+            process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
+        }
+        // Select and apply model
+        const modelResult = await selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel);
+        s.currentUnitRouting = modelResult.routing;
+        // ── Start unit supervision (delegated to auto-timers.ts) ──
+        clearUnitTimeout();
+        startUnitSupervision({
+            s,
+            ctx,
+            pi,
+            unitType,
+            unitId,
+            prefs,
+            buildSnapshotOpts: () => buildSnapshotOpts(unitType, unitId),
+            buildRecoveryContext: () => buildRecoveryContext(),
+            pauseAuto,
+        });
+        // Inject prompt
+        if (!s.active)
+            return;
+        pi.sendMessage({ customType: "gsd-auto", content: finalPrompt, display: s.verbose }, { triggerTurn: true });
+    }
+    finally {
+        s.dispatching = false;
+    }
+}
+// ─── Preconditions ────────────────────────────────────────────────────────────
+/**
+ * Ensure directories, branches, and other prerequisites exist before
+ * dispatching a unit. The LLM should never need to mkdir or git checkout.
+ */
+function ensurePreconditions(unitType, unitId, base, state) {
+    const { milestone: mid } = parseUnitId(unitId);
+    const mDir = resolveMilestonePath(base, mid);
+    if (!mDir) {
+        const newDir = join(milestonesDir(base), mid);
+        mkdirSync(join(newDir, "slices"), { recursive: true });
+    }
+    const sid = parseUnitId(unitId).slice;
+    if (sid) {
+        const mDirResolved = resolveMilestonePath(base, mid);
+        if (mDirResolved) {
+            const slicesDir = join(mDirResolved, "slices");
+            const sDir = resolveDir(slicesDir, sid);
+            if (!sDir) {
+                mkdirSync(join(slicesDir, sid, "tasks"), { recursive: true });
+            }
+            const resolvedSliceDir = resolveDir(slicesDir, sid) ?? sid;
+            const tasksDir = join(slicesDir, resolvedSliceDir, "tasks");
+            if (!existsSync(tasksDir)) {
+                mkdirSync(tasksDir, { recursive: true });
+            }
+        }
+    }
+}
+// ─── Diagnostics ──────────────────────────────────────────────────────────────
+/** Build recovery context from module state for recoverTimedOutUnit */
+function buildRecoveryContext() {
+    return { basePath: s.basePath, verbose: s.verbose,
+        currentUnitStartedAt: s.currentUnit?.startedAt ?? Date.now(), unitRecoveryCount: s.unitRecoveryCount,
+        dispatchNextUnit,
+    };
+}
+// Re-export recovery functions for external consumers
+export { resolveExpectedArtifactPath, verifyExpectedArtifact, writeBlockerPlaceholder, skipExecuteTask, buildLoopRemediationSteps, } from "./auto-recovery.js";
+/**
+ * Test-only: expose skip-loop state for unit tests.
+ * Not part of the public API.
+ */
+export function _getUnitConsecutiveSkips() { return s.unitConsecutiveSkips; }
+export function _resetUnitConsecutiveSkips() { s.unitConsecutiveSkips.clear(); }
+/**
+ * Test-only: expose dispatching / skipDepth state for reentrancy guard tests.
+ * Not part of the public API.
+ */
+export function _getDispatching() { return s.dispatching; }
+export function _setDispatching(v) { s.dispatching = v; }
+export function _getSkipDepth() { return s.skipDepth; }
+export function _setSkipDepth(v) { s.skipDepth = v; }
+/**
+ * Dispatch a hook unit directly, bypassing normal pre-dispatch hooks.
+ * Used for manual hook triggers via /gsd run-hook.
+ */
+export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, triggerUnitId, hookPrompt, hookModel, targetBasePath) {
+    if (!s.active) {
+        s.active = true;
+        s.stepMode = true;
+        s.cmdCtx = ctx;
+        s.basePath = targetBasePath;
+        s.autoStartTime = Date.now();
+        s.currentUnit = null;
+        s.completedUnits = [];
+        s.pendingQuickTasks = [];
+    }
+    const hookUnitType = `hook/${hookName}`;
+    const hookStartedAt = Date.now();
+    s.currentUnit = { type: triggerUnitType, id: triggerUnitId, startedAt: hookStartedAt };
+    const result = await s.cmdCtx.newSession();
+    if (result.cancelled) {
+        await stopAuto(ctx, pi);
+        return false;
+    }
+    s.currentUnit = { type: hookUnitType, id: triggerUnitId, startedAt: hookStartedAt };
+    writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: hookStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+    });
+    if (hookModel) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const match = availableModels.find(m => m.id === hookModel || `${m.provider}/${m.id}` === hookModel);
+        if (match) {
+            try {
+                await pi.setModel(match);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    updateSessionLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
+    writeLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
+    clearUnitTimeout();
+    const supervisor = resolveAutoSupervisorConfig();
+    const hookHardTimeoutMs = (supervisor.hard_timeout_minutes ?? 30) * 60 * 1000;
+    s.unitTimeoutHandle = setTimeout(async () => {
+        s.unitTimeoutHandle = null;
+        if (!s.active)
+            return;
+        if (s.currentUnit) {
+            writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
+                phase: "timeout",
+                timeoutAt: Date.now(),
+            });
+        }
+        ctx.ui.notify(`Hook ${hookName} exceeded ${supervisor.hard_timeout_minutes ?? 30}min timeout. Pausing auto-mode.`, "warning");
+        resetHookState();
+        await pauseAuto(ctx, pi);
+    }, hookHardTimeoutMs);
+    ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
+    ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
+    pi.sendMessage({ customType: "gsd-auto", content: hookPrompt, display: true }, { triggerTurn: true });
+    return true;
+}