gsd-pi 2.33.1 → 2.34.0-dev.6769913

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

@@ -0,0 +1,956 @@
+/**
+ * auto-loop.ts — Linear loop execution backbone for auto-mode.
+ *
+ * Replaces the recursive dispatchNextUnit → handleAgentEnd → dispatchNextUnit
+ * pattern with a while loop. The agent_end event resolves a promise instead
+ * of recursing.
+ *
+ * MAINTENANCE RULE: The only module-level mutable state here is `_activeSession`,
+ * used by the agent_end bridge. Promise state itself lives on AutoSession so
+ * concurrent auto sessions cannot corrupt each other.
+ */
+import { NEW_SESSION_TIMEOUT_MS } from "./auto/session.js";
+import { debugLog } from "./debug-logger.js";
+/**
+ * Maximum total loop iterations before forced stop. Prevents runaway loops
+ * when units alternate IDs (bypassing the same-unit stuck detector).
+ * A milestone with 20 slices × 5 tasks × 3 phases ≈ 300 units. 500 gives
+ * generous headroom including retries and sidecar work.
+ */
+const MAX_LOOP_ITERATIONS = 500;
+// ─── Session-scoped promise state ───────────────────────────────────────────
+//
+// pendingResolve and pendingAgentEndQueue live on AutoSession (not module-level)
+// so concurrent sessions cannot corrupt each other's promises.
+/**
+ * The singleton session reference used by resolveAgentEnd. Set by autoLoop
+ * on entry so that the agent_end handler in index.ts can resolve the correct
+ * session's promise without needing a direct reference to `s`.
+ */
+let _activeSession = null;
+// ─── resolveAgentEnd ─────────────────────────────────────────────────────────
+/**
+ * Called from the agent_end event handler in index.ts to resolve the
+ * in-flight unit promise. One-shot: the resolver is nulled before calling
+ * to prevent double-resolution from model fallback retries.
+ *
+ * If no pendingResolve exists (event arrived between loop iterations),
+ * the event is queued on the session so the next runUnit can drain it.
+ */
+export function resolveAgentEnd(event) {
+    const s = _activeSession;
+    if (!s) {
+        debugLog("resolveAgentEnd", {
+            status: "no-active-session",
+            warning: "agent_end with no active loop session",
+        });
+        return;
+    }
+    if (s.pendingResolve) {
+        debugLog("resolveAgentEnd", { status: "resolving", hasEvent: true });
+        const r = s.pendingResolve;
+        s.pendingResolve = null;
+        r({ status: "completed", event });
+    }
+    else {
+        // Queue the event so the next runUnit picks it up immediately
+        debugLog("resolveAgentEnd", {
+            status: "queued",
+            queueLength: s.pendingAgentEndQueue.length + 1,
+            warning: "agent_end arrived between loop iterations — queued for next runUnit",
+        });
+        s.pendingAgentEndQueue.push(event);
+    }
+}
+export function isSessionSwitchInFlight() {
+    return _activeSession?.sessionSwitchInFlight ?? false;
+}
+// ─── resetPendingResolve (test helper) ───────────────────────────────────────
+/**
+ * Reset session promise state. Only exported for test cleanup — production code
+ * should never call this.
+ */
+export function _resetPendingResolve() {
+    if (_activeSession) {
+        _activeSession.pendingResolve = null;
+        _activeSession.pendingAgentEndQueue = [];
+    }
+    _activeSession = null;
+}
+/**
+ * Set the active session for resolveAgentEnd. Only exported for test setup —
+ * production code sets this via autoLoop entry.
+ */
+export function _setActiveSession(session) {
+    _activeSession = session;
+}
+// ─── runUnit ─────────────────────────────────────────────────────────────────
+/**
+ * Execute a single unit: create a new session, send the prompt, and await
+ * the agent_end promise. Returns a UnitResult describing what happened.
+ *
+ * The promise is one-shot: resolveAgentEnd() is the only way to resolve it.
+ * On session creation failure or timeout, returns { status: 'cancelled' }
+ * without awaiting the promise.
+ */
+export async function runUnit(ctx, pi, s, unitType, unitId, prompt, _prefs) {
+    debugLog("runUnit", { phase: "start", unitType, unitId });
+    // ── Drain queued events from error-recovery retries ──
+    // If an agent_end arrived between iterations (e.g. from a model fallback
+    // sendMessage retry), consume it immediately instead of creating a new promise.
+    // Cap queue to 3 entries to prevent unbounded growth from stale events.
+    if (s.pendingAgentEndQueue.length > 3) {
+        debugLog("runUnit", {
+            phase: "queue-overflow",
+            dropped: s.pendingAgentEndQueue.length - 1,
+            unitType,
+            unitId,
+        });
+        s.pendingAgentEndQueue = [
+            s.pendingAgentEndQueue[s.pendingAgentEndQueue.length - 1],
+        ];
+    }
+    if (s.pendingAgentEndQueue.length > 0) {
+        const queued = s.pendingAgentEndQueue.shift();
+        debugLog("runUnit", {
+            phase: "drained-queued-event",
+            unitType,
+            unitId,
+            queueRemaining: s.pendingAgentEndQueue.length,
+        });
+        return { status: "completed", event: queued };
+    }
+    // ── Session creation with timeout ──
+    debugLog("runUnit", { phase: "session-create", unitType, unitId });
+    let sessionResult;
+    let sessionTimeoutHandle;
+    s.sessionSwitchInFlight = true;
+    try {
+        const sessionPromise = s.cmdCtx.newSession().finally(() => {
+            s.sessionSwitchInFlight = false;
+        });
+        const timeoutPromise = new Promise((resolve) => {
+            sessionTimeoutHandle = setTimeout(() => resolve({ cancelled: true }), NEW_SESSION_TIMEOUT_MS);
+        });
+        sessionResult = await Promise.race([sessionPromise, timeoutPromise]);
+    }
+    catch (sessionErr) {
+        if (sessionTimeoutHandle)
+            clearTimeout(sessionTimeoutHandle);
+        const msg = sessionErr instanceof Error ? sessionErr.message : String(sessionErr);
+        debugLog("runUnit", {
+            phase: "session-error",
+            unitType,
+            unitId,
+            error: msg,
+        });
+        return { status: "cancelled" };
+    }
+    if (sessionTimeoutHandle)
+        clearTimeout(sessionTimeoutHandle);
+    if (sessionResult.cancelled) {
+        debugLog("runUnit-session-timeout", { unitType, unitId });
+        return { status: "cancelled" };
+    }
+    if (!s.active) {
+        return { status: "cancelled" };
+    }
+    // ── Create the agent_end promise (session-scoped) ──
+    // This happens after newSession completes so session-switch agent_end events
+    // from the previous session cannot resolve the new unit.
+    const unitPromise = new Promise((resolve) => {
+        s.pendingResolve = resolve;
+    });
+    // ── Send the prompt ──
+    debugLog("runUnit", { phase: "send-message", unitType, unitId });
+    pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
+    // ── Await agent_end ──
+    debugLog("runUnit", { phase: "awaiting-agent-end", unitType, unitId });
+    const result = await unitPromise;
+    debugLog("runUnit", {
+        phase: "agent-end-received",
+        unitType,
+        unitId,
+        status: result.status,
+    });
+    return result;
+}
+// ─── autoLoop ────────────────────────────────────────────────────────────────
+/**
+ * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
+ * runUnit → finalize → repeat. Exits when s.active becomes false or a
+ * terminal condition is reached.
+ *
+ * This is the linear replacement for the recursive
+ * dispatchNextUnit → handleAgentEnd → dispatchNextUnit chain.
+ */
+export async function autoLoop(ctx, pi, s, deps) {
+    debugLog("autoLoop", { phase: "enter" });
+    _activeSession = s;
+    let iteration = 0;
+    let lastDerivedUnit = "";
+    let sameUnitCount = 0;
+    let consecutiveErrors = 0;
+    while (s.active) {
+        iteration++;
+        debugLog("autoLoop", { phase: "loop-top", iteration });
+        if (iteration > MAX_LOOP_ITERATIONS) {
+            debugLog("autoLoop", {
+                phase: "exit",
+                reason: "max-iterations",
+                iteration,
+            });
+            await deps.stopAuto(ctx, pi, `Safety: loop exceeded ${MAX_LOOP_ITERATIONS} iterations — possible runaway`);
+            break;
+        }
+        if (!s.cmdCtx) {
+            debugLog("autoLoop", { phase: "exit", reason: "no-cmdCtx" });
+            break;
+        }
+        try {
+            // ── Blanket try/catch: one bad iteration must not kill the session
+            if (deps.lockBase() && !deps.validateSessionLock(deps.lockBase())) {
+                deps.handleLostSessionLock(ctx);
+                debugLog("autoLoop", { phase: "exit", reason: "session-lock-lost" });
+                break;
+            }
+            // ── Phase 1: Pre-dispatch ───────────────────────────────────────────
+            // Resource version guard
+            const staleMsg = deps.checkResourcesStale(s.resourceVersionOnStart);
+            if (staleMsg) {
+                await deps.stopAuto(ctx, pi, staleMsg);
+                debugLog("autoLoop", { phase: "exit", reason: "resources-stale" });
+                break;
+            }
+            deps.invalidateAllCaches();
+            s.lastPromptCharCount = undefined;
+            s.lastBaselineCharCount = undefined;
+            // Pre-dispatch health gate
+            try {
+                const healthGate = await deps.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 deps.pauseAuto(ctx, pi);
+                    debugLog("autoLoop", { phase: "exit", reason: "health-gate-failed" });
+                    break;
+                }
+            }
+            catch {
+                // Non-fatal
+            }
+            // Sync project root artifacts into worktree
+            if (s.originalBasePath &&
+                s.basePath !== s.originalBasePath &&
+                s.currentMilestoneId) {
+                deps.syncProjectRootToWorktree(s.originalBasePath, s.basePath, s.currentMilestoneId);
+            }
+            // Derive state
+            let state = await deps.deriveState(s.basePath);
+            let mid = state.activeMilestone?.id;
+            let midTitle = state.activeMilestone?.title;
+            debugLog("autoLoop", {
+                phase: "state-derived",
+                iteration,
+                mid,
+                statePhase: state.phase,
+            });
+            // ── Milestone transition ────────────────────────────────────────────
+            if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) {
+                ctx.ui.notify(`Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}: ${midTitle}.`, "info");
+                deps.sendDesktopNotification("GSD", `Milestone ${s.currentMilestoneId} complete!`, "success", "milestone");
+                const vizPrefs = deps.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 } = 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((acc, m) => acc +
+                            m.slices.filter((sl) => sl.done).length, 0);
+                        const totalSlices = snapData.milestones.reduce((acc, m) => acc + 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/${(await import("node:path")).basename(outPath)} — open index.html to browse progression.`, "info");
+                    }
+                    catch (err) {
+                        ctx.ui.notify(`Report generation failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+                    }
+                }
+                // Reset dispatch counters for new milestone
+                s.unitDispatchCount.clear();
+                s.unitRecoveryCount.clear();
+                s.unitLifetimeDispatches.clear();
+                lastDerivedUnit = "";
+                sameUnitCount = 0;
+                // Worktree lifecycle on milestone transition — merge current, enter next
+                deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                deps.invalidateAllCaches();
+                state = await deps.deriveState(s.basePath);
+                mid = state.activeMilestone?.id;
+                midTitle = state.activeMilestone?.title;
+                if (mid) {
+                    if (deps.getIsolationMode() !== "none") {
+                        deps.captureIntegrationBranch(s.basePath, mid, {
+                            commitDocs: deps.loadEffectiveGSDPreferences()?.preferences?.git
+                                ?.commit_docs,
+                        });
+                    }
+                    deps.resolver.enterMilestone(mid, ctx.ui);
+                }
+                else {
+                    // mid is undefined — no milestone to capture integration branch for
+                }
+                const pendingIds = state.registry
+                    .filter((m) => m.status !== "complete" && m.status !== "parked")
+                    .map((m) => m.id);
+                deps.pruneQueueOrder(s.basePath, pendingIds);
+            }
+            if (mid) {
+                s.currentMilestoneId = mid;
+                deps.setActiveMilestoneId(s.basePath, mid);
+            }
+            // ── Terminal conditions ──────────────────────────────────────────────
+            if (!mid) {
+                if (s.currentUnit) {
+                    await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+                }
+                const incomplete = state.registry.filter((m) => m.status !== "complete" && m.status !== "parked");
+                if (incomplete.length === 0) {
+                    // All milestones complete — merge milestone branch before stopping
+                    if (s.currentMilestoneId) {
+                        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                    }
+                    deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
+                    await deps.stopAuto(ctx, pi, "All milestones complete");
+                }
+                else if (state.phase === "blocked") {
+                    const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+                    await deps.stopAuto(ctx, pi, blockerMsg);
+                    ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+                    deps.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 deps.stopAuto(ctx, pi, `No active milestone — ${incomplete.length} incomplete (${ids}), see diagnostic above`);
+                }
+                debugLog("autoLoop", { phase: "exit", reason: "no-active-milestone" });
+                break;
+            }
+            if (!midTitle) {
+                midTitle = mid;
+                ctx.ui.notify(`Milestone ${mid} has no title in roadmap — using ID as fallback.`, "warning");
+            }
+            // Mid-merge safety check
+            if (deps.reconcileMergeState(s.basePath, ctx)) {
+                deps.invalidateAllCaches();
+                state = await deps.deriveState(s.basePath);
+                mid = state.activeMilestone?.id;
+                midTitle = state.activeMilestone?.title;
+            }
+            if (!mid || !midTitle) {
+                if (s.currentUnit) {
+                    await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+                }
+                const noMilestoneReason = !mid
+                    ? "No active milestone after merge reconciliation"
+                    : `Milestone ${mid} has no title after reconciliation`;
+                await deps.stopAuto(ctx, pi, noMilestoneReason);
+                debugLog("autoLoop", {
+                    phase: "exit",
+                    reason: "no-milestone-after-reconciliation",
+                });
+                break;
+            }
+            // Terminal: complete
+            if (state.phase === "complete") {
+                if (s.currentUnit) {
+                    await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+                }
+                // Milestone merge on complete
+                if (s.currentMilestoneId) {
+                    deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                }
+                deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
+                await deps.stopAuto(ctx, pi, `Milestone ${mid} complete`);
+                debugLog("autoLoop", { phase: "exit", reason: "milestone-complete" });
+                break;
+            }
+            // Terminal: blocked
+            if (state.phase === "blocked") {
+                if (s.currentUnit) {
+                    await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+                }
+                const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
+                await deps.stopAuto(ctx, pi, blockerMsg);
+                ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
+                deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
+                debugLog("autoLoop", { phase: "exit", reason: "blocked" });
+                break;
+            }
+            // ── Phase 2: Guards ─────────────────────────────────────────────────
+            const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
+            // Budget ceiling guard
+            const budgetCeiling = prefs?.budget_ceiling;
+            if (budgetCeiling !== undefined && budgetCeiling > 0) {
+                const currentLedger = deps.getLedger();
+                const totalCost = currentLedger
+                    ? deps.getProjectTotals(currentLedger.units).cost
+                    : 0;
+                const budgetPct = totalCost / budgetCeiling;
+                const budgetAlertLevel = deps.getBudgetAlertLevel(budgetPct);
+                const newBudgetAlertLevel = deps.getNewBudgetAlertLevel(s.lastBudgetAlertLevel, budgetPct);
+                const enforcement = prefs?.budget_enforcement ?? "pause";
+                const budgetEnforcementAction = deps.getBudgetEnforcementAction(enforcement, budgetPct);
+                if (newBudgetAlertLevel === 100 && budgetEnforcementAction !== "none") {
+                    const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
+                    s.lastBudgetAlertLevel =
+                        newBudgetAlertLevel;
+                    if (budgetEnforcementAction === "halt") {
+                        deps.sendDesktopNotification("GSD", msg, "error", "budget");
+                        await deps.stopAuto(ctx, pi, "Budget ceiling reached");
+                        debugLog("autoLoop", { phase: "exit", reason: "budget-halt" });
+                        break;
+                    }
+                    if (budgetEnforcementAction === "pause") {
+                        ctx.ui.notify(`${msg} Pausing auto-mode — /gsd auto to override and continue.`, "warning");
+                        deps.sendDesktopNotification("GSD", msg, "warning", "budget");
+                        await deps.pauseAuto(ctx, pi);
+                        debugLog("autoLoop", { phase: "exit", reason: "budget-pause" });
+                        break;
+                    }
+                    ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
+                    deps.sendDesktopNotification("GSD", msg, "warning", "budget");
+                }
+                else if (newBudgetAlertLevel === 90) {
+                    s.lastBudgetAlertLevel =
+                        newBudgetAlertLevel;
+                    ctx.ui.notify(`Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
+                    deps.sendDesktopNotification("GSD", `Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning", "budget");
+                }
+                else if (newBudgetAlertLevel === 80) {
+                    s.lastBudgetAlertLevel =
+                        newBudgetAlertLevel;
+                    ctx.ui.notify(`Approaching budget ceiling — 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
+                    deps.sendDesktopNotification("GSD", `Approaching budget ceiling — 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning", "budget");
+                }
+                else if (newBudgetAlertLevel === 75) {
+                    s.lastBudgetAlertLevel =
+                        newBudgetAlertLevel;
+                    ctx.ui.notify(`Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "info");
+                    deps.sendDesktopNotification("GSD", `Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "info", "budget");
+                }
+                else if (budgetAlertLevel === 0) {
+                    s.lastBudgetAlertLevel = 0;
+                }
+            }
+            else {
+                s.lastBudgetAlertLevel = 0;
+            }
+            // Context window guard
+            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");
+                    deps.sendDesktopNotification("GSD", `Context ${contextUsage.percent}% — paused`, "warning", "attention");
+                    await deps.pauseAuto(ctx, pi);
+                    debugLog("autoLoop", { phase: "exit", reason: "context-window" });
+                    break;
+                }
+            }
+            // Secrets re-check gate
+            try {
+                const manifestStatus = await deps.getManifestStatus(s.basePath, mid);
+                if (manifestStatus && manifestStatus.pending.length > 0) {
+                    const result = await deps.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: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`, "warning");
+            }
+            // ── Phase 3: Dispatch resolution ────────────────────────────────────
+            debugLog("autoLoop", { phase: "dispatch-resolve", iteration });
+            const dispatchResult = await deps.resolveDispatch({
+                basePath: s.basePath,
+                mid,
+                midTitle: midTitle,
+                state,
+                prefs,
+            });
+            if (dispatchResult.action === "stop") {
+                if (s.currentUnit) {
+                    await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+                }
+                await deps.stopAuto(ctx, pi, dispatchResult.reason);
+                debugLog("autoLoop", { phase: "exit", reason: "dispatch-stop" });
+                break;
+            }
+            if (dispatchResult.action !== "dispatch") {
+                // Non-dispatch action (e.g. "skip") — re-derive state
+                await new Promise((r) => setImmediate(r));
+                continue;
+            }
+            let unitType = dispatchResult.unitType;
+            let unitId = dispatchResult.unitId;
+            let prompt = dispatchResult.prompt;
+            const pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
+            // ── Same-unit stuck counter with graduated recovery ──
+            const derivedKey = `${unitType}/${unitId}`;
+            if (derivedKey === lastDerivedUnit && !s.pendingVerificationRetry) {
+                sameUnitCount++;
+                debugLog("autoLoop", {
+                    phase: "stuck-check",
+                    unitType,
+                    unitId,
+                    sameUnitCount,
+                });
+                if (sameUnitCount === 3) {
+                    // Level 1: try verifying the artifact — maybe it was written but not detected
+                    const artifactExists = deps.verifyExpectedArtifact(unitType, unitId, s.basePath);
+                    if (artifactExists) {
+                        debugLog("autoLoop", {
+                            phase: "stuck-recovery",
+                            level: 1,
+                            action: "artifact-found",
+                        });
+                        ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
+                        deps.invalidateAllCaches();
+                        continue;
+                    }
+                    ctx.ui.notify(`Stuck on ${unitType} ${unitId} (attempt ${sameUnitCount}). Invalidating caches and retrying.`, "warning");
+                    deps.invalidateAllCaches();
+                }
+                else if (sameUnitCount === 5) {
+                    // Level 2: hard stop — genuinely stuck
+                    debugLog("autoLoop", {
+                        phase: "stuck-detected",
+                        unitType,
+                        unitId,
+                        sameUnitCount,
+                    });
+                    await deps.stopAuto(ctx, pi, `Stuck: ${unitType} ${unitId} derived ${sameUnitCount} consecutive times without progress`);
+                    ctx.ui.notify(`Stuck on ${unitType} ${unitId} — deriveState returns the same unit after ${sameUnitCount} attempts. The expected artifact was not written.`, "error");
+                    break;
+                }
+            }
+            else {
+                if (derivedKey !== lastDerivedUnit) {
+                    debugLog("autoLoop", {
+                        phase: "stuck-counter-reset",
+                        from: lastDerivedUnit,
+                        to: derivedKey,
+                    });
+                }
+                lastDerivedUnit = derivedKey;
+                sameUnitCount = 0;
+            }
+            // Pre-dispatch hooks
+            const preDispatchResult = deps.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");
+                await new Promise((r) => setImmediate(r));
+                continue;
+            }
+            if (preDispatchResult.action === "replace") {
+                prompt = preDispatchResult.prompt ?? prompt;
+                if (preDispatchResult.unitType)
+                    unitType = preDispatchResult.unitType;
+            }
+            else if (preDispatchResult.prompt) {
+                prompt = preDispatchResult.prompt;
+            }
+            const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(s.basePath, deps.getMainBranch(s.basePath), unitType, unitId);
+            if (priorSliceBlocker) {
+                await deps.stopAuto(ctx, pi, priorSliceBlocker);
+                debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
+                break;
+            }
+            const observabilityIssues = await deps.collectObservabilityWarnings(ctx, s.basePath, unitType, unitId);
+            // ── Phase 4: Unit execution ─────────────────────────────────────────
+            debugLog("autoLoop", {
+                phase: "unit-execution",
+                iteration,
+                unitType,
+                unitId,
+            });
+            // Closeout previous unit
+            if (s.currentUnit) {
+                await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+                if (s.currentUnitRouting) {
+                    const isRetry = s.currentUnit.type === unitType && s.currentUnit.id === unitId;
+                    deps.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 ||
+                    deps.verifyExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
+                if (closeoutKey !== incomingKey && artifactVerified) {
+                    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);
+                    }
+                    deps.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() };
+            deps.captureAvailableSkills();
+            deps.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)
+                deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
+            deps.updateProgressWidget(ctx, unitType, unitId, state);
+            deps.ensurePreconditions(unitType, unitId, s.basePath, state);
+            // 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 = deps.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 = deps.buildObservabilityRepairBlock(observabilityIssues);
+            if (repairBlock) {
+                finalPrompt = `${finalPrompt}${repairBlock}`;
+            }
+            // Prompt char measurement
+            s.lastPromptCharCount = finalPrompt.length;
+            s.lastBaselineCharCount = undefined;
+            if (deps.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 {
+                finalPrompt = deps.reorderForCaching(finalPrompt);
+            }
+            catch (reorderErr) {
+                const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
+                process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
+            }
+            // Select and apply model
+            const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel);
+            s.currentUnitRouting =
+                modelResult.routing;
+            // Start unit supervision
+            deps.clearUnitTimeout();
+            deps.startUnitSupervision({
+                s,
+                ctx,
+                pi,
+                unitType,
+                unitId,
+                prefs,
+                buildSnapshotOpts: () => deps.buildSnapshotOpts(unitType, unitId),
+                buildRecoveryContext: () => ({}),
+                pauseAuto: deps.pauseAuto,
+            });
+            // Session + send + await
+            const sessionFile = deps.getSessionFile(ctx);
+            deps.updateSessionLock(deps.lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
+            deps.writeLock(deps.lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
+            debugLog("autoLoop", {
+                phase: "runUnit-start",
+                iteration,
+                unitType,
+                unitId,
+            });
+            const unitResult = await runUnit(ctx, pi, s, unitType, unitId, finalPrompt, prefs);
+            debugLog("autoLoop", {
+                phase: "runUnit-end",
+                iteration,
+                unitType,
+                unitId,
+                status: unitResult.status,
+            });
+            if (unitResult.status === "cancelled") {
+                ctx.ui.notify(`Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`, "warning");
+                await deps.stopAuto(ctx, pi, "Session creation failed");
+                debugLog("autoLoop", { phase: "exit", reason: "session-failed" });
+                break;
+            }
+            // ── Phase 5: Finalize ───────────────────────────────────────────────
+            debugLog("autoLoop", { phase: "finalize", iteration });
+            // Clear unit timeout (unit completed)
+            deps.clearUnitTimeout();
+            // Post-unit context for pre/post verification
+            const postUnitCtx = {
+                s,
+                ctx,
+                pi,
+                buildSnapshotOpts: deps.buildSnapshotOpts,
+                lockBase: deps.lockBase,
+                stopAuto: deps.stopAuto,
+                pauseAuto: deps.pauseAuto,
+                updateProgressWidget: deps.updateProgressWidget,
+            };
+            // Pre-verification processing (commit, doctor, state rebuild, etc.)
+            const preResult = await deps.postUnitPreVerification(postUnitCtx);
+            if (preResult === "dispatched") {
+                debugLog("autoLoop", {
+                    phase: "exit",
+                    reason: "pre-verification-dispatched",
+                });
+                break;
+            }
+            if (pauseAfterUatDispatch) {
+                ctx.ui.notify("UAT requires human execution. Auto-mode will pause after this unit writes the result file.", "info");
+                await deps.pauseAuto(ctx, pi);
+                debugLog("autoLoop", { phase: "exit", reason: "uat-pause" });
+                break;
+            }
+            // Verification gate — the loop handles retries via s.pendingVerificationRetry
+            const verificationResult = await deps.runPostUnitVerification({ s, ctx, pi }, deps.pauseAuto);
+            if (verificationResult === "pause") {
+                debugLog("autoLoop", { phase: "exit", reason: "verification-pause" });
+                break;
+            }
+            if (verificationResult === "retry") {
+                // s.pendingVerificationRetry was set by runPostUnitVerification.
+                // Continue the loop — next iteration will inject the retry context into the prompt.
+                debugLog("autoLoop", { phase: "verification-retry", iteration });
+                continue;
+            }
+            // Post-verification processing (DB dual-write, hooks, triage, quick-tasks)
+            const postResult = await deps.postUnitPostVerification(postUnitCtx);
+            if (postResult === "stopped") {
+                debugLog("autoLoop", {
+                    phase: "exit",
+                    reason: "post-verification-stopped",
+                });
+                break;
+            }
+            if (postResult === "step-wizard") {
+                // Step mode — exit the loop (caller handles wizard)
+                debugLog("autoLoop", { phase: "exit", reason: "step-wizard" });
+                break;
+            }
+            // ── Sidecar drain: dispatch enqueued hooks/triage/quick-tasks ──
+            let sidecarBroke = false;
+            while (s.sidecarQueue.length > 0 && s.active) {
+                const item = s.sidecarQueue.shift();
+                debugLog("autoLoop", {
+                    phase: "sidecar-dequeue",
+                    kind: item.kind,
+                    unitType: item.unitType,
+                    unitId: item.unitId,
+                });
+                // Set up as current unit
+                const sidecarStartedAt = Date.now();
+                s.currentUnit = {
+                    type: item.unitType,
+                    id: item.unitId,
+                    startedAt: sidecarStartedAt,
+                };
+                deps.writeUnitRuntimeRecord(s.basePath, item.unitType, item.unitId, sidecarStartedAt, {
+                    phase: "dispatched",
+                    wrapupWarningSent: false,
+                    timeoutAt: null,
+                    lastProgressAt: sidecarStartedAt,
+                    progressCount: 0,
+                    lastProgressKind: "dispatch",
+                });
+                // Model selection (handles hook model override)
+                await deps.selectAndApplyModel(ctx, pi, item.unitType, item.unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel);
+                // Supervision
+                deps.clearUnitTimeout();
+                deps.startUnitSupervision({
+                    s,
+                    ctx,
+                    pi,
+                    unitType: item.unitType,
+                    unitId: item.unitId,
+                    prefs,
+                    buildSnapshotOpts: () => deps.buildSnapshotOpts(item.unitType, item.unitId),
+                    buildRecoveryContext: () => ({}),
+                    pauseAuto: deps.pauseAuto,
+                });
+                // Write lock
+                const sidecarSessionFile = deps.getSessionFile(ctx);
+                deps.writeLock(deps.lockBase(), item.unitType, item.unitId, s.completedUnits.length, sidecarSessionFile);
+                // Execute via standard runUnit
+                const sidecarResult = await runUnit(ctx, pi, s, item.unitType, item.unitId, item.prompt, prefs);
+                deps.clearUnitTimeout();
+                if (sidecarResult.status === "cancelled") {
+                    ctx.ui.notify(`Sidecar unit ${item.unitType} ${item.unitId} session cancelled. Stopping.`, "warning");
+                    await deps.stopAuto(ctx, pi, "Sidecar session creation failed");
+                    sidecarBroke = true;
+                    break;
+                }
+                // Run pre-verification for the sidecar unit
+                const sidecarPreResult = await deps.postUnitPreVerification(postUnitCtx);
+                if (sidecarPreResult === "dispatched") {
+                    // Pre-verification caused stop/pause
+                    debugLog("autoLoop", {
+                        phase: "exit",
+                        reason: "sidecar-pre-verification-stop",
+                    });
+                    sidecarBroke = true;
+                    break;
+                }
+                // Verification gate for non-hook sidecar units (triage, quick-tasks)
+                // Hook units are lightweight and don't need verification.
+                if (item.kind !== "hook") {
+                    const sidecarVerification = await deps.runPostUnitVerification({ s, ctx, pi }, deps.pauseAuto);
+                    if (sidecarVerification === "pause") {
+                        debugLog("autoLoop", {
+                            phase: "exit",
+                            reason: "sidecar-verification-pause",
+                        });
+                        sidecarBroke = true;
+                        break;
+                    }
+                    // "retry" for sidecars — skip retry, just continue (sidecar retries are not worth the complexity)
+                }
+                // Post-verification (may enqueue more sidecar items)
+                const sidecarPostResult = await deps.postUnitPostVerification(postUnitCtx);
+                if (sidecarPostResult === "stopped") {
+                    debugLog("autoLoop", { phase: "exit", reason: "sidecar-stopped" });
+                    sidecarBroke = true;
+                    break;
+                }
+                if (sidecarPostResult === "step-wizard") {
+                    debugLog("autoLoop", {
+                        phase: "exit",
+                        reason: "sidecar-step-wizard",
+                    });
+                    sidecarBroke = true;
+                    break;
+                }
+                // "continue" — loop checks sidecarQueue again
+            }
+            if (sidecarBroke)
+                break;
+            consecutiveErrors = 0; // Iteration completed successfully
+            debugLog("autoLoop", { phase: "iteration-complete", iteration });
+        }
+        catch (loopErr) {
+            // ── Blanket catch: absorb unexpected exceptions, apply graduated recovery ──
+            consecutiveErrors++;
+            const msg = loopErr instanceof Error ? loopErr.message : String(loopErr);
+            debugLog("autoLoop", {
+                phase: "iteration-error",
+                iteration,
+                consecutiveErrors,
+                error: msg,
+            });
+            if (consecutiveErrors >= 3) {
+                // 3+ consecutive: hard stop — something is fundamentally broken
+                ctx.ui.notify(`Auto-mode stopped: ${consecutiveErrors} consecutive iteration failures. Last: ${msg}`, "error");
+                await deps.stopAuto(ctx, pi, `${consecutiveErrors} consecutive iteration failures`);
+                break;
+            }
+            else if (consecutiveErrors === 2) {
+                // 2nd consecutive: try invalidating caches + re-deriving state
+                ctx.ui.notify(`Iteration error (attempt ${consecutiveErrors}): ${msg}. Invalidating caches and retrying.`, "warning");
+                deps.invalidateAllCaches();
+            }
+            else {
+                // 1st error: log and retry — transient failures happen
+                ctx.ui.notify(`Iteration error: ${msg}. Retrying.`, "warning");
+            }
+        }
+    }
+    _activeSession = null;
+    debugLog("autoLoop", { phase: "exit", totalIterations: iteration });
+}