gsd-pi 2.80.0 → 2.81.0

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

@@ -9,24 +9,41 @@
 import { randomUUID } from "node:crypto";
 import { MAX_LOOP_ITERATIONS, } from "./types.js";
 import { _clearCurrentResolve } from "./resolve.js";
-import { runPreDispatch, runDispatch, runGuards, runUnitPhase, runFinalize, } from "./phases.js";
+import { runPreDispatch, runDispatch, runGuards, runFinalize, } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
 import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { ModelPolicyDispatchBlockedError } from "../auto-model-selection.js";
 import { resolveEngine } from "../engine-resolver.js";
 import { logWarning } from "../workflow-logger.js";
-import { gsdRoot } from "../paths.js";
-import { heartbeatAutoWorker } from "../db/auto-workers.js";
 import { recordDispatchClaim, markRunning as markDispatchRunning, markCompleted as markDispatchCompleted, markFailed as markDispatchFailed, getRecentForUnit as getRecentDispatchesForUnit, getRecentUnitKeysForProjectRoot, } from "../db/unit-dispatches.js";
-import { refreshMilestoneLease } from "../db/milestone-leases.js";
+import { claimMilestoneLease, refreshMilestoneLease } from "../db/milestone-leases.js";
+import { heartbeatAutoWorker } from "../db/auto-workers.js";
 import { getRuntimeKv, setRuntimeKv } from "../db/runtime-kv.js";
-import { atomicWriteSync } from "../atomic-write.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { scheduleSidecarQueue } from "../uok/execution-graph.js";
-import { ExecutionGraphScheduler } from "../uok/execution-graph.js";
-import { readFileSync, mkdirSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
 import { normalizeRealPath } from "../paths.js";
+import { decideCooldownRecovery, decideDispatchClaim, decideEngineDispatch, decideFinalizeResult, decideInfrastructureError, decideIterationErrorRecovery, decideMemoryPressure, decideModelPolicyBlocked, decideMinRequestInterval, decideWorkflowLoop, formatDispatchExceptionSummary, formatUnhandledDispatchErrorSummary, resolveUnitRequestTimestamp, shouldUseCustomEnginePath, } from "./workflow-kernel.js";
+import { hydrateCustomVerifyRetryCounts, saveCustomVerifyRetryCounts, } from "./custom-verify-retry-store.js";
+import { settleDispatchCompleted, settleDispatchFailed, } from "./workflow-dispatch-ledger.js";
+import { emitOpenUnitEndForUnit } from "../crash-recovery.js";
+import { writeUnitRuntimeRecord } from "../unit-runtime.js";
+import { ensureDispatchLease, openDispatchClaim } from "./workflow-dispatch-claim.js";
+import { completeWorkflowIteration } from "./workflow-iteration-completion.js";
+import { createWorkflowJournalReporter } from "./workflow-journal-reporter.js";
+import { createWorkflowPhaseReporter } from "./workflow-phase-reporter.js";
+import { createWorkflowTurnReporter } from "./workflow-turn-reporter.js";
+import { validateWorkflowSessionLock } from "./workflow-session-lock.js";
+import { dequeueSidecarItem } from "./workflow-sidecar-queue.js";
+import { maintainWorkerHeartbeat } from "./workflow-worker-heartbeat.js";
+import { measureMemoryPressure } from "./workflow-memory-pressure.js";
+import { buildSidecarIterationData } from "./workflow-sidecar-iteration.js";
+import { createExecutionGraphUnitDispatchDeps, runUnitPhaseViaContract, } from "./workflow-unit-dispatch.js";
+import { handleCustomEngineDispatchOutcome } from "./workflow-custom-engine-dispatch-outcome.js";
+import { buildCustomEngineIterationData } from "./workflow-custom-engine-iteration.js";
+import { handleCustomEngineVerifyRetry } from "./workflow-custom-engine-retry.js";
+import { handleCustomEngineVerifyPause, handleCustomEngineVerifyRetryOutcome, } from "./workflow-custom-engine-verify-outcome.js";
+import { handleCustomEngineReconcile } from "./workflow-custom-engine-reconcile.js";
+import { handleCustomEngineReconcileOutcome } from "./workflow-custom-engine-reconcile-outcome.js";
 // ── Stuck detection persistence (#3704) ──────────────────────────────────
 // Phase C migration: stuck-state.json deleted in favor of DB-backed
 // equivalents. recentUnits is rebuilt from unit_dispatches (Phase B
@@ -70,199 +87,83 @@ function saveStuckState(s, state) {
         debugLog("autoLoop", { phase: "save-stuck-state-failed", error: err instanceof Error ? err.message : String(err) });
     }
 }
-// ── Custom workflow verification retry persistence ───────────────────────
-// Custom workflows can request verification retries after a step runs. The
-// retry budget must survive an auto-mode restart or a failing verifier can
-// consume a fresh retry budget every session.
-function customVerifyRetryStateDir(s) {
-    return s.activeRunDir ? join(s.activeRunDir, "runtime") : join(gsdRoot(s.basePath), "runtime");
+function logDispatchLedgerWriteFailure(err) {
+    debugLog("autoLoop", {
+        phase: "dispatch-ledger-write-failed",
+        error: err instanceof Error ? err.message : String(err),
+    });
 }
-function customVerifyRetryStatePath(s) {
-    return join(customVerifyRetryStateDir(s), "custom-verify-retries.json");
+function logDispatchClaimRejected(details) {
+    debugLog("autoLoop", {
+        phase: "dispatch-claim-rejected",
+        ...details,
+    });
 }
-function hydrateCustomVerifyRetryCounts(s) {
-    if (s.verificationRetryCount.size > 0) {
-        return s.verificationRetryCount;
-    }
-    try {
-        const raw = JSON.parse(readFileSync(customVerifyRetryStatePath(s), "utf-8"));
-        const counts = raw && typeof raw === "object" && raw.counts && typeof raw.counts === "object"
-            ? raw.counts
-            : {};
-        for (const [key, value] of Object.entries(counts)) {
-            if (typeof value === "number" && Number.isFinite(value) && value > 0) {
-                s.verificationRetryCount.set(key, Math.floor(value));
-            }
-        }
-    }
-    catch (err) {
-        debugLog("autoLoop", { phase: "load-custom-verify-retries-failed", error: err instanceof Error ? err.message : String(err) });
-    }
-    return s.verificationRetryCount;
+function logDispatchClaimFailed(err) {
+    debugLog("autoLoop", {
+        phase: "dispatch-claim-failed",
+        error: err instanceof Error ? err.message : String(err),
+    });
 }
-function saveCustomVerifyRetryCounts(s) {
-    const retryCounts = s.verificationRetryCount;
-    const filePath = customVerifyRetryStatePath(s);
-    try {
-        if (!retryCounts || retryCounts.size === 0) {
-            unlinkSync(filePath);
-            return;
-        }
-        mkdirSync(customVerifyRetryStateDir(s), { recursive: true });
-        atomicWriteSync(filePath, JSON.stringify({
-            counts: Object.fromEntries(retryCounts),
-            updatedAt: new Date().toISOString(),
-        }) + "\n");
-    }
-    catch (err) {
-        const code = err && typeof err === "object" && "code" in err ? err.code : undefined;
-        if (code !== "ENOENT") {
-            debugLog("autoLoop", { phase: "save-custom-verify-retries-failed", error: err instanceof Error ? err.message : String(err) });
-        }
-    }
+function logDispatchLeaseRecovered(details) {
+    debugLog("autoLoop", {
+        phase: details.recovered ? "dispatch-lease-recovered" : "dispatch-lease-acquired",
+        ...details,
+    });
 }
-function openDispatchClaim(s, flowId, turnId, iterData) {
-    if (!s.workerId || s.milestoneLeaseToken === null)
-        return { kind: "degraded" };
-    const mid = iterData.mid;
-    if (!mid)
-        return { kind: "degraded" };
-    const recent = getRecentDispatchesForUnit(iterData.unitId, 1);
-    const attemptN = (recent[0]?.attempt_n ?? 0) + 1;
-    let claim;
-    try {
-        claim = recordDispatchClaim({
-            traceId: flowId,
-            turnId,
-            workerId: s.workerId,
-            milestoneLeaseToken: s.milestoneLeaseToken,
-            milestoneId: mid,
-            sliceId: iterData.state.activeSlice?.id ?? null,
-            taskId: iterData.state.activeTask?.id ?? null,
-            unitType: iterData.unitType,
-            unitId: iterData.unitId,
-            attemptN,
-        });
-        if (!claim.ok) {
-            debugLog("autoLoop", {
-                phase: "dispatch-claim-rejected",
-                unitId: iterData.unitId,
-                reason: claim.error,
-                existingId: "existingId" in claim ? claim.existingId : undefined,
-                existingWorker: "existingWorker" in claim ? claim.existingWorker : undefined,
-            });
-            if (claim.error === "already_active") {
-                return {
-                    kind: "skip",
-                    reason: "already-active",
-                    existingId: claim.existingId,
-                    existingWorker: claim.existingWorker,
-                };
-            }
-            return { kind: "skip", reason: "stale-lease" };
-        }
-        markDispatchRunning(claim.dispatchId);
-        return { kind: "opened", dispatchId: claim.dispatchId };
-    }
-    catch (err) {
-        debugLog("autoLoop", {
-            phase: "dispatch-claim-failed",
-            error: err instanceof Error ? err.message : String(err),
-        });
-        return { kind: "degraded" };
-    }
+function logDispatchLeaseRecoveryFailed(details) {
+    debugLog("autoLoop", {
+        phase: "dispatch-lease-recovery-failed",
+        ...details,
+    });
+}
+function logCustomVerifyRetryLoadFailure(err) {
+    debugLog("autoLoop", {
+        phase: "load-custom-verify-retries-failed",
+        error: err instanceof Error ? err.message : String(err),
+    });
+}
+function logCustomVerifyRetrySaveFailure(err) {
+    debugLog("autoLoop", {
+        phase: "save-custom-verify-retries-failed",
+        error: err instanceof Error ? err.message : String(err),
+    });
 }
 // ── Memory pressure monitoring (#3331) ──────────────────────────────────
 // Check heap usage every N iterations and trigger graceful shutdown before
 // the OS OOM killer sends SIGKILL. The threshold is 90% of the V8 heap
 // limit (--max-old-space-size or default ~1.5-4GB depending on platform).
 const MEMORY_CHECK_INTERVAL = 5; // check every 5 iterations
-const MEMORY_PRESSURE_THRESHOLD = 0.85; // 85% of heap limit
 const MAX_CUSTOM_ENGINE_VERIFY_RETRIES = 3;
-function checkMemoryPressure() {
-    const mem = process.memoryUsage();
-    // v8.getHeapStatistics() gives heap_size_limit but requires import
-    // Use a conservative estimate: RSS > 3GB is danger zone on most systems
-    const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
-    const rssMB = Math.round(mem.rss / 1024 / 1024);
-    // Try to get the actual V8 heap limit
-    let limitMB = 4096; // conservative default
-    try {
-        const v8 = require("node:v8");
-        const stats = v8.getHeapStatistics();
-        limitMB = Math.round(stats.heap_size_limit / 1024 / 1024);
-    }
-    catch {
-        limitMB = 4096; /* v8 stats unavailable — use conservative default */
-    }
-    const pct = heapMB / limitMB;
-    return { pressured: pct > MEMORY_PRESSURE_THRESHOLD, heapMB, limitMB, pct };
-}
-function resolveDispatchNodeKind(unitType, sidecarItem) {
-    if (sidecarItem?.kind === "hook")
-        return "hook";
-    if (sidecarItem?.kind === "triage")
-        return "verification";
-    if (sidecarItem?.kind === "quick-task")
-        return "team-worker";
-    if (unitType.startsWith("hook/"))
-        return "hook";
-    if (unitType === "reactive-execute")
-        return "subagent";
-    if (unitType === "gate-evaluate"
-        || unitType === "validate-milestone"
-        || unitType === "run-uat"
-        || unitType === "complete-slice") {
-        return "verification";
-    }
-    if (unitType === "replan-slice" || unitType === "reassess-roadmap") {
-        return "reprocess";
-    }
-    return "unit";
-}
 async function enforceMinRequestInterval(s, prefs) {
     const minInterval = prefs?.min_request_interval_ms ?? 0;
-    if (minInterval > 0 && s.lastRequestTimestamp > 0) {
-        const elapsed = Date.now() - s.lastRequestTimestamp;
-        if (elapsed < minInterval) {
-            const waitMs = minInterval - elapsed;
-            debugLog("autoLoop", { phase: "rate-limit-wait", waitMs });
-            await new Promise(r => setTimeout(r, waitMs));
-        }
+    const decision = decideMinRequestInterval({
+        minIntervalMs: minInterval,
+        lastRequestTimestamp: s.lastRequestTimestamp,
+        nowMs: Date.now(),
+    });
+    if (decision.action === "wait") {
+        debugLog("autoLoop", { phase: "rate-limit-wait", waitMs: decision.waitMs });
+        await new Promise(r => setTimeout(r, decision.waitMs));
     }
 }
-async function runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem) {
-    if (dispatchContract === "legacy-direct") {
-        return runUnitPhase(ic, iterData, loopState, sidecarItem);
+function closeOutCrashedUnit(s, iterData, err) {
+    const summary = formatDispatchExceptionSummary({ error: err });
+    try {
+        emitOpenUnitEndForUnit(s.basePath, iterData.unitType, iterData.unitId, "cancelled", {
+            message: summary,
+            category: "unit-exception",
+            isTransient: false,
+        });
+        writeUnitRuntimeRecord(s.basePath, iterData.unitType, iterData.unitId, s.currentUnit?.startedAt ?? Date.now(), {
+            phase: "crashed",
+            lastProgressAt: Date.now(),
+            lastProgressKind: "unit-exception",
+        });
+    }
+    catch (closeoutErr) {
+        logWarning("dispatch", `unit crash closeout failed: ${closeoutErr instanceof Error ? closeoutErr.message : String(closeoutErr)}`);
     }
-    const scheduler = new ExecutionGraphScheduler();
-    let outcome = null;
-    const executeNode = async () => {
-        outcome = await runUnitPhase(ic, iterData, loopState, sidecarItem);
-    };
-    const kinds = [
-        "unit",
-        "hook",
-        "subagent",
-        "team-worker",
-        "verification",
-        "reprocess",
-    ];
-    for (const kind of kinds)
-        scheduler.registerHandler(kind, executeNode);
-    const nodeId = `dispatch:${ic.iteration}:${iterData.unitType}:${iterData.unitId}`;
-    await scheduler.run([
-        {
-            id: nodeId,
-            kind: resolveDispatchNodeKind(iterData.unitType, sidecarItem),
-            dependsOn: [],
-            metadata: {
-                unitType: iterData.unitType,
-                unitId: iterData.unitId,
-            },
-        },
-    ], { parallel: false, maxWorkers: 1 });
-    return outcome ?? { action: "break", reason: "scheduler-dispatch-missing-result" };
 }
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
@@ -276,6 +177,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
     debugLog("autoLoop", { phase: "enter" });
     let iteration = 0;
     const dispatchContract = options?.dispatchContract ?? "legacy-direct";
+    const unitDispatchDeps = createExecutionGraphUnitDispatchDeps();
     // Load persisted stuck state so counters survive session restarts (#3704)
     const persisted = loadStuckState(s);
     const loopState = {
@@ -289,65 +191,69 @@ export async function autoLoop(ctx, pi, s, deps, options) {
     while (s.active) {
         iteration++;
         debugLog("autoLoop", { phase: "loop-top", iteration });
-        // Phase B: heartbeat the worker registry + active milestone lease so
-        // janitors and concurrent workers see a live process. Best-effort —
-        // DB unavailability or stale state must not stop the loop.
-        if (s.workerId) {
-            try {
-                heartbeatAutoWorker(s.workerId);
-                if (s.currentMilestoneId && s.milestoneLeaseToken) {
-                    refreshMilestoneLease(s.workerId, s.currentMilestoneId, s.milestoneLeaseToken);
-                }
-            }
-            catch (err) {
-                debugLog("autoLoop", {
-                    phase: "heartbeat-failed",
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
+        maintainWorkerHeartbeat(s, {
+            heartbeatAutoWorker,
+            refreshMilestoneLease,
+            logHeartbeatFailure: err => debugLog("autoLoop", {
+                phase: "heartbeat-failed",
+                error: err instanceof Error ? err.message : String(err),
+            }),
+            logLeaseRefreshMiss: details => debugLog("autoLoop", {
+                phase: "lease-refresh-missed",
+                ...details,
+            }),
+        });
         // ── Journal: per-iteration flow grouping ──
         const flowId = randomUUID();
         let seqCounter = 0;
         const nextSeq = () => ++seqCounter;
+        const journalReporter = createWorkflowJournalReporter({
+            emitJournalEvent: deps.emitJournalEvent,
+            flowId,
+            nextSeq,
+        });
         const turnId = randomUUID();
         s.currentTraceId = flowId;
         s.currentTurnId = turnId;
         const turnStartedAt = new Date().toISOString();
         let observedUnitType;
         let observedUnitId;
-        let turnFinished = false;
+        const phaseReporter = createWorkflowPhaseReporter({
+            observer: deps.uokObserver,
+        });
+        const turnReporter = createWorkflowTurnReporter({
+            observer: deps.uokObserver,
+            traceId: flowId,
+            turnId,
+            iteration,
+            basePath: s.basePath,
+            startedAt: turnStartedAt,
+            clearCurrentTurn: () => {
+                s.currentTraceId = null;
+                s.currentTurnId = null;
+            },
+        });
         const finishTurn = (status, failureClass = "none", error) => {
-            if (turnFinished)
-                return;
-            turnFinished = true;
-            deps.uokObserver?.onTurnResult({
-                traceId: flowId,
-                turnId,
-                iteration,
+            turnReporter.finish({
                 unitType: observedUnitType,
                 unitId: observedUnitId,
                 status,
                 failureClass,
-                phaseResults: [],
                 error,
-                startedAt: turnStartedAt,
-                finishedAt: new Date().toISOString(),
             });
-            s.currentTraceId = null;
-            s.currentTurnId = null;
         };
-        deps.uokObserver?.onTurnStart({
-            traceId: flowId,
-            turnId,
+        turnReporter.start();
+        const iterationDecision = decideWorkflowLoop({
+            active: s.active,
             iteration,
-            basePath: s.basePath,
-            startedAt: turnStartedAt,
+            maxIterations: MAX_LOOP_ITERATIONS,
+            hasCommandContext: true,
+            sessionLockValid: true,
         });
-        if (iteration > MAX_LOOP_ITERATIONS) {
+        if (iterationDecision.action === "stop" && iterationDecision.reason === "max-iterations") {
             debugLog("autoLoop", {
                 phase: "exit",
-                reason: "max-iterations",
+                reason: iterationDecision.reason,
                 iteration,
             });
             await deps.stopAuto(ctx, pi, `Safety: loop exceeded ${MAX_LOOP_ITERATIONS} iterations — possible runaway`);
@@ -357,69 +263,84 @@ export async function autoLoop(ctx, pi, s, deps, options) {
         // ── Memory pressure check (#3331) ──
         // Graceful shutdown before OOM killer sends SIGKILL.
         if (iteration % MEMORY_CHECK_INTERVAL === 0) {
-            const mem = checkMemoryPressure();
+            const mem = measureMemoryPressure();
             debugLog("autoLoop", { phase: "memory-check", ...mem });
-            if (mem.pressured) {
-                logWarning("dispatch", `Memory pressure: ${mem.heapMB}MB / ${mem.limitMB}MB (${Math.round(mem.pct * 100)}%) — stopping auto-mode to prevent OOM kill`);
-                await deps.stopAuto(ctx, pi, `Memory pressure: heap at ${mem.heapMB}MB / ${mem.limitMB}MB (${Math.round(mem.pct * 100)}%). ` +
-                    `Stopping gracefully to prevent OOM kill after ${iteration} iterations. ` +
-                    `Resume with /gsd auto to continue from where you left off.`);
-                finishTurn("stopped", "timeout", "memory-pressure");
+            const memoryDecision = decideMemoryPressure({ ...mem, iteration });
+            if (memoryDecision.action === "stop") {
+                logWarning("dispatch", memoryDecision.warningMessage);
+                await deps.stopAuto(ctx, pi, memoryDecision.stopMessage);
+                finishTurn("stopped", "timeout", memoryDecision.turnError);
                 break;
             }
         }
-        if (!s.cmdCtx) {
+        const commandContextDecision = decideWorkflowLoop({
+            active: s.active,
+            iteration,
+            maxIterations: MAX_LOOP_ITERATIONS,
+            hasCommandContext: Boolean(s.cmdCtx),
+            sessionLockValid: true,
+        });
+        if (commandContextDecision.action === "stop" && commandContextDecision.reason === "missing-command-context") {
             debugLog("autoLoop", { phase: "exit", reason: "no-cmdCtx" });
-            finishTurn("stopped", "manual-attention", "missing-command-context");
+            finishTurn("stopped", "manual-attention", commandContextDecision.reason);
             break;
         }
         let dispatchId = null;
         let dispatchSettled = false;
+        const completeIteration = () => {
+            completeWorkflowIteration({
+                get consecutiveErrors() { return consecutiveErrors; },
+                set consecutiveErrors(value) { consecutiveErrors = value; },
+                get consecutiveCooldowns() { return consecutiveCooldowns; },
+                set consecutiveCooldowns(value) { consecutiveCooldowns = value; },
+                recentErrorMessages,
+            }, {
+                emitIterationEnd: () => journalReporter.emit("iteration-end", { iteration }),
+                saveStuckState: () => saveStuckState(s, loopState),
+                logIterationComplete: () => debugLog("autoLoop", { phase: "iteration-complete", iteration }),
+            });
+        };
         try {
             // ── Blanket try/catch: one bad iteration must not kill the session
             const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
             const uokFlags = resolveUokFlags(prefs);
             // ── Check sidecar queue before deriveState ──
-            let sidecarItem;
-            if (s.sidecarQueue.length > 0) {
-                if (uokFlags.executionGraph && s.sidecarQueue.length > 1) {
-                    try {
-                        s.sidecarQueue = await scheduleSidecarQueue(s.sidecarQueue);
-                    }
-                    catch (err) {
-                        logWarning("dispatch", `sidecar queue scheduling failed: ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-                sidecarItem = s.sidecarQueue.shift();
-                debugLog("autoLoop", {
-                    phase: "sidecar-dequeue",
-                    kind: sidecarItem.kind,
-                    unitType: sidecarItem.unitType,
-                    unitId: sidecarItem.unitId,
-                });
-                deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "sidecar-dequeue", data: { kind: sidecarItem.kind, unitType: sidecarItem.unitType, unitId: sidecarItem.unitId } });
-            }
-            const sessionLockBase = deps.lockBase();
-            if (sessionLockBase) {
-                const lockStatus = deps.validateSessionLock(sessionLockBase);
-                if (!lockStatus.valid) {
-                    debugLog("autoLoop", {
+            // NOTE: Sidecar dequeue MUST run before validateWorkflowSessionLock so a
+            // queued item is popped (and the `sidecar-dequeue` journal event emitted)
+            // even when the session lock invalidates this iteration. Inverting this
+            // order silently drops queued items on lock-loss. Refs #5308.
+            const sidecarItem = await dequeueSidecarItem({
+                queue: s.sidecarQueue,
+                executionGraphEnabled: uokFlags.executionGraph,
+                scheduleQueue: scheduleSidecarQueue,
+                warnSchedulingFailure: message => logWarning("dispatch", `sidecar queue scheduling failed: ${message}`),
+                logDequeue: payload => debugLog("autoLoop", { phase: "sidecar-dequeue", ...payload }),
+                emitDequeue: payload => journalReporter.emit("sidecar-dequeue", payload),
+            });
+            const sessionLockOutcome = validateWorkflowSessionLock({
+                active: s.active,
+                iteration,
+                maxIterations: MAX_LOOP_ITERATIONS,
+                deps: {
+                    lockBase: deps.lockBase,
+                    validateSessionLock: deps.validateSessionLock,
+                    handleLostSessionLock: lockStatus => deps.handleLostSessionLock(ctx, lockStatus),
+                    logInvalidSessionLock: details => debugLog("autoLoop", {
                         phase: "session-lock-invalid",
-                        reason: lockStatus.failureReason ?? "unknown",
-                        existingPid: lockStatus.existingPid,
-                        expectedPid: lockStatus.expectedPid,
-                    });
-                    deps.handleLostSessionLock(ctx, lockStatus);
-                    debugLog("autoLoop", {
+                        ...details,
+                    }),
+                    logSessionLockExit: details => debugLog("autoLoop", {
                         phase: "exit",
-                        reason: "session-lock-lost",
-                        detail: lockStatus.failureReason ?? "unknown",
-                    });
-                    break;
-                }
+                        ...details,
+                    }),
+                },
+            });
+            if (sessionLockOutcome.action === "stop" && sessionLockOutcome.reason === "session-lock-lost") {
+                finishTurn("stopped", "manual-attention", sessionLockOutcome.reason);
+                break;
             }
             const ic = { ctx, pi, s, deps, prefs, iteration, flowId, nextSeq };
-            deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-start", data: { iteration } });
+            journalReporter.emit("iteration-start", { iteration });
             let iterData;
             // ── Custom engine path ──────────────────────────────────────────────
             // When activeEngineId is a non-dev value, bypass runPreDispatch and
@@ -429,7 +350,11 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             //
             // GSD_ENGINE_BYPASS=1 skips the engine layer entirely — falls through
             // to the dev path below.
-            if (s.activeEngineId != null && s.activeEngineId !== "dev" && !sidecarItem && process.env.GSD_ENGINE_BYPASS !== "1") {
+            if (shouldUseCustomEnginePath({
+                activeEngineId: s.activeEngineId,
+                hasSidecarItem: Boolean(sidecarItem),
+                engineBypass: process.env.GSD_ENGINE_BYPASS === "1",
+            })) {
                 debugLog("autoLoop", { phase: "custom-engine-derive", iteration, engineId: s.activeEngineId });
                 const { engine, policy } = resolveEngine({
                     activeEngineId: s.activeEngineId,
@@ -447,48 +372,53 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     isComplete: engineState.isComplete,
                 });
                 if (engineState.isComplete) {
+                    finishTurn("completed");
                     await deps.stopAuto(ctx, pi, "Workflow complete");
                     break;
                 }
                 debugLog("autoLoop", { phase: "custom-engine-dispatch", iteration });
                 const dispatch = await engine.resolveDispatch(engineState, { basePath: s.basePath });
-                if (dispatch.action === "stop") {
-                    await deps.stopAuto(ctx, pi, dispatch.reason ?? "Engine stopped");
+                const engineDispatchDecision = decideEngineDispatch(dispatch.action === "stop"
+                    ? { action: "stop", reason: dispatch.reason }
+                    : { action: dispatch.action });
+                const dispatchFlow = await handleCustomEngineDispatchOutcome({
+                    decision: engineDispatchDecision,
+                    deps: {
+                        stopAuto: reason => deps.stopAuto(ctx, pi, reason),
+                    },
+                });
+                if (dispatchFlow.action === "break") {
+                    finishTurn("stopped", "manual-attention", "custom-engine-dispatch-stop");
                     break;
                 }
-                if (dispatch.action === "skip") {
+                if (dispatchFlow.action === "continue") {
+                    finishTurn("skipped");
                     continue;
                 }
                 // dispatch.action === "dispatch"
+                if (dispatch.action !== "dispatch") {
+                    finishTurn("skipped");
+                    continue;
+                }
                 const step = dispatch.step;
-                const gsdState = await deps.deriveState(s.canonicalProjectRoot);
-                debugLog("autoLoop", {
-                    phase: "post-derive",
-                    site: "custom-engine-gsd-state",
+                iterData = await buildCustomEngineIterationData({
+                    step,
                     basePath: s.basePath,
                     canonicalProjectRoot: s.canonicalProjectRoot,
-                    derivedPhase: gsdState.phase,
-                    activeUnit: gsdState.activeTask?.id ?? gsdState.activeSlice?.id ?? gsdState.activeMilestone?.id,
+                    currentMilestoneId: s.currentMilestoneId,
+                    deriveState: deps.deriveState,
+                    logPostDerive: details => debugLog("autoLoop", {
+                        phase: "post-derive",
+                        ...details,
+                    }),
                 });
-                iterData = {
-                    unitType: step.unitType,
-                    unitId: step.unitId,
-                    prompt: step.prompt,
-                    finalPrompt: step.prompt,
-                    pauseAfterUatDispatch: false,
-                    state: gsdState,
-                    mid: s.currentMilestoneId ?? "workflow",
-                    midTitle: "Workflow",
-                    isRetry: false,
-                    previousTier: undefined,
-                };
                 observedUnitType = iterData.unitType;
                 observedUnitId = iterData.unitId;
                 // ── Progress widget (mirrors dev path in runDispatch) ──
                 deps.updateProgressWidget(ctx, iterData.unitType, iterData.unitId, iterData.state);
                 // ── Guards (shared with dev path) ──
                 const guardsResult = await runGuards(ic, s.currentMilestoneId ?? "workflow");
-                deps.uokObserver?.onPhaseResult("guard", guardsResult.action, {
+                phaseReporter.report("guard", guardsResult.action, {
                     unitType: iterData.unitType,
                     unitId: iterData.unitId,
                 });
@@ -498,13 +428,23 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 }
                 // ── Unit execution (shared with dev path) ──
                 await enforceMinRequestInterval(s, prefs);
-                const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState);
+                let unitPhaseResult;
+                try {
+                    unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, undefined, unitDispatchDeps);
+                }
+                catch (err) {
+                    if (err instanceof ModelPolicyDispatchBlockedError) {
+                        throw err;
+                    }
+                    closeOutCrashedUnit(s, iterData, err);
+                    throw err;
+                }
                 if (unitPhaseResult.action === "next") {
-                    const requestTimestamp = unitPhaseResult.data.requestDispatchedAt ?? unitPhaseResult.data.unitStartedAt;
-                    if (typeof requestTimestamp === "number")
+                    const requestTimestamp = resolveUnitRequestTimestamp(unitPhaseResult.data);
+                    if (requestTimestamp !== undefined)
                         s.lastRequestTimestamp = requestTimestamp;
                 }
-                deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
+                phaseReporter.report("unit", unitPhaseResult.action, {
                     unitType: iterData.unitType,
                     unitId: iterData.unitId,
                 });
@@ -516,103 +456,94 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 debugLog("autoLoop", { phase: "custom-engine-verify", iteration, unitId: iterData.unitId });
                 const verifyResult = await policy.verify(iterData.unitType, iterData.unitId, { basePath: s.basePath });
                 if (verifyResult === "pause") {
-                    await deps.pauseAuto(ctx, pi);
-                    deps.uokObserver?.onPhaseResult("custom-engine", "pause", {
+                    const verifyFlow = await handleCustomEngineVerifyPause({
                         unitType: iterData.unitType,
                         unitId: iterData.unitId,
+                        deps: {
+                            pauseAuto: () => deps.pauseAuto(ctx, pi),
+                            stopAuto: reason => deps.stopAuto(ctx, pi, reason),
+                            reportPause: details => phaseReporter.report("custom-engine", "pause", details),
+                            finishTurn,
+                        },
                     });
-                    finishTurn("paused", "manual-attention", "custom-engine-verify-pause");
-                    break;
+                    if (verifyFlow.action === "break")
+                        break;
                 }
                 if (verifyResult === "retry") {
-                    const recoveryKey = `${iterData.unitType}/${iterData.unitId}`;
-                    const retryCounts = hydrateCustomVerifyRetryCounts(s);
-                    const attempts = (retryCounts.get(recoveryKey) ?? 0) + 1;
-                    retryCounts.set(recoveryKey, attempts);
-                    saveCustomVerifyRetryCounts(s);
-                    debugLog("autoLoop", { phase: "custom-engine-verify-retry", iteration, unitId: iterData.unitId, attempts });
-                    deps.uokObserver?.onPhaseResult("custom-engine", "retry", {
+                    const retryOutcome = await handleCustomEngineVerifyRetry({
+                        session: s,
                         unitType: iterData.unitType,
                         unitId: iterData.unitId,
-                        attempts,
+                        basePath: s.basePath,
+                        iteration,
+                        maxRetries: MAX_CUSTOM_ENGINE_VERIFY_RETRIES,
+                        deps: {
+                            hydrateRetryCounts: () => hydrateCustomVerifyRetryCounts(s, {
+                                logFailure: logCustomVerifyRetryLoadFailure,
+                            }),
+                            saveRetryCounts: () => saveCustomVerifyRetryCounts(s, {
+                                logFailure: logCustomVerifyRetrySaveFailure,
+                            }),
+                            recover: (unitType, unitId, options) => policy.recover(unitType, unitId, options),
+                            logRetry: details => debugLog("autoLoop", {
+                                phase: "custom-engine-verify-retry",
+                                ...details,
+                            }),
+                            reportRetry: details => phaseReporter.report("custom-engine", "retry", details),
+                        },
+                    });
+                    const retryFlow = await handleCustomEngineVerifyRetryOutcome({
+                        outcome: retryOutcome,
+                        deps: {
+                            pauseAuto: () => deps.pauseAuto(ctx, pi),
+                            stopAuto: reason => deps.stopAuto(ctx, pi, reason),
+                            reportPause: details => phaseReporter.report("custom-engine", "pause", details),
+                            finishTurn,
+                        },
                     });
-                    if (attempts > MAX_CUSTOM_ENGINE_VERIFY_RETRIES) {
-                        const recovery = await policy.recover(iterData.unitType, iterData.unitId, { basePath: s.basePath });
-                        if (recovery.outcome === "pause") {
-                            await deps.pauseAuto(ctx, pi);
-                            finishTurn("paused", "manual-attention", recovery.reason ?? "custom-engine-verify-retry-exhausted");
-                            break;
-                        }
-                        if (recovery.outcome === "skip") {
-                            await deps.stopAuto(ctx, pi, recovery.reason ??
-                                `Custom workflow verification for ${iterData.unitId} requested skip after retry exhaustion, but the custom engine cannot reconcile skipped steps.`);
-                            finishTurn("stopped", "manual-attention", "custom-engine-verify-retry-exhausted");
-                            break;
-                        }
-                        const exhaustedReason = `Custom workflow verification for ${iterData.unitId} requested retry ${attempts} times without passing.`;
-                        await deps.stopAuto(ctx, pi, recovery.outcome === "stop" && recovery.reason ? recovery.reason : exhaustedReason);
-                        finishTurn("stopped", "manual-attention", "custom-engine-verify-retry-exhausted");
+                    if (retryFlow.action === "break")
                         break;
-                    }
-                    finishTurn("retry");
                     continue;
                 }
                 // Verification passed — mark step complete
-                s.verificationRetryCount?.delete(`${iterData.unitType}/${iterData.unitId}`);
-                saveCustomVerifyRetryCounts(s);
-                debugLog("autoLoop", { phase: "custom-engine-reconcile", iteration, unitId: iterData.unitId });
-                const reconcileResult = await engine.reconcile(engineState, {
-                    unitType: iterData.unitType,
-                    unitId: iterData.unitId,
-                    startedAt: s.currentUnit?.startedAt ?? Date.now(),
-                    finishedAt: Date.now(),
+                const reconcileOutcome = await handleCustomEngineReconcile({
+                    session: s,
+                    engineState,
+                    iterData,
+                    iteration,
+                    deps: {
+                        saveRetryCounts: () => saveCustomVerifyRetryCounts(s, {
+                            logFailure: logCustomVerifyRetrySaveFailure,
+                        }),
+                        logReconcile: details => debugLog("autoLoop", {
+                            phase: "custom-engine-reconcile",
+                            ...details,
+                        }),
+                        reconcile: (state, completedStep) => engine.reconcile(state, completedStep),
+                        now: () => Date.now(),
+                        clearUnitTimeout: deps.clearUnitTimeout,
+                        completeIteration,
+                    },
                 });
-                deps.clearUnitTimeout();
-                consecutiveErrors = 0;
-                consecutiveCooldowns = 0;
-                recentErrorMessages.length = 0;
-                deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
-                saveStuckState(s, loopState); // persist across session restarts (#3704)
-                debugLog("autoLoop", { phase: "iteration-complete", iteration });
-                if (reconcileResult.outcome === "milestone-complete") {
-                    await deps.stopAuto(ctx, pi, "Workflow complete");
-                    deps.uokObserver?.onPhaseResult("custom-engine", "milestone-complete", {
-                        unitType: iterData.unitType,
-                        unitId: iterData.unitId,
-                    });
-                    finishTurn("completed");
-                    break;
-                }
-                if (reconcileResult.outcome === "pause") {
-                    await deps.pauseAuto(ctx, pi);
-                    deps.uokObserver?.onPhaseResult("custom-engine", "pause", {
-                        unitType: iterData.unitType,
-                        unitId: iterData.unitId,
-                    });
-                    finishTurn("paused", "manual-attention");
-                    break;
-                }
-                if (reconcileResult.outcome === "stop") {
-                    await deps.stopAuto(ctx, pi, reconcileResult.reason ?? "Engine stopped");
-                    deps.uokObserver?.onPhaseResult("custom-engine", "stop", {
-                        unitType: iterData.unitType,
-                        unitId: iterData.unitId,
-                        reason: reconcileResult.reason,
-                    });
-                    finishTurn("stopped", "manual-attention", reconcileResult.reason);
-                    break;
-                }
-                deps.uokObserver?.onPhaseResult("custom-engine", "continue", {
+                const reconcileFlow = await handleCustomEngineReconcileOutcome({
+                    outcome: reconcileOutcome,
                     unitType: iterData.unitType,
                     unitId: iterData.unitId,
+                    deps: {
+                        stopAuto: reason => deps.stopAuto(ctx, pi, reason),
+                        pauseAuto: () => deps.pauseAuto(ctx, pi),
+                        report: (action, details) => phaseReporter.report("custom-engine", action, details),
+                        finishTurn,
+                    },
                 });
-                finishTurn("completed");
+                if (reconcileFlow.action === "break")
+                    break;
                 continue;
             }
             if (!sidecarItem) {
                 // ── Phase 1: Pre-dispatch ─────────────────────────────────────────
                 const preDispatchResult = await runPreDispatch(ic, loopState);
-                deps.uokObserver?.onPhaseResult("pre-dispatch", preDispatchResult.action);
+                phaseReporter.report("pre-dispatch", preDispatchResult.action);
                 if (preDispatchResult.action === "break") {
                     finishTurn("stopped", "manual-attention", "pre-dispatch-break");
                     break;
@@ -624,14 +555,14 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 const preData = preDispatchResult.data;
                 // ── Phase 2: Guards ───────────────────────────────────────────────
                 const guardsResult = await runGuards(ic, preData.mid);
-                deps.uokObserver?.onPhaseResult("guard", guardsResult.action);
+                phaseReporter.report("guard", guardsResult.action);
                 if (guardsResult.action === "break") {
                     finishTurn("stopped", "manual-attention", "guard-break");
                     break;
                 }
                 // ── Phase 3: Dispatch ─────────────────────────────────────────────
                 const dispatchResult = await runDispatch(ic, preData, loopState);
-                deps.uokObserver?.onPhaseResult("dispatch", dispatchResult.action);
+                phaseReporter.report("dispatch", dispatchResult.action);
                 if (dispatchResult.action === "break") {
                     finishTurn("stopped", "manual-attention", "dispatch-break");
                     break;
@@ -645,30 +576,19 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 observedUnitId = iterData.unitId;
             }
             else {
-                // ── Sidecar path: use values from the sidecar item directly ──
-                const sidecarState = await deps.deriveState(s.canonicalProjectRoot);
-                debugLog("autoLoop", {
-                    phase: "post-derive",
-                    site: "sidecar",
+                iterData = await buildSidecarIterationData({
+                    sidecarItem,
                     basePath: s.basePath,
                     canonicalProjectRoot: s.canonicalProjectRoot,
-                    derivedPhase: sidecarState.phase,
-                    activeUnit: sidecarState.activeTask?.id ?? sidecarState.activeSlice?.id ?? sidecarState.activeMilestone?.id,
+                    deriveState: deps.deriveState,
+                    logPostDerive: details => debugLog("autoLoop", {
+                        phase: "post-derive",
+                        ...details,
+                    }),
                 });
-                iterData = {
-                    unitType: sidecarItem.unitType,
-                    unitId: sidecarItem.unitId,
-                    prompt: sidecarItem.prompt,
-                    finalPrompt: sidecarItem.prompt,
-                    pauseAfterUatDispatch: false,
-                    state: sidecarState,
-                    mid: sidecarState.activeMilestone?.id,
-                    midTitle: sidecarState.activeMilestone?.title,
-                    isRetry: false, previousTier: undefined,
-                };
                 observedUnitType = iterData.unitType;
                 observedUnitId = iterData.unitId;
-                deps.uokObserver?.onPhaseResult("dispatch", "sidecar", {
+                phaseReporter.report("dispatch", "sidecar", {
                     unitType: iterData.unitType,
                     unitId: iterData.unitId,
                     sidecarKind: sidecarItem.kind,
@@ -677,56 +597,103 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             await enforceMinRequestInterval(s, prefs);
             // Phase B: claim a unit_dispatches row before invoking the unit. The
             // partial unique index idx_unit_dispatches_active_per_unit prevents
-            // a second worker from claiming the same unit concurrently. Returns
-            // null when DB unavailable, no worker registered, or no active lease
-            // — those degraded paths fall through to the existing single-worker
-            // semantics with no ledger entry, preserving back-compat.
-            const dispatchClaim = openDispatchClaim(s, flowId, turnId, iterData);
-            if (dispatchClaim.kind === "skip") {
-                finishTurn("skipped", "execution", dispatchClaim.reason);
+            // a second worker from claiming the same unit concurrently. When this
+            // process has a worker identity, make the milestone lease explicit before
+            // claiming so a step-mode handoff cannot leave us running with a stale
+            // in-memory token and no backing lease row.
+            const leaseBeforeClaim = ensureDispatchLease(s, iterData.mid, {
+                claimMilestoneLease,
+                logLeaseRecovered: logDispatchLeaseRecovered,
+                logLeaseRecoveryFailed: logDispatchLeaseRecoveryFailed,
+            });
+            if (leaseBeforeClaim.kind === "blocked" || leaseBeforeClaim.kind === "failed") {
+                const msg = `Lost milestone lease for ${iterData.mid ?? "unknown"} before dispatching ${iterData.unitType} ${iterData.unitId}: ${leaseBeforeClaim.reason}`;
+                ctx.ui.notify(msg, "error");
+                finishTurn("stopped", "execution", msg);
+                await deps.stopAuto(ctx, pi, msg);
+                break;
+            }
+            let dispatchClaim = openDispatchClaim(s, flowId, turnId, iterData, {
+                getRecentDispatchesForUnit,
+                recordDispatchClaim,
+                markDispatchRunning,
+                logClaimRejected: logDispatchClaimRejected,
+                logClaimFailed: logDispatchClaimFailed,
+            });
+            let dispatchDecision = decideDispatchClaim(dispatchClaim.kind === "opened"
+                ? { kind: "opened", dispatchId: dispatchClaim.dispatchId }
+                : dispatchClaim.kind === "skip"
+                    ? { kind: "skip", reason: dispatchClaim.reason }
+                    : { kind: "degraded" });
+            if (dispatchDecision.action === "skip" && dispatchDecision.reason === "stale-lease") {
+                const leaseRecovery = ensureDispatchLease(s, iterData.mid, {
+                    claimMilestoneLease,
+                    logLeaseRecovered: logDispatchLeaseRecovered,
+                    logLeaseRecoveryFailed: logDispatchLeaseRecoveryFailed,
+                }, { forceReclaim: true });
+                if (leaseRecovery.kind === "ready") {
+                    dispatchClaim = openDispatchClaim(s, flowId, turnId, iterData, {
+                        getRecentDispatchesForUnit,
+                        recordDispatchClaim,
+                        markDispatchRunning,
+                        logClaimRejected: logDispatchClaimRejected,
+                        logClaimFailed: logDispatchClaimFailed,
+                    });
+                    dispatchDecision = decideDispatchClaim(dispatchClaim.kind === "opened"
+                        ? { kind: "opened", dispatchId: dispatchClaim.dispatchId }
+                        : dispatchClaim.kind === "skip"
+                            ? { kind: "skip", reason: dispatchClaim.reason }
+                            : { kind: "degraded" });
+                }
+                else {
+                    const msg = `Lost milestone lease for ${iterData.mid ?? "unknown"} while claiming ${iterData.unitType} ${iterData.unitId}: ${leaseRecovery.reason}`;
+                    ctx.ui.notify(msg, "error");
+                    finishTurn("stopped", "execution", msg);
+                    await deps.stopAuto(ctx, pi, msg);
+                    break;
+                }
+            }
+            if (dispatchDecision.action === "skip") {
+                if (dispatchDecision.reason === "stale-lease") {
+                    const msg = `Lost milestone lease for ${iterData.mid ?? "unknown"} while claiming ${iterData.unitType} ${iterData.unitId}; dispatch claim still failed after recovery.`;
+                    ctx.ui.notify(msg, "error");
+                    finishTurn("stopped", "execution", msg);
+                    await deps.stopAuto(ctx, pi, msg);
+                    break;
+                }
+                finishTurn("skipped", "execution", dispatchDecision.reason);
                 continue;
             }
-            dispatchId = dispatchClaim.kind === "opened" ? dispatchClaim.dispatchId : null;
+            dispatchId = dispatchDecision.dispatchId;
             let unitPhaseResult;
             try {
-                unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem);
+                unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem, unitDispatchDeps);
             }
             catch (err) {
                 if (err instanceof ModelPolicyDispatchBlockedError) {
                     throw err;
                 }
-                if (dispatchId !== null) {
-                    try {
-                        markDispatchFailed(dispatchId, {
-                            errorSummary: `exception:${err instanceof Error ? err.message : String(err)}`,
-                        });
-                        dispatchSettled = true;
-                    }
-                    catch (ledgerErr) {
-                        debugLog("autoLoop", { phase: "dispatch-ledger-write-failed", error: ledgerErr instanceof Error ? ledgerErr.message : String(ledgerErr) });
-                    }
-                }
+                closeOutCrashedUnit(s, iterData, err);
+                dispatchSettled = settleDispatchFailed(dispatchId, formatDispatchExceptionSummary({ error: err }), {
+                    markFailed: markDispatchFailed,
+                    logWriteFailure: logDispatchLedgerWriteFailure,
+                }) || dispatchSettled;
                 throw err;
             }
             if (unitPhaseResult.action === "next") {
-                const requestTimestamp = unitPhaseResult.data.requestDispatchedAt ?? unitPhaseResult.data.unitStartedAt;
-                if (typeof requestTimestamp === "number")
+                const requestTimestamp = resolveUnitRequestTimestamp(unitPhaseResult.data);
+                if (requestTimestamp !== undefined)
                     s.lastRequestTimestamp = requestTimestamp;
             }
-            deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
+            phaseReporter.report("unit", unitPhaseResult.action, {
                 unitType: iterData.unitType,
                 unitId: iterData.unitId,
             });
             if (unitPhaseResult.action === "break") {
-                if (dispatchId !== null) {
-                    try {
-                        markDispatchFailed(dispatchId, { errorSummary: "unit-break" });
-                        dispatchSettled = true;
-                    }
-                    catch (err) {
-                        debugLog("autoLoop", { phase: "dispatch-ledger-write-failed", error: err instanceof Error ? err.message : String(err) });
-                    }
-                }
+                dispatchSettled = settleDispatchFailed(dispatchId, "unit-break", {
+                    markFailed: markDispatchFailed,
+                    logWriteFailure: logDispatchLedgerWriteFailure,
+                }) || dispatchSettled;
                 finishTurn("stopped", "execution", "unit-break");
                 break;
             }
@@ -736,88 +703,57 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 finalizeResult = await runFinalize(ic, iterData, loopState, sidecarItem);
             }
             catch (err) {
-                if (dispatchId !== null) {
-                    try {
-                        markDispatchFailed(dispatchId, {
-                            errorSummary: `exception:${err instanceof Error ? err.message : String(err)}`,
-                        });
-                        dispatchSettled = true;
-                    }
-                    catch (ledgerErr) {
-                        debugLog("autoLoop", { phase: "dispatch-ledger-write-failed", error: ledgerErr instanceof Error ? ledgerErr.message : String(ledgerErr) });
-                    }
-                }
+                dispatchSettled = settleDispatchFailed(dispatchId, formatDispatchExceptionSummary({ error: err }), {
+                    markFailed: markDispatchFailed,
+                    logWriteFailure: logDispatchLedgerWriteFailure,
+                }) || dispatchSettled;
                 throw err;
             }
-            deps.uokObserver?.onPhaseResult("finalize", finalizeResult.action, {
+            phaseReporter.report("finalize", finalizeResult.action, {
                 unitType: iterData.unitType,
                 unitId: iterData.unitId,
             });
-            if (finalizeResult.action === "break") {
-                const finalizeFailureClass = finalizeResult.reason === "git-closeout-failure"
-                    ? "git"
-                    : "closeout";
-                if (dispatchId !== null) {
-                    try {
-                        markDispatchFailed(dispatchId, { errorSummary: `finalize-break:${finalizeResult.reason ?? "unknown"}` });
-                        dispatchSettled = true;
-                    }
-                    catch (err) {
-                        debugLog("autoLoop", { phase: "dispatch-ledger-write-failed", error: err instanceof Error ? err.message : String(err) });
-                    }
-                }
-                finishTurn("stopped", finalizeFailureClass, "finalize-break");
+            const finalizeDecision = decideFinalizeResult(finalizeResult.action === "break"
+                ? { action: "break", reason: finalizeResult.reason }
+                : finalizeResult.action === "continue"
+                    ? { action: "continue" }
+                    : { action: "next" });
+            if (finalizeDecision.action === "stop") {
+                dispatchSettled = settleDispatchFailed(dispatchId, finalizeDecision.ledgerErrorSummary, {
+                    markFailed: markDispatchFailed,
+                    logWriteFailure: logDispatchLedgerWriteFailure,
+                }) || dispatchSettled;
+                finishTurn("stopped", finalizeDecision.failureClass, finalizeDecision.turnError);
                 break;
             }
-            if (finalizeResult.action === "continue") {
-                if (dispatchId !== null) {
-                    try {
-                        markDispatchFailed(dispatchId, { errorSummary: "finalize-retry" });
-                        dispatchSettled = true;
-                    }
-                    catch (err) {
-                        debugLog("autoLoop", { phase: "dispatch-ledger-write-failed", error: err instanceof Error ? err.message : String(err) });
-                    }
-                }
+            if (finalizeDecision.action === "retry") {
+                dispatchSettled = settleDispatchFailed(dispatchId, finalizeDecision.ledgerErrorSummary, {
+                    markFailed: markDispatchFailed,
+                    logWriteFailure: logDispatchLedgerWriteFailure,
+                }) || dispatchSettled;
                 finishTurn("retry");
                 continue;
             }
-            if (dispatchId !== null) {
-                try {
-                    markDispatchCompleted(dispatchId);
-                    dispatchSettled = true;
-                }
-                catch (err) {
-                    debugLog("autoLoop", { phase: "dispatch-ledger-write-failed", error: err instanceof Error ? err.message : String(err) });
-                }
-            }
-            consecutiveErrors = 0; // Iteration completed successfully
-            consecutiveCooldowns = 0;
-            recentErrorMessages.length = 0;
-            deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
-            saveStuckState(s, loopState); // persist across session restarts (#4382)
-            debugLog("autoLoop", { phase: "iteration-complete", iteration });
+            dispatchSettled = settleDispatchCompleted(dispatchId, {
+                markCompleted: markDispatchCompleted,
+                logWriteFailure: logDispatchLedgerWriteFailure,
+            }) || dispatchSettled;
+            completeIteration();
             finishTurn("completed");
         }
         catch (loopErr) {
             // ── Blanket catch: absorb unexpected exceptions, apply graduated recovery ──
             const msg = loopErr instanceof Error ? loopErr.message : String(loopErr);
             if (dispatchId !== null && !dispatchSettled && !(loopErr instanceof ModelPolicyDispatchBlockedError)) {
-                try {
-                    markDispatchFailed(dispatchId, { errorSummary: `unhandled-error:${msg.slice(0, 200)}` });
-                    dispatchSettled = true;
-                }
-                catch (err) {
-                    debugLog("autoLoop", {
-                        phase: "dispatch-ledger-write-failed",
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                }
+                dispatchSettled = settleDispatchFailed(dispatchId, formatUnhandledDispatchErrorSummary({ error: loopErr }), {
+                    markFailed: markDispatchFailed,
+                    logWriteFailure: logDispatchLedgerWriteFailure,
+                }) || dispatchSettled;
             }
             // Always emit iteration-end on error so the journal records iteration
             // completion even on failure (#2344). Without this, errors in
             // runFinalize leave the journal incomplete, making diagnosis harder.
-            deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration, error: msg } });
+            journalReporter.emit("iteration-end", { iteration, error: msg });
             // ── Pre-send model-policy block: not a retryable error (#4959 / #4850) ──
             // The model-policy gate runs before the prompt is sent.  When every
             // candidate model is denied (cross-provider disabled + flat-rate
@@ -827,6 +763,12 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             // instead, with the per-model deny reasons surfaced from the typed
             // error.
             if (loopErr instanceof ModelPolicyDispatchBlockedError) {
+                const policyDecision = decideModelPolicyBlocked({
+                    unitType: loopErr.unitType,
+                    unitId: loopErr.unitId,
+                    errorMessage: msg,
+                    reasons: loopErr.reasons,
+                });
                 debugLog("autoLoop", {
                     phase: "model-policy-blocked",
                     iteration,
@@ -834,20 +776,8 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     unitId: loopErr.unitId,
                     reasons: loopErr.reasons,
                 });
-                ctx.ui.notify(`Auto-mode paused: model-policy denied dispatch for ${loopErr.unitType}/${loopErr.unitId}. ${msg}`, "error");
-                deps.emitJournalEvent({
-                    ts: new Date().toISOString(),
-                    flowId,
-                    seq: nextSeq(),
-                    eventType: "unit-end",
-                    data: {
-                        unitType: loopErr.unitType,
-                        unitId: loopErr.unitId,
-                        status: "blocked",
-                        reason: "model-policy-dispatch-blocked",
-                        reasons: loopErr.reasons,
-                    },
-                });
+                ctx.ui.notify(policyDecision.notifyMessage, "error");
+                journalReporter.emit("unit-end", policyDecision.journalData);
                 // Carry the blocked unit identity into the turn-result observer:
                 // the throw originated inside dispatch, so observedUnitType/Id were
                 // not assigned by the success path at lines 453/631/647 — but the
@@ -855,7 +785,7 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 observedUnitType = loopErr.unitType;
                 observedUnitId = loopErr.unitId;
                 await deps.pauseAuto(ctx, pi);
-                finishTurn("paused", "manual-attention", msg);
+                finishTurn(policyDecision.turnStatus, policyDecision.failureClass, msg);
                 // Do NOT increment consecutiveErrors — the failure is configuration,
                 // not a transient runtime fault.
                 break;
@@ -865,15 +795,19 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             // LLM budget on guaranteed failures.
             const infraCode = isInfrastructureError(loopErr);
             if (infraCode) {
+                const infraDecision = decideInfrastructureError({
+                    code: infraCode,
+                    errorMessage: msg,
+                });
                 debugLog("autoLoop", {
                     phase: "infrastructure-error",
                     iteration,
                     code: infraCode,
                     error: msg,
                 });
-                ctx.ui.notify(`Auto-mode stopped: infrastructure error ${infraCode} — ${msg}`, "error");
-                await deps.stopAuto(ctx, pi, `Infrastructure error (${infraCode}): not recoverable by retry`);
-                finishTurn("failed", "execution", msg);
+                ctx.ui.notify(infraDecision.notifyMessage, "error");
+                await deps.stopAuto(ctx, pi, infraDecision.stopMessage);
+                finishTurn(infraDecision.turnStatus, infraDecision.failureClass, msg);
                 break;
             }
             // ── Credential cooldown: wait and retry with bounded budget ──
@@ -885,6 +819,12 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             if (isTransientCooldownError(loopErr)) {
                 consecutiveCooldowns++;
                 const retryAfterMs = getCooldownRetryAfterMs(loopErr);
+                const cooldownDecision = decideCooldownRecovery({
+                    consecutiveCooldowns,
+                    maxCooldownRetries: MAX_COOLDOWN_RETRIES,
+                    retryAfterMs,
+                    fallbackWaitMs: COOLDOWN_FALLBACK_WAIT_MS,
+                });
                 debugLog("autoLoop", {
                     phase: "cooldown-wait",
                     iteration,
@@ -892,16 +832,14 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                     retryAfterMs,
                     error: msg,
                 });
-                if (consecutiveCooldowns > MAX_COOLDOWN_RETRIES) {
-                    ctx.ui.notify(`Auto-mode stopped: ${consecutiveCooldowns} consecutive credential cooldowns — rate limit or quota may be persistently exhausted.`, "error");
-                    await deps.stopAuto(ctx, pi, `${consecutiveCooldowns} consecutive credential cooldowns exceeded retry budget`);
+                if (cooldownDecision.action === "stop") {
+                    ctx.ui.notify(cooldownDecision.notifyMessage, "error");
+                    finishTurn("stopped", "timeout", msg);
+                    await deps.stopAuto(ctx, pi, cooldownDecision.stopMessage);
                     break;
                 }
-                const waitMs = (retryAfterMs !== undefined && retryAfterMs > 0 && retryAfterMs <= 60_000)
-                    ? retryAfterMs + 500 // Use structured hint + small buffer
-                    : COOLDOWN_FALLBACK_WAIT_MS;
-                ctx.ui.notify(`Credentials in cooldown (${consecutiveCooldowns}/${MAX_COOLDOWN_RETRIES}) — waiting ${Math.round(waitMs / 1000)}s before retrying.`, "warning");
-                await new Promise(resolve => setTimeout(resolve, waitMs));
+                ctx.ui.notify(cooldownDecision.notifyMessage, "warning");
+                await new Promise(resolve => setTimeout(resolve, cooldownDecision.waitMs));
                 finishTurn("retry", "timeout", msg);
                 continue; // Retry iteration without incrementing consecutiveErrors
             }
@@ -913,26 +851,25 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 consecutiveErrors,
                 error: msg,
             });
-            if (consecutiveErrors >= 3) {
-                // 3+ consecutive: hard stop — something is fundamentally broken
-                const errorHistory = recentErrorMessages
-                    .map((m, i) => `  ${i + 1}. ${m}`)
-                    .join("\n");
-                ctx.ui.notify(`Auto-mode stopped: ${consecutiveErrors} consecutive iteration failures:\n${errorHistory}`, "error");
-                await deps.stopAuto(ctx, pi, `${consecutiveErrors} consecutive iteration failures`);
-                finishTurn("failed", "execution", msg);
+            const errorDecision = decideIterationErrorRecovery({
+                consecutiveErrors,
+                recentErrorMessages,
+                currentErrorMessage: msg,
+            });
+            if (errorDecision.action === "stop") {
+                ctx.ui.notify(errorDecision.notifyMessage, "error");
+                await deps.stopAuto(ctx, pi, errorDecision.stopMessage);
+                finishTurn(errorDecision.turnStatus, "execution", msg);
                 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");
+            if (errorDecision.action === "invalidate-and-retry") {
+                ctx.ui.notify(errorDecision.notifyMessage, "warning");
                 deps.invalidateAllCaches();
             }
             else {
-                // 1st error: log and retry — transient failures happen
-                ctx.ui.notify(`Iteration error: ${msg}. Retrying.`, "warning");
+                ctx.ui.notify(errorDecision.notifyMessage, "warning");
             }
-            finishTurn("retry", "execution", msg);
+            finishTurn(errorDecision.turnStatus, "execution", msg);
         }
     }
     _clearCurrentResolve();