gsd-pi 2.38.0-dev.eeb3520 → 2.39.0-dev.64cd3ed

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

@@ -5,12 +5,16 @@
  * 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.
+ * MAINTENANCE RULE: Module-level mutable state is limited to `_currentResolve`
+ * (per-unit one-shot resolver) and `_sessionSwitchInFlight` (guard for
+ * session rotation). No queue — stale agent_end events are dropped.
  */
+import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { NEW_SESSION_TIMEOUT_MS } from "./auto/session.js";
 import { debugLog } from "./debug-logger.js";
+import { gsdRoot } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { join } from "node:path";
 /**
  * Maximum total loop iterations before forced stop. Prevents runaway loops
  * when units alternate IDs (bypassing the same-unit stuck detector).
@@ -18,71 +22,114 @@ import { debugLog } from "./debug-logger.js";
  * generous headroom including retries and sidecar work.
  */
 const MAX_LOOP_ITERATIONS = 500;
-// ─── Session-scoped promise state ───────────────────────────────────────────
+/** Maximum characters of failure/crash context included in recovery prompts. */
+const MAX_RECOVERY_CHARS = 50_000;
+/** Data-driven budget threshold notifications (descending). The 100% entry
+ *  triggers special enforcement logic (halt/pause/warn); sub-100 entries fire
+ *  a simple notification. */
+const BUDGET_THRESHOLDS = [
+    { pct: 100, label: "Budget ceiling reached", notifyLevel: "error", cmuxLevel: "error" },
+    { pct: 90, label: "Budget 90%", notifyLevel: "warning", cmuxLevel: "warning" },
+    { pct: 80, label: "Approaching budget ceiling — 80%", notifyLevel: "warning", cmuxLevel: "warning" },
+    { pct: 75, label: "Budget 75%", notifyLevel: "info", cmuxLevel: "progress" },
+];
+// ─── Per-unit one-shot 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;
+// A single module-level resolve function scoped to the current unit execution.
+// No queue — if an agent_end arrives with no pending resolver, it is dropped
+// (logged as warning). This is simpler and safer than the previous session-
+// scoped pendingResolve + pendingAgentEndQueue pattern.
+let _currentResolve = null;
+let _sessionSwitchInFlight = false;
 // ─── 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.
+ * If no resolver exists (event arrived between loop iterations or during
+ * session switch), the event is dropped with a debug warning.
  */
 export function resolveAgentEnd(event) {
-    const s = _activeSession;
-    if (!s) {
-        debugLog("resolveAgentEnd", {
-            status: "no-active-session",
-            warning: "agent_end with no active loop session",
-        });
+    if (_sessionSwitchInFlight) {
+        debugLog("resolveAgentEnd", { status: "ignored-during-switch" });
         return;
     }
-    if (s.pendingResolve) {
+    if (_currentResolve) {
         debugLog("resolveAgentEnd", { status: "resolving", hasEvent: true });
-        const r = s.pendingResolve;
-        s.pendingResolve = null;
+        const r = _currentResolve;
+        _currentResolve = 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",
+            status: "no-pending-resolve",
+            warning: "agent_end with no pending unit",
         });
-        s.pendingAgentEndQueue.push(event);
     }
 }
 export function isSessionSwitchInFlight() {
-    return _activeSession?.sessionSwitchInFlight ?? false;
+    return _sessionSwitchInFlight;
 }
 // ─── resetPendingResolve (test helper) ───────────────────────────────────────
 /**
- * Reset session promise state. Only exported for test cleanup — production code
- * should never call this.
+ * Reset module-level 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;
+    _currentResolve = null;
+    _sessionSwitchInFlight = false;
+}
+/**
+ * No-op for backward compatibility with tests that previously set the
+ * active session. The module no longer holds a session reference.
+ */
+export function _setActiveSession(_session) {
+    // No-op — kept for test backward compatibility
 }
 /**
- * Set the active session for resolveAgentEnd. Only exported for test setup —
- * production code sets this via autoLoop entry.
+ * Analyze a sliding window of recent unit dispatches for stuck patterns.
+ * Returns a signal with reason if stuck, null otherwise.
+ *
+ * Rule 1: Same error string twice in a row → stuck immediately.
+ * Rule 2: Same unit key 3+ consecutive times → stuck (preserves prior behavior).
+ * Rule 3: Oscillation A→B→A→B in last 4 entries → stuck.
  */
-export function _setActiveSession(session) {
-    _activeSession = session;
+export function detectStuck(window) {
+    if (window.length < 2)
+        return null;
+    const last = window[window.length - 1];
+    const prev = window[window.length - 2];
+    // Rule 1: Same error repeated consecutively
+    if (last.error && prev.error && last.error === prev.error) {
+        return {
+            stuck: true,
+            reason: `Same error repeated: ${last.error.slice(0, 200)}`,
+        };
+    }
+    // Rule 2: Same unit 3+ consecutive times
+    if (window.length >= 3) {
+        const lastThree = window.slice(-3);
+        if (lastThree.every((u) => u.key === last.key)) {
+            return {
+                stuck: true,
+                reason: `${last.key} derived 3 consecutive times without progress`,
+            };
+        }
+    }
+    // Rule 3: Oscillation (A→B→A→B in last 4)
+    if (window.length >= 4) {
+        const w = window.slice(-4);
+        if (w[0].key === w[2].key &&
+            w[1].key === w[3].key &&
+            w[0].key !== w[1].key) {
+            return {
+                stuck: true,
+                reason: `Oscillation detected: ${w[0].key} ↔ ${w[1].key}`,
+            };
+        }
+    }
+    return null;
 }
 // ─── runUnit ─────────────────────────────────────────────────────────────────
 /**
@@ -93,41 +140,16 @@ export function _setActiveSession(session) {
  * On session creation failure or timeout, returns { status: 'cancelled' }
  * without awaiting the promise.
  */
-export async function runUnit(ctx, pi, s, unitType, unitId, prompt, _prefs) {
+export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
     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;
+    _sessionSwitchInFlight = true;
     try {
         const sessionPromise = s.cmdCtx.newSession().finally(() => {
-            s.sessionSwitchInFlight = false;
+            _sessionSwitchInFlight = false;
         });
         const timeoutPromise = new Promise((resolve) => {
             sessionTimeoutHandle = setTimeout(() => resolve({ cancelled: true }), NEW_SESSION_TIMEOUT_MS);
@@ -155,11 +177,12 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt, _prefs) {
     if (!s.active) {
         return { status: "cancelled" };
     }
-    // ── Create the agent_end promise (session-scoped) ──
+    // ── Create the agent_end promise (per-unit one-shot) ──
     // This happens after newSession completes so session-switch agent_end events
     // from the previous session cannot resolve the new unit.
+    _sessionSwitchInFlight = false;
     const unitPromise = new Promise((resolve) => {
-        s.pendingResolve = resolve;
+        _currentResolve = resolve;
     });
     // Ensure cwd matches basePath before dispatch (#1389).
     // async_bash and background jobs can drift cwd away from the worktree.
@@ -182,8 +205,76 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt, _prefs) {
         unitId,
         status: result.status,
     });
+    // Discard trailing follow-up messages (e.g. async_job_result notifications)
+    // from the completed unit. Without this, queued follow-ups trigger wasteful
+    // LLM turns before the next session can start (#1642).
+    // clearQueue() lives on AgentSession but isn't part of the typed
+    // ExtensionCommandContext interface — call it via runtime check.
+    try {
+        const cmdCtxAny = s.cmdCtx;
+        if (typeof cmdCtxAny?.clearQueue === "function") {
+            cmdCtxAny.clearQueue();
+        }
+    }
+    catch {
+        // Non-fatal — clearQueue may not be available in all contexts
+    }
     return result;
 }
+// ─── generateMilestoneReport ──────────────────────────────────────────────────
+/**
+ * Generate and write an HTML milestone report snapshot.
+ * Extracted from the milestone-transition block in autoLoop.
+ */
+async function generateMilestoneReport(s, ctx, milestoneId) {
+    const { loadVisualizerData } = await importExtensionModule(import.meta.url, "./visualizer-data.js");
+    const { generateHtmlReport } = await importExtensionModule(import.meta.url, "./export-html.js");
+    const { writeReportSnapshot } = await importExtensionModule(import.meta.url, "./reports.js");
+    const { basename } = await import("node:path");
+    const snapData = await loadVisualizerData(s.basePath);
+    const completedMs = snapData.milestones.find((m) => m.id === milestoneId);
+    const msTitle = completedMs?.title ?? milestoneId;
+    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,
+            indexRelPath: "index.html",
+        }),
+        milestoneId,
+        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");
+}
+// ─── closeoutAndStop ──────────────────────────────────────────────────────────
+/**
+ * If a unit is in-flight, close it out, then stop auto-mode.
+ * Extracted from ~4 identical if-closeout-then-stop sequences in autoLoop.
+ */
+async function closeoutAndStop(ctx, pi, s, deps, reason) {
+    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, reason);
+}
 // ─── autoLoop ────────────────────────────────────────────────────────────────
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
@@ -195,10 +286,11 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt, _prefs) {
  */
 export async function autoLoop(ctx, pi, s, deps) {
     debugLog("autoLoop", { phase: "enter" });
-    _activeSession = s;
     let iteration = 0;
-    let lastDerivedUnit = "";
-    let sameUnitCount = 0;
+    // ── Sliding-window stuck detection ──
+    const recentUnits = [];
+    const STUCK_WINDOW_SIZE = 6;
+    let stuckRecoveryAttempts = 0;
     let consecutiveErrors = 0;
     while (s.active) {
         iteration++;
@@ -218,6 +310,18 @@ export async function autoLoop(ctx, pi, s, deps) {
         }
         try {
             // ── Blanket try/catch: one bad iteration must not kill the session
+            const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
+            // ── Check sidecar queue before deriveState ──
+            let sidecarItem;
+            if (s.sidecarQueue.length > 0) {
+                sidecarItem = s.sidecarQueue.shift();
+                debugLog("autoLoop", {
+                    phase: "sidecar-dequeue",
+                    kind: sidecarItem.kind,
+                    unitType: sidecarItem.unitType,
+                    unitId: sidecarItem.unitId,
+                });
+            }
             const sessionLockBase = deps.lockBase();
             if (sessionLockBase) {
                 const lockStatus = deps.validateSessionLock(sessionLockBase);
@@ -237,419 +341,436 @@ export async function autoLoop(ctx, pi, s, deps) {
                     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" });
+            // Variables shared between the sidecar and normal paths
+            let unitType;
+            let unitId;
+            let prompt;
+            let pauseAfterUatDispatch = false;
+            let state;
+            let mid;
+            let midTitle;
+            let observabilityIssues = [];
+            if (!sidecarItem) {
+                // ── 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;
                 }
-            }
-            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);
-            deps.syncCmuxSidebar(deps.loadEffectiveGSDPreferences()?.preferences, state);
-            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");
-                deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}.`, "success");
-                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");
+                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");
                     }
-                    catch (err) {
-                        ctx.ui.notify(`Report generation failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+                    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;
                     }
                 }
-                // 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();
+                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
                 state = await deps.deriveState(s.basePath);
+                deps.syncCmuxSidebar(prefs, state);
                 mid = state.activeMilestone?.id;
                 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");
+                    deps.logCmuxEvent(prefs, `Milestone ${s.currentMilestoneId} complete. Advancing to ${mid}.`, "success");
+                    const vizPrefs = prefs;
+                    if (vizPrefs?.auto_visualize) {
+                        ctx.ui.notify("Run /gsd visualize to see progress overview.", "info");
+                    }
+                    if (vizPrefs?.auto_report !== false) {
+                        try {
+                            await generateMilestoneReport(s, ctx, s.currentMilestoneId);
+                        }
+                        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();
+                    recentUnits.length = 0;
+                    stuckRecoveryAttempts = 0;
+                    // Worktree lifecycle on milestone transition — merge current, enter next
+                    deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                    // Opt-in: create draft PR on milestone completion
+                    if (prefs?.git?.auto_pr) {
+                        try {
+                            const { createDraftPR } = await import("./git-service.js");
+                            const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
+                            if (prUrl) {
+                                ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
+                            }
+                        }
+                        catch {
+                            // Non-fatal — PR creation is best-effort
+                        }
+                    }
+                    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: prefs?.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) {
-                    if (deps.getIsolationMode() !== "none") {
-                        deps.captureIntegrationBranch(s.basePath, mid, {
-                            commitDocs: deps.loadEffectiveGSDPreferences()?.preferences?.git
-                                ?.commit_docs,
-                        });
+                    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));
                     }
-                    deps.resolver.enterMilestone(mid, ctx.ui);
+                    const incomplete = state.registry.filter((m) => m.status !== "complete" && m.status !== "parked");
+                    if (incomplete.length === 0 && state.registry.length > 0) {
+                        // All milestones complete — merge milestone branch before stopping
+                        if (s.currentMilestoneId) {
+                            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                            // Opt-in: create draft PR on milestone completion
+                            if (prefs?.git?.auto_pr) {
+                                try {
+                                    const { createDraftPR } = await import("./git-service.js");
+                                    const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
+                                    if (prUrl) {
+                                        ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
+                                    }
+                                }
+                                catch {
+                                    // Non-fatal — PR creation is best-effort
+                                }
+                            }
+                        }
+                        deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
+                        deps.logCmuxEvent(prefs, "All milestones complete.", "success");
+                        await deps.stopAuto(ctx, pi, "All milestones complete");
+                    }
+                    else if (incomplete.length === 0 && state.registry.length === 0) {
+                        // Empty registry — no milestones visible, likely a path resolution bug
+                        const diag = `basePath=${s.basePath}, phase=${state.phase}`;
+                        ctx.ui.notify(`No milestones visible in current scope. Possible path resolution issue.\n   Diagnostic: ${diag}`, "error");
+                        await deps.stopAuto(ctx, pi, `No milestones found — check basePath resolution`);
+                    }
+                    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");
+                        deps.logCmuxEvent(prefs, blockerMsg, "error");
+                    }
+                    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;
                 }
-                else {
-                    // mid is undefined — no milestone to capture integration branch for
+                if (!midTitle) {
+                    midTitle = mid;
+                    ctx.ui.notify(`Milestone ${mid} has no title in roadmap — using ID as fallback.`, "warning");
                 }
-                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
+                // 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) {
+                    const noMilestoneReason = !mid
+                        ? "No active milestone after merge reconciliation"
+                        : `Milestone ${mid} has no title after reconciliation`;
+                    await closeoutAndStop(ctx, pi, s, deps, noMilestoneReason);
+                    debugLog("autoLoop", {
+                        phase: "exit",
+                        reason: "no-milestone-after-reconciliation",
+                    });
+                    break;
+                }
+                // Terminal: complete
+                if (state.phase === "complete") {
+                    // Milestone merge on complete (before closeout so branch state is clean)
                     if (s.currentMilestoneId) {
                         deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                        // Opt-in: create draft PR on milestone completion
+                        if (prefs?.git?.auto_pr) {
+                            try {
+                                const { createDraftPR } = await import("./git-service.js");
+                                const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
+                                if (prUrl) {
+                                    ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
+                                }
+                            }
+                            catch {
+                                // Non-fatal — PR creation is best-effort
+                            }
+                        }
                     }
-                    deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
-                    deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, "All milestones complete.", "success");
-                    await deps.stopAuto(ctx, pi, "All milestones complete");
+                    deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
+                    deps.logCmuxEvent(prefs, `Milestone ${mid} complete.`, "success");
+                    await closeoutAndStop(ctx, pi, s, deps, `Milestone ${mid} complete`);
+                    debugLog("autoLoop", { phase: "exit", reason: "milestone-complete" });
+                    break;
                 }
-                else if (state.phase === "blocked") {
+                // Terminal: blocked
+                if (state.phase === "blocked") {
                     const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-                    await deps.stopAuto(ctx, pi, blockerMsg);
+                    await closeoutAndStop(ctx, pi, s, deps, blockerMsg);
                     ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
                     deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention");
-                    deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, blockerMsg, "error");
-                }
-                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`);
+                    deps.logCmuxEvent(prefs, blockerMsg, "error");
+                    debugLog("autoLoop", { phase: "exit", reason: "blocked" });
+                    break;
                 }
-                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));
+                // ── Phase 2: Guards ─────────────────────────────────────────────────
+                // 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);
+                    // Data-driven threshold check — loop descending, fire first match
+                    const threshold = BUDGET_THRESHOLDS.find((t) => newBudgetAlertLevel >= t.pct);
+                    if (threshold) {
+                        s.lastBudgetAlertLevel =
+                            newBudgetAlertLevel;
+                        if (threshold.pct === 100 && budgetEnforcementAction !== "none") {
+                            // 100% — special enforcement logic (halt/pause/warn)
+                            const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`;
+                            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");
+                                deps.logCmuxEvent(prefs, msg, "warning");
+                                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");
+                            deps.logCmuxEvent(prefs, msg, "warning");
+                        }
+                        else if (threshold.pct < 100) {
+                            // Sub-100% — simple notification
+                            const msg = `${threshold.label}: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`;
+                            ctx.ui.notify(msg, threshold.notifyLevel);
+                            deps.sendDesktopNotification("GSD", msg, threshold.notifyLevel, "budget");
+                            deps.logCmuxEvent(prefs, msg, threshold.cmuxLevel);
+                        }
+                    }
+                    else if (budgetAlertLevel === 0) {
+                        s.lastBudgetAlertLevel = 0;
+                    }
                 }
-                // Milestone merge on complete
-                if (s.currentMilestoneId) {
-                    deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                else {
+                    s.lastBudgetAlertLevel = 0;
                 }
-                deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
-                deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, `Milestone ${mid} complete.`, "success");
-                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");
-                deps.logCmuxEvent(deps.loadEffectiveGSDPreferences()?.preferences, blockerMsg, "error");
-                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");
-                        deps.logCmuxEvent(prefs, msg, "warning");
+                // 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: "budget-pause" });
+                        debugLog("autoLoop", { phase: "exit", reason: "context-window" });
                         break;
                     }
-                    ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning");
-                    deps.sendDesktopNotification("GSD", msg, "warning", "budget");
-                    deps.logCmuxEvent(prefs, msg, "warning");
-                }
-                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");
-                    deps.logCmuxEvent(prefs, `Budget 90%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
-                }
-                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");
-                    deps.logCmuxEvent(prefs, `Budget 80%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "warning");
-                }
-                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");
-                    deps.logCmuxEvent(prefs, `Budget 75%: ${deps.formatCost(totalCost)} / ${deps.formatCost(budgetCeiling)}`, "progress");
-                }
-                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, s.originalBasePath);
-                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");
+                // Secrets re-check gate
+                try {
+                    const manifestStatus = await deps.getManifestStatus(s.basePath, mid, s.originalBasePath);
+                    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));
+                catch (err) {
+                    ctx.ui.notify(`Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`, "warning");
                 }
-                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,
+                // ── Phase 3: Dispatch resolution ────────────────────────────────────
+                debugLog("autoLoop", { phase: "dispatch-resolve", iteration });
+                const dispatchResult = await deps.resolveDispatch({
+                    basePath: s.basePath,
+                    mid,
+                    midTitle: midTitle,
+                    state,
+                    prefs,
+                    session: s,
                 });
-                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) {
+                if (dispatchResult.action === "stop") {
+                    await closeoutAndStop(ctx, pi, s, deps, 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;
+                }
+                unitType = dispatchResult.unitType;
+                unitId = dispatchResult.unitId;
+                prompt = dispatchResult.prompt;
+                pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
+                // ── Sliding-window stuck detection with graduated recovery ──
+                const derivedKey = `${unitType}/${unitId}`;
+                if (!s.pendingVerificationRetry) {
+                    recentUnits.push({ key: derivedKey });
+                    if (recentUnits.length > STUCK_WINDOW_SIZE)
+                        recentUnits.shift();
+                    const stuckSignal = detectStuck(recentUnits);
+                    if (stuckSignal) {
                         debugLog("autoLoop", {
-                            phase: "stuck-recovery",
-                            level: 1,
-                            action: "artifact-found",
+                            phase: "stuck-check",
+                            unitType,
+                            unitId,
+                            reason: stuckSignal.reason,
+                            recoveryAttempts: stuckRecoveryAttempts,
                         });
-                        ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
-                        deps.invalidateAllCaches();
-                        continue;
+                        if (stuckRecoveryAttempts === 0) {
+                            // Level 1: try verifying the artifact, then cache invalidation + retry
+                            stuckRecoveryAttempts++;
+                            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} (${stuckSignal.reason}). Invalidating caches and retrying.`, "warning");
+                            deps.invalidateAllCaches();
+                        }
+                        else {
+                            // Level 2: hard stop — genuinely stuck
+                            debugLog("autoLoop", {
+                                phase: "stuck-detected",
+                                unitType,
+                                unitId,
+                                reason: stuckSignal.reason,
+                            });
+                            await deps.stopAuto(ctx, pi, `Stuck: ${stuckSignal.reason}`);
+                            ctx.ui.notify(`Stuck on ${unitType} ${unitId} — ${stuckSignal.reason}. The expected artifact was not written.`, "error");
+                            break;
+                        }
+                    }
+                    else {
+                        // Progress detected — reset recovery counter
+                        if (stuckRecoveryAttempts > 0) {
+                            debugLog("autoLoop", {
+                                phase: "stuck-counter-reset",
+                                from: recentUnits[recentUnits.length - 2]?.key ?? "",
+                                to: derivedKey,
+                            });
+                            stuckRecoveryAttempts = 0;
+                        }
                     }
-                    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");
+                // 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;
                 }
+                observabilityIssues = await deps.collectObservabilityWarnings(ctx, s.basePath, unitType, unitId);
+                // Derive state for shared use in execution phase
+                // (state, mid, midTitle already set above)
             }
             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;
+                // ── Sidecar path: use values from the sidecar item directly ──
+                unitType = sidecarItem.unitType;
+                unitId = sidecarItem.unitId;
+                prompt = sidecarItem.prompt;
+                // Derive minimal state for progress widget / execution context
+                state = await deps.deriveState(s.basePath);
+                mid = state.activeMilestone?.id;
+                midTitle = state.activeMilestone?.title;
             }
-            const observabilityIssues = await deps.collectObservabilityWarnings(ctx, s.basePath, unitType, unitId);
             // ── Phase 4: Unit execution ─────────────────────────────────────────
             debugLog("autoLoop", {
                 phase: "unit-execution",
@@ -662,33 +783,6 @@ export async function autoLoop(ctx, pi, s, deps) {
                 s.currentUnit.type === unitType &&
                 s.currentUnit.id === unitId);
             const previousTier = s.currentUnitRouting?.tier;
-            // 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, {
@@ -706,7 +800,6 @@ export async function autoLoop(ctx, pi, s, deps) {
             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;
@@ -744,7 +837,7 @@ export async function autoLoop(ctx, pi, s, deps) {
             s.lastBaselineCharCount = undefined;
             if (deps.isDbAvailable()) {
                 try {
-                    const { inlineGsdRootFile } = await import("./auto-prompts.js");
+                    const { inlineGsdRootFile } = await importExtensionModule(import.meta.url, "./auto-prompts.js");
                     const [decisionsContent, requirementsContent, projectContent] = await Promise.all([
                         inlineGsdRootFile(s.basePath, "decisions.md", "Decisions"),
                         inlineGsdRootFile(s.basePath, "requirements.md", "Requirements"),
@@ -767,8 +860,8 @@ export async function autoLoop(ctx, pi, s, deps) {
                 const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
                 process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
             }
-            // Select and apply model (with tier escalation on retry)
-            const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, { isRetry, previousTier });
+            // Select and apply model (with tier escalation on retry — normal units only)
+            const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, sidecarItem ? undefined : { isRetry, previousTier });
             s.currentUnitRouting =
                 modelResult.routing;
             // Start unit supervision
@@ -794,7 +887,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                 unitType,
                 unitId,
             });
-            const unitResult = await runUnit(ctx, pi, s, unitType, unitId, finalPrompt, prefs);
+            const unitResult = await runUnit(ctx, pi, s, unitType, unitId, finalPrompt);
             debugLog("autoLoop", {
                 phase: "runUnit-end",
                 iteration,
@@ -802,12 +895,60 @@ export async function autoLoop(ctx, pi, s, deps) {
                 unitId,
                 status: unitResult.status,
             });
+            // Tag the most recent window entry with error info for stuck detection
+            if (unitResult.status === "error" || unitResult.status === "cancelled") {
+                const lastEntry = recentUnits[recentUnits.length - 1];
+                if (lastEntry) {
+                    lastEntry.error = `${unitResult.status}:${unitType}/${unitId}`;
+                }
+            }
+            else if (unitResult.event?.messages?.length) {
+                const lastMsg = unitResult.event.messages[unitResult.event.messages.length - 1];
+                const msgStr = typeof lastMsg === "string" ? lastMsg : JSON.stringify(lastMsg);
+                if (/error|fail|exception/i.test(msgStr)) {
+                    const lastEntry = recentUnits[recentUnits.length - 1];
+                    if (lastEntry) {
+                        lastEntry.error = msgStr.slice(0, 200);
+                    }
+                }
+            }
             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;
             }
+            // ── Immediate unit closeout (metrics, activity log, memory) ────────
+            // Run right after runUnit() returns so telemetry is never lost to a
+            // crash between iterations.
+            await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));
+            if (s.currentUnitRouting) {
+                deps.recordOutcome(unitType, s.currentUnitRouting.tier, true);
+            }
+            const isHookUnit = unitType.startsWith("hook/");
+            const artifactVerified = isHookUnit ||
+                deps.verifyExpectedArtifact(unitType, unitId, s.basePath);
+            if (artifactVerified) {
+                s.completedUnits.push({
+                    type: unitType,
+                    id: unitId,
+                    startedAt: s.currentUnit.startedAt,
+                    finishedAt: Date.now(),
+                });
+                if (s.completedUnits.length > 200) {
+                    s.completedUnits = s.completedUnits.slice(-200);
+                }
+                // Flush completed-units to disk so the record survives crashes
+                try {
+                    const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
+                    const keys = s.completedUnits.map((u) => `${u.type}/${u.id}`);
+                    atomicWriteSync(completedKeysPath, JSON.stringify(keys, null, 2));
+                }
+                catch { /* non-fatal: disk flush failure */ }
+                deps.clearUnitRuntimeRecord(s.basePath, unitType, unitId);
+                s.unitDispatchCount.delete(`${unitType}/${unitId}`);
+                s.unitRecoveryCount.delete(`${unitType}/${unitId}`);
+            }
             // ── Phase 5: Finalize ───────────────────────────────────────────────
             debugLog("autoLoop", { phase: "finalize", iteration });
             // Clear unit timeout (unit completed)
@@ -824,7 +965,13 @@ export async function autoLoop(ctx, pi, s, deps) {
                 updateProgressWidget: deps.updateProgressWidget,
             };
             // Pre-verification processing (commit, doctor, state rebuild, etc.)
-            const preResult = await deps.postUnitPreVerification(postUnitCtx);
+            // Sidecar items use lightweight pre-verification opts
+            const preVerificationOpts = sidecarItem
+                ? sidecarItem.kind === "hook"
+                    ? { skipSettleDelay: true, skipDoctor: true, skipStateRebuild: true, skipWorktreeSync: true }
+                    : { skipSettleDelay: true, skipStateRebuild: true }
+                : undefined;
+            const preResult = await deps.postUnitPreVerification(postUnitCtx, preVerificationOpts);
             if (preResult === "dispatched") {
                 debugLog("autoLoop", {
                     phase: "exit",
@@ -838,17 +985,28 @@ export async function autoLoop(ctx, pi, s, deps) {
                 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;
+            // Verification gate
+            // Hook sidecar items skip verification entirely.
+            // Non-hook sidecar items run verification but skip retries (just continue).
+            const skipVerification = sidecarItem?.kind === "hook";
+            if (!skipVerification) {
+                const verificationResult = await deps.runPostUnitVerification({ s, ctx, pi }, deps.pauseAuto);
+                if (verificationResult === "pause") {
+                    debugLog("autoLoop", { phase: "exit", reason: "verification-pause" });
+                    break;
+                }
+                if (verificationResult === "retry") {
+                    if (sidecarItem) {
+                        // Sidecar verification retries are skipped — just continue
+                        debugLog("autoLoop", { phase: "sidecar-verification-retry-skipped", iteration });
+                    }
+                    else {
+                        // 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);
@@ -864,102 +1022,6 @@ export async function autoLoop(ctx, pi, s, deps) {
                 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 });
         }
@@ -990,6 +1052,6 @@ export async function autoLoop(ctx, pi, s, deps) {
             }
         }
     }
-    _activeSession = null;
+    _currentResolve = null;
     debugLog("autoLoop", { phase: "exit", totalIterations: iteration });
 }