@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/dist/resources/extensions/gsd/auto/unit-phase.js

@@ -0,0 +1,694 @@
+// Project/App: gsd-pi
+// File Purpose: Auto-loop unit execution phase.
+import { importExtensionModule } from "@gsd/pi-coding-agent";
+import { resetEvidence, loadEvidenceFromDisk } from "../safety/evidence-collector.js";
+import { captureRootDirtySnapshot } from "../root-write-leak-guard.js";
+import { USER_DRIVEN_DEEP_UNITS, isAwaitingUserInput, } from "../auto-post-unit.js";
+import { lastAssistantText } from "../consent-question.js";
+import { classifyProject } from "../detection.js";
+import { debugLog } from "../debug-logger.js";
+import { pauseAutoForProviderError } from "../provider-error-pause.js";
+import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.js";
+import { join } from "node:path";
+import { logWarning, _resetLogs } from "../workflow-logger.js";
+import { verifyExpectedArtifact, } from "../auto-recovery.js";
+import { writeUnitRuntimeRecord } from "../unit-runtime.js";
+import { isDbAvailable, getTask } from "../gsd-db.js";
+import { parseUnitId } from "../unit-id.js";
+import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js";
+import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
+import { getUnitWorkflowDispatchReadinessError } from "../tool-contract.js";
+import { prepareWorkflowMcpForProject } from "../workflow-mcp-auto-prep.js";
+import { applyThinkingLevelForModel, floorThinkingLevelForUnit, } from "../auto-model-selection.js";
+import { isSuspiciousGhostCompletion } from "../auto-unit-closeout.js";
+import { classifyError, isTransient } from "../error-classifier.js";
+import { setCurrentPhase } from "../../shared/gsd-phase-state.js";
+import { setAutoActiveStatus } from "../auto-dashboard.js";
+import { runUnit } from "./run-unit.js";
+import { validateSourceWriteWorktreeSafety } from "./worktree-safety-phase.js";
+import { isIsolatedWorktreeSession, _resolveCurrentUnitStartedAtForTest, emitCancelledUnitEnd, _buildCancelledUnitStopReason, _isPauseOriginCancelledResult, rememberRetryDispatch, } from "./phase-helpers.js";
+import { MAX_RECOVERY_CHARS } from "./types.js";
+const ZERO_TOOL_PROVIDER_ERROR_PREFIX_RE = /^(?:api error(?::|$|\s*\()|provider error(?::|$|\s*\()|request failed\b|(?:http\s*)?(?:429|500|502|503)\b|\b(?:econnreset|etimedout|econnrefused|epipe)\b|socket hang up\b|fetch failed\b|(?:network|connection|server) error(?::|$)|connection (?:reset|refused)(?::|$|\s+by\b)|dns\b.*(?:fail|error|timeout)|unexpected eof\b|stream idle timeout\b|partial response received\b|stream_exhausted\b|terminated(?::|$)|(?:connection|stream|request)\b.{0,40}\bterminated\b|other side closed\b|rate.?limit(?:ed| exceeded| reached| error)|too many requests\b|you(?:'ve| have) (?:hit|reached) your (?:\w+ )?limit\b|.*\b(?:usage|session|weekly|daily|monthly|quota) limit\b|limit\b.{0,40}\bresets?\b|out of extra usage\b|service.?unavailable\b|internal(?: server)? error(?::|$)|internal(?:[_-]server)?[_-]error\b|server[_-]error\b|(?:provider|server|api|model|codex|claude|openai|anthropic|gemini)\b.{0,80}\boverloaded\b|overloaded\b.{0,80}\b(?:provider|server|api|model)\b|context (?:window|length) exceed|context window exceed)/i;
+const ZERO_TOOL_PROVIDER_ERROR_SIGNAL_RE = /(?:\b(?:http|status(?: code)?|code|error:)\s*(?:429|500|502|503)\b|\b(?:api|provider) error\s*[:(]?\s*(?:429|500|502|503)\b|\b(?:typeerror|error):\s*(?:fetch failed\b|socket hang up\b|terminated(?::|$)|connection (?:reset|refused)(?::|$|\s+by\b)|(?:network|connection|server) error(?::|$)|stream idle timeout\b|partial response received\b|unexpected eof\b)|\b(?:server_error|api_error|stream_exhausted(?:_without_result)?)\b|\b(?:econnreset|etimedout|econnrefused|epipe)\b|context (?:window|length) exceed|context window exceed)/i;
+function classifyZeroToolProviderMessage(message) {
+    const firstLine = message.trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
+    if (!firstLine ||
+        (!ZERO_TOOL_PROVIDER_ERROR_PREFIX_RE.test(firstLine) &&
+            !ZERO_TOOL_PROVIDER_ERROR_SIGNAL_RE.test(firstLine)))
+        return null;
+    return classifyError(firstLine);
+}
+export const _classifyZeroToolProviderMessageForTest = classifyZeroToolProviderMessage;
+export function resolveDispatchRecoveryAttempts(unitRecoveryCount, unitType, unitId) {
+    return (unitRecoveryCount.get(`${unitType}/${unitId}`) ?? 0) > 0
+        ? 0
+        : undefined;
+}
+export function _shouldProceedWithInvalidRepoClassificationForTest(reason, hasGit) {
+    return reason === "missing .git" && hasGit;
+}
+// ─── Session timeout auto-resume state ────────────────────────────────────────
+let consecutiveSessionTimeouts = 0;
+const MAX_SESSION_TIMEOUT_AUTO_RESUMES = 3;
+/** Maximum zero-tool-call retries before pausing — context exhaustion is deterministic. */
+const MAX_ZERO_TOOL_RETRIES = 1;
+export function resetSessionTimeoutState() {
+    consecutiveSessionTimeouts = 0;
+}
+/**
+ * Phase 4: Unit execution — dispatch prompt, await agent_end, closeout, artifact verify.
+ * Returns break or next with unitStartedAt for downstream phases.
+ */
+export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
+    const { ctx, pi, s, deps, prefs } = ic;
+    const { unitType, unitId, prompt, state, mid } = iterData;
+    debugLog("autoLoop", {
+        phase: "unit-execution",
+        iteration: ic.iteration,
+        unitType,
+        unitId,
+    });
+    const worktreeSafetyBlock = await validateSourceWriteWorktreeSafety(ic, unitType, unitId, mid, "unit-execution");
+    if (worktreeSafetyBlock)
+        return worktreeSafetyBlock;
+    // ── Project classification notice (#1833, #1843) ─────────────────────
+    // Worktree Safety owns source-write root validity. Classification now only
+    // shapes user/model guidance for valid roots.
+    let projectClassification = null;
+    if (s.basePath && unitType === "execute-task") {
+        projectClassification = classifyProject(s.basePath);
+        if (projectClassification.kind === "invalid-repo") {
+            const msg = `Worktree health check failed: ${s.basePath} classified as invalid-repo (${projectClassification.reason}) — refusing to dispatch ${unitType} ${unitId}`;
+            debugLog("runUnitPhase", { phase: "worktree-health-invalid-repo", basePath: s.basePath, classification: projectClassification });
+            const hasGit = deps.existsSync(join(s.basePath, ".git"));
+            if (_shouldProceedWithInvalidRepoClassificationForTest(projectClassification.reason, hasGit)) {
+                ctx.ui.notify(`Warning: ${s.basePath} project classification could not confirm .git; assuming it has no project content yet — proceeding as greenfield project because worktree health reported .git present`, "warning");
+            }
+            else {
+                ctx.ui.notify(msg, "error");
+                await deps.stopAuto(ctx, pi, msg);
+                return { action: "break", reason: "worktree-invalid" };
+            }
+        }
+        if (projectClassification.kind === "greenfield") {
+            debugLog("runUnitPhase", { phase: "worktree-health-greenfield", basePath: s.basePath, classification: projectClassification });
+            ctx.ui.notify(`Warning: ${s.basePath} has no project content yet — proceeding as greenfield project`, "warning");
+        }
+        else if (projectClassification.kind === "untyped-existing") {
+            debugLog("runUnitPhase", { phase: "worktree-health-untyped-existing", basePath: s.basePath, classification: projectClassification });
+            ctx.ui.notify(`Notice: ${s.basePath} has existing project content but no recognized tooling markers — using generic file-level workflow guidance`, "info");
+        }
+    }
+    // Detect retry and capture previous tier for escalation
+    const isRetry = !!(s.currentUnit &&
+        s.currentUnit.type === unitType &&
+        s.currentUnit.id === unitId);
+    const previousTier = s.currentUnitRouting?.tier;
+    const dispatchKey = `${unitType}/${unitId}`;
+    const nextDispatchCount = (s.unitDispatchCount.get(dispatchKey) ?? 0) + 1;
+    // Status bar (widget + preconditions deferred until after model selection — see #2899)
+    setAutoActiveStatus(ctx, s.stepMode ? "next" : "auto");
+    if (mid)
+        deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id);
+    // ── Safety harness: reset evidence + create checkpoint ──
+    const safetyConfig = resolveSafetyHarnessConfig(prefs?.safety_harness);
+    if (safetyConfig.enabled && safetyConfig.evidence_collection) {
+        resetEvidence();
+        // Restore persisted evidence so session-restart resumes don't produce
+        // false-positive "no bash calls" warnings (Bug #4385).
+        if (s.basePath && unitType === "execute-task") {
+            const { milestone: eMid, slice: eSid, task: eTid } = parseUnitId(unitId);
+            if (eMid && eSid && eTid) {
+                loadEvidenceFromDisk(s.basePath, eMid, eSid, eTid);
+            }
+        }
+    }
+    // Only checkpoint code-executing units (not lifecycle/planning units)
+    if (safetyConfig.enabled && safetyConfig.checkpoints && unitType === "execute-task") {
+        s.checkpointSha = createCheckpoint(s.basePath, unitId);
+        if (s.checkpointSha) {
+            debugLog("runUnitPhase", { phase: "checkpoint-created", unitId, sha: s.checkpointSha.slice(0, 8) });
+        }
+    }
+    // Prompt injection
+    let finalPrompt = prompt;
+    if (unitType === "execute-task") {
+        projectClassification ??= classifyProject(s.basePath);
+        if (projectClassification.kind === "untyped-existing") {
+            const samples = projectClassification.contentFiles.slice(0, 8).join(", ") || "project files";
+            finalPrompt +=
+                "\n\n**Project classification:** Existing untyped project. No recognized build/tooling markers were detected, " +
+                    "so use generic file-level workflow guidance. Task plans and completion summaries must list every concrete " +
+                    `project file changed in \`files\` or \`expected_output\`. Detected content sample: ${samples}.`;
+        }
+    }
+    if (s.pendingVerificationRetry && s.pendingVerificationRetry.unitId === unitId) {
+        const retryCtx = s.pendingVerificationRetry;
+        s.pendingVerificationRetry = null;
+        const capped = retryCtx.failureContext.length > MAX_RECOVERY_CHARS
+            ? retryCtx.failureContext.slice(0, MAX_RECOVERY_CHARS) +
+                "\n\n[...failure context truncated]"
+            : retryCtx.failureContext;
+        finalPrompt = `**VERIFICATION FAILED — AUTO-FIX ATTEMPT ${retryCtx.attempt}**\n\nThe verification gate ran after your previous attempt and found failures. Fix these issues before completing the task.\n\n${capped}\n\n---\n\n${finalPrompt}`;
+    }
+    if (s.pendingCrashRecovery) {
+        const capped = s.pendingCrashRecovery.length > MAX_RECOVERY_CHARS
+            ? s.pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) +
+                "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
+            : s.pendingCrashRecovery;
+        finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
+        s.pendingCrashRecovery = null;
+    }
+    else if (nextDispatchCount > 1) {
+        const diagnostic = deps.getDeepDiagnostic(s.basePath);
+        if (diagnostic) {
+            const cappedDiag = diagnostic.length > MAX_RECOVERY_CHARS
+                ? diagnostic.slice(0, MAX_RECOVERY_CHARS) +
+                    "\n\n[...diagnostic truncated to prevent memory exhaustion]"
+                : diagnostic;
+            const retryInstruction = unitType === "execute-task"
+                ? "The required artifact is `T##-SUMMARY.md`. Do NOT manually write this file. Call `gsd_task_complete` with `milestoneId`, `sliceId`, `taskId`, and the required completion fields. Do not re-run implementation work — call the tool."
+                : "Fix whatever went wrong and make sure you write the required file this time.";
+            finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\n${retryInstruction}\n\n---\n\n${finalPrompt}`;
+        }
+    }
+    // Prompt char measurement
+    s.lastPromptCharCount = finalPrompt.length;
+    s.lastBaselineCharCount = undefined;
+    if (deps.isDbAvailable()) {
+        try {
+            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"),
+                inlineGsdRootFile(s.basePath, "project.md", "Project"),
+            ]);
+            s.lastBaselineCharCount =
+                (decisionsContent?.length ?? 0) +
+                    (requirementsContent?.length ?? 0) +
+                    (projectContent?.length ?? 0);
+        }
+        catch (e) {
+            logWarning("engine", "Baseline char count measurement failed", { error: String(e) });
+        }
+    }
+    // Cache-optimize prompt section ordering
+    try {
+        finalPrompt = deps.reorderForCaching(finalPrompt);
+    }
+    catch (reorderErr) {
+        const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
+        logWarning("engine", "Prompt reorder failed", { error: msg });
+    }
+    // Select and apply model (with tier escalation on retry — normal units only)
+    const prevUnitRouting = s.currentUnitRouting;
+    const prevUnitModel = s.currentUnitModel;
+    const prevDispatchedModelId = s.currentDispatchedModelId;
+    const prevSessionModel = ctx.model;
+    const prevSessionThinkingLevel = pi.getThinkingLevel();
+    const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, sidecarItem ? undefined : { isRetry, previousTier }, undefined, s.manualSessionModelOverride, s.autoModeStartThinkingLevel);
+    s.currentUnitRouting =
+        modelResult.routing;
+    s.currentUnitModel =
+        modelResult.appliedModel;
+    // Apply sidecar/pre-dispatch hook model override (takes priority over standard model selection)
+    const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;
+    if (hookModelOverride) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const match = deps.resolveModelId(hookModelOverride, availableModels, ctx.model?.provider);
+        if (match) {
+            const ok = await pi.setModel(match, { persist: false });
+            if (ok) {
+                // Apply the per-phase reasoning effort selectAndApplyModel resolved for
+                // this unit — not the auto-start session snapshot — but route it through
+                // the same floor + capability-clamp pipeline against the *hook* model
+                // (ADR-026). The hook override can pick a different model family than the
+                // one selectAndApplyModel clamped against, so re-clamping here prevents
+                // sending an unsupported level; the floor fills in when no phase level
+                // resolved so a hook-overridden execute-task still meets the floor.
+                const hookThinkingBase = modelResult.appliedThinkingLevel
+                    ?? floorThinkingLevelForUnit(unitType, s.autoModeStartThinkingLevel);
+                applyThinkingLevelForModel(pi, hookThinkingBase, match, ctx);
+                s.currentUnitModel = match;
+                ctx.ui.notify(`Hook model override: ${match.provider}/${match.id}`, "info");
+            }
+            else {
+                ctx.ui.notify(`Hook model "${hookModelOverride}" found but setModel failed. Using default.`, "warning");
+            }
+        }
+        else {
+            ctx.ui.notify(`Hook model "${hookModelOverride}" not found in available models. Falling back to current session model. ` +
+                `Ensure the model is defined in models.json and has auth configured.`, "warning");
+        }
+    }
+    // Store the final dispatched model ID so the dashboard can read it (#2899).
+    // This accounts for hook model overrides applied after selectAndApplyModel.
+    s.currentDispatchedModelId = s.currentUnitModel
+        ? `${s.currentUnitModel.provider ?? ""}/${s.currentUnitModel.id ?? ""}`
+        : null;
+    const compatibilityError = getUnitWorkflowDispatchReadinessError({
+        provider: s.currentUnitModel?.provider ?? ctx.model?.provider,
+        projectRoot: s.basePath,
+        surface: "auto-mode",
+        unitType,
+        authMode: s.currentUnitModel?.provider
+            ? ctx.modelRegistry.getProviderAuthMode(s.currentUnitModel.provider)
+            : ctx.model?.provider
+                ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+                : undefined,
+        baseUrl: s.currentUnitModel?.baseUrl ?? ctx.model?.baseUrl,
+        activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+    });
+    const workflowMcpPrepModel = s.currentUnitModel;
+    if (compatibilityError) {
+        s.currentUnitRouting = prevUnitRouting;
+        s.currentUnitModel = prevUnitModel;
+        s.currentDispatchedModelId = prevDispatchedModelId;
+        if (s.checkpointSha) {
+            cleanupCheckpoint(s.basePath, unitId);
+            s.checkpointSha = null;
+        }
+        if (prevSessionModel) {
+            const ok = await pi.setModel(prevSessionModel, { persist: false });
+            if (!ok) {
+                ctx.ui.notify("Failed to restore previous session model after compatibility check failure.", "warning");
+            }
+            if (prevSessionThinkingLevel) {
+                pi.setThinkingLevel(prevSessionThinkingLevel);
+            }
+        }
+        const workflowMcpPrep = prepareWorkflowMcpForProject(ctx, s.basePath, workflowMcpPrepModel);
+        if (workflowMcpPrep && workflowMcpPrep.status !== "unchanged") {
+            const pauseMsg = "GSD workflow MCP config has been written. Restart Claude Code (or reload MCP servers), then run /gsd auto to continue.";
+            ctx.ui.notify(pauseMsg, "warning");
+            await deps.pauseAuto(ctx, pi, {
+                category: "provider",
+                isTransient: true,
+                message: pauseMsg,
+            });
+            return { action: "break", reason: "workflow-capability" };
+        }
+        ctx.ui.notify(compatibilityError, "error");
+        await deps.stopAuto(ctx, pi, compatibilityError);
+        return { action: "break", reason: "workflow-capability" };
+    }
+    // Scope workflow-logger buffer to this unit so post-finalize drains are
+    // per-unit. Without this, the module-level _buffer accumulates across every
+    // unit in the same Node process (see workflow-logger.ts module header).
+    _resetLogs();
+    const unitStartedAt = Date.now();
+    s.unitDispatchCount.set(dispatchKey, nextDispatchCount);
+    s.setCurrentUnit({ type: unitType, id: unitId, startedAt: unitStartedAt, workspaceRoot: s.basePath });
+    if (unitType === "execute-task") {
+        const { milestone, slice, task } = parseUnitId(unitId);
+        if (milestone && slice && task && isDbAvailable()) {
+            try {
+                const taskRow = getTask(milestone, slice, task);
+                if (taskRow)
+                    s.sourceObservations.observePlanTask(taskRow);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logWarning("prompt", `failed to preload source observations for ${unitId}: ${message}`);
+            }
+        }
+    }
+    s.rootWriteBaseline = isIsolatedWorktreeSession(s)
+        ? captureRootDirtySnapshot(s.originalBasePath)
+        : null;
+    s.lastGitActionFailure = null;
+    s.lastGitActionStatus = null;
+    s.lastUnitAgentEndMessages = null;
+    setCurrentPhase(unitType, {
+        basePath: s.basePath,
+        traceId: ic.flowId,
+        turnId: `iter-${ic.iteration}`,
+        causedBy: "unit-start",
+    });
+    s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
+    if (nextDispatchCount <= 1) {
+        s.toolUnavailableRetries = 0;
+    }
+    const unitStartSeq = ic.nextSeq();
+    deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
+    deps.captureAvailableSkills();
+    writeUnitRuntimeRecord(s.basePath, unitType, unitId, unitStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: unitStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+        recoveryAttempts: resolveDispatchRecoveryAttempts(s.unitRecoveryCount, unitType, unitId),
+    });
+    // Progress widget + preconditions — deferred to after model selection so the
+    // widget's first render tick shows the correct model (#2899).
+    deps.updateProgressWidget(ctx, unitType, unitId, state);
+    deps.ensurePreconditions(unitType, unitId, s.basePath, state);
+    // Start unit supervision
+    deps.clearUnitTimeout();
+    deps.startUnitSupervision({
+        s,
+        ctx,
+        pi,
+        unitType,
+        unitId,
+        prefs,
+        buildSnapshotOpts: () => deps.buildSnapshotOpts(unitType, unitId),
+        buildRecoveryContext: () => ({
+            basePath: s.basePath,
+            verbose: s.verbose,
+            currentUnitStartedAt: s.currentUnit?.startedAt ?? Date.now(),
+            unitRecoveryCount: s.unitRecoveryCount,
+        }),
+        pauseAuto: deps.pauseAuto,
+    });
+    // Write preliminary lock (no session path yet — runUnit creates a new session).
+    // Crash recovery can still identify the in-flight unit from this lock.
+    deps.writeLock(deps.lockBase(), unitType, unitId);
+    debugLog("autoLoop", {
+        phase: "runUnit-start",
+        iteration: ic.iteration,
+        unitType,
+        unitId,
+    });
+    const pausedBeforeRun = s.paused;
+    const unitResult = await runUnit(ctx, pi, s, unitType, unitId, finalPrompt);
+    s.lastUnitAgentEndMessages = unitResult.event?.messages ?? null;
+    debugLog("autoLoop", {
+        phase: "runUnit-end",
+        iteration: ic.iteration,
+        unitType,
+        unitId,
+        status: unitResult.status,
+    });
+    if (unitResult.status === "completed" &&
+        s.currentUnit &&
+        (unitResult.event?.messages?.length ?? 0) === 0 &&
+        isSuspiciousGhostCompletion(ctx, unitResult.requestDispatchedAt ?? s.currentUnit.startedAt)) {
+        const message = `${unitType} ${unitId} completed without assistant output or tool calls; treating as a stale ghost completion.`;
+        debugLog("autoLoop", {
+            phase: "ghost-completion",
+            iteration: ic.iteration,
+            unitType,
+            unitId,
+            elapsedMs: Date.now() - (unitResult.requestDispatchedAt ?? s.currentUnit.startedAt),
+        });
+        logWarning("engine", message);
+        ctx.ui.notify(`${message} Pausing auto-mode before closeout side effects.`, "warning");
+        await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, {
+            message,
+            category: "unknown",
+            isTransient: true,
+        });
+        s.clearCurrentUnit();
+        await deps.pauseAuto(ctx, pi);
+        return { action: "break", reason: "ghost-completion" };
+    }
+    // Now that runUnit has called newSession(), the session file path is correct.
+    const sessionFile = deps.getSessionFile(ctx);
+    deps.updateSessionLock(deps.lockBase(), unitType, unitId, sessionFile);
+    deps.writeLock(deps.lockBase(), unitType, unitId, sessionFile);
+    // Tag the most recent window entry with error info for stuck detection
+    const lastEntry = loopState.recentUnits[loopState.recentUnits.length - 1];
+    if (lastEntry) {
+        if (unitResult.errorContext) {
+            lastEntry.error = `${unitResult.errorContext.category}:${unitResult.errorContext.message}`.slice(0, 200);
+        }
+        else if (unitResult.status === "error" || unitResult.status === "cancelled") {
+            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)) {
+                lastEntry.error = msgStr.slice(0, 200);
+            }
+        }
+    }
+    if (unitResult.status === "cancelled") {
+        if (_isPauseOriginCancelledResult(s.paused, unitResult.errorContext)) {
+            if (!pausedBeforeRun) {
+                const pauseContext = {
+                    message: "Auto-mode paused during unit setup",
+                    category: "aborted",
+                    isTransient: true,
+                };
+                await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+                await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, pauseContext);
+                return { action: "break", reason: "pause-during-setup" };
+            }
+            debugLog("autoLoop", { phase: "cancelled-after-pause", unitType, unitId });
+            return { action: "break", reason: "paused" };
+        }
+        const errorCategory = unitResult.errorContext?.category;
+        // Provider-error pause: agent_end recovery normally pauses before this
+        // branch. Provider readiness failures happen before dispatch, so pause here
+        // if nothing upstream already did.
+        if (errorCategory === "provider") {
+            if (!s.paused) {
+                const detail = unitResult.errorContext?.message ?? `Provider unavailable for ${unitType} ${unitId}`;
+                const isTransient = Boolean(unitResult.errorContext?.isTransient);
+                const retryAfterMs = unitResult.errorContext?.retryAfterMs ?? (isTransient ? 30_000 : undefined);
+                await pauseAutoForProviderError(ctx.ui, detail, () => deps.pauseAuto(ctx, pi), {
+                    isRateLimit: false,
+                    isTransient,
+                    retryAfterMs,
+                    resume: isTransient
+                        ? () => {
+                            void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
+                                logWarning("engine", `Provider error auto-resume failed: ${err instanceof Error ? err.message : String(err)}`);
+                            });
+                        }
+                        : undefined,
+                });
+            }
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext?.isTransient });
+            return { action: "break", reason: "provider-pause" };
+        }
+        // Timeout category covers two distinct scenarios:
+        //   1. Session creation timeout (120s) — transient, auto-resume with backoff
+        //   2. Unit hard timeout (30min+) — stuck agent, pause for manual review
+        // Transient session-failed covers recoverable newSession failures and should
+        // pause instead of hard-stopping.
+        // Structural errors (TypeError, is not a function) are NOT transient
+        // and must hard-stop to avoid infinite retry loops.
+        if (unitResult.errorContext?.isTransient &&
+            errorCategory === "timeout") {
+            const isSessionCreationTimeout = unitResult.errorContext.message?.includes("Session creation timed out");
+            if (isSessionCreationTimeout) {
+                consecutiveSessionTimeouts += 1;
+                const baseRetryAfterMs = 30_000;
+                const retryAfterMs = baseRetryAfterMs * 2 ** Math.max(0, consecutiveSessionTimeouts - 1);
+                const allowAutoResume = consecutiveSessionTimeouts <= MAX_SESSION_TIMEOUT_AUTO_RESUMES;
+                if (!allowAutoResume) {
+                    ctx.ui.notify(`Session creation timed out ${consecutiveSessionTimeouts} consecutive times for ${unitType} ${unitId}. Pausing for manual review.`, "warning");
+                }
+                debugLog("autoLoop", {
+                    phase: "session-timeout-pause",
+                    unitType, unitId,
+                    consecutiveSessionTimeouts,
+                    retryAfterMs,
+                    allowAutoResume,
+                });
+                const errorDetail = ` for ${unitType} ${unitId}`;
+                await pauseAutoForProviderError(ctx.ui, errorDetail, () => deps.pauseAuto(ctx, pi), {
+                    isRateLimit: false,
+                    isTransient: allowAutoResume,
+                    retryAfterMs,
+                    resume: allowAutoResume
+                        ? () => {
+                            void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
+                                const message = err instanceof Error ? err.message : String(err);
+                                ctx.ui.notify(`Session timeout recovery failed: ${message}`, "error");
+                            });
+                        }
+                        : undefined,
+                });
+                await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+                await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+                return { action: "break", reason: "session-timeout" };
+            }
+            // Unit hard timeout (30min+): pause without auto-resume — stuck agent
+            ctx.ui.notify(`Unit timed out for ${unitType} ${unitId} (supervision may have failed). Pausing auto-mode.`, "warning");
+            debugLog("autoLoop", { phase: "unit-hard-timeout-pause", unitType, unitId });
+            await deps.pauseAuto(ctx, pi);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "unit-hard-timeout" };
+        }
+        if (unitResult.errorContext?.isTransient &&
+            errorCategory === "session-failed") {
+            ctx.ui.notify(`Session creation failed transiently for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Pausing auto-mode (recoverable).`, "warning");
+            debugLog("autoLoop", { phase: "session-start-transient-pause", unitType, unitId, category: errorCategory });
+            await deps.pauseAuto(ctx, pi);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "session-timeout" };
+        }
+        if (unitResult.errorContext?.isTransient &&
+            errorCategory === "aborted") {
+            rememberRetryDispatch(s, { type: unitType, id: unitId }, iterData);
+            writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit?.startedAt ?? Date.now(), {
+                phase: "paused",
+                lastProgressAt: Date.now(),
+                lastProgressKind: "unit-aborted-pause",
+            });
+            ctx.ui.notify(`Unit ${unitType} ${unitId} was aborted (transient). Pausing auto-mode (recoverable).`, "warning");
+            debugLog("autoLoop", { phase: "unit-aborted-transient-pause", unitType, unitId, category: errorCategory });
+            await deps.pauseAuto(ctx, pi, unitResult.errorContext);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "unit-aborted-pause" };
+        }
+        // All other cancelled states (structural errors, non-transient failures): hard stop
+        if (s.currentUnit) {
+            await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));
+        }
+        await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+        await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+        const cancelledStop = _buildCancelledUnitStopReason(unitType, unitId, unitResult.errorContext);
+        ctx.ui.notify(cancelledStop.notifyMessage, "warning");
+        await deps.stopAuto(ctx, pi, cancelledStop.stopReason);
+        debugLog("autoLoop", { phase: "exit", reason: cancelledStop.loopReason });
+        return { action: "break", reason: cancelledStop.loopReason };
+    }
+    // ── Immediate unit closeout (metrics, activity log, memory) ────────
+    // Run right after runUnit() returns so telemetry is never lost to a
+    // crash between iterations.
+    // Guard: stopAuto() may have nulled s.currentUnit via s.reset() while
+    // this coroutine was suspended at `await runUnit(...)` (#2939).
+    if (s.currentUnit) {
+        // Reset session timeout counter — any successful unit clears the slate
+        consecutiveSessionTimeouts = 0;
+        await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));
+    }
+    // ── Zero tool-call guard (#1833, #2653) ──────────────────────────
+    // Any unit that completes with 0 tool calls made no real progress —
+    // likely context exhaustion where all tool calls errored out. Treat
+    // as failed so the unit is retried in a fresh context instead of
+    // silently passing through to artifact verification (which loops
+    // forever when the unit never produced its artifact).
+    {
+        const currentLedger = deps.getLedger();
+        if (currentLedger?.units) {
+            const lastUnit = [...currentLedger.units].reverse().find((u) => u.type === unitType && u.id === unitId && u.startedAt === _resolveCurrentUnitStartedAtForTest(s.currentUnit));
+            if (lastUnit && lastUnit.toolCalls === 0) {
+                const lastAssistantMessage = lastAssistantText(s.lastUnitAgentEndMessages);
+                const providerMessageClass = classifyZeroToolProviderMessage(lastAssistantMessage);
+                if (providerMessageClass && isTransient(providerMessageClass)) {
+                    const retryAfterMs = "retryAfterMs" in providerMessageClass ? providerMessageClass.retryAfterMs : 15_000;
+                    await pauseAutoForProviderError(ctx.ui, ` for ${unitType} ${unitId}`, () => deps.pauseAuto(ctx, pi), {
+                        isRateLimit: providerMessageClass.kind === "rate-limit",
+                        isTransient: true,
+                        retryAfterMs,
+                        resume: () => {
+                            void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
+                                logWarning("engine", `Provider error auto-resume failed: ${err instanceof Error ? err.message : String(err)}`);
+                            });
+                        },
+                    });
+                    await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, {
+                        message: lastAssistantMessage.slice(0, 200),
+                        category: "provider",
+                        isTransient: true,
+                        retryAfterMs,
+                    });
+                    return {
+                        action: "break",
+                        reason: providerMessageClass.kind === "rate-limit" ? "rate-limit" : "api-timeout",
+                    };
+                }
+                if (USER_DRIVEN_DEEP_UNITS.has(unitType) && isAwaitingUserInput(s.lastUnitAgentEndMessages ?? undefined)) {
+                    debugLog("runUnitPhase", {
+                        phase: "zero-tool-calls-awaiting-user-input",
+                        unitType,
+                        unitId,
+                    });
+                }
+                else {
+                    const zeroToolKey = `${unitType}/${unitId}`;
+                    const attempt = (s.zeroToolRetryCount.get(zeroToolKey) ?? 0) + 1;
+                    debugLog("runUnitPhase", {
+                        phase: "zero-tool-calls",
+                        unitType,
+                        unitId,
+                        attempt,
+                        warning: "Unit completed with 0 tool calls — likely context exhaustion, marking as failed",
+                    });
+                    if (attempt > MAX_ZERO_TOOL_RETRIES) {
+                        s.zeroToolRetryCount.delete(zeroToolKey);
+                        ctx.ui.notify(`${unitType} ${unitId} completed with 0 tool calls — context exhaustion, pausing auto-mode after ${MAX_ZERO_TOOL_RETRIES} retry.`, "error");
+                        await deps.pauseAuto(ctx, pi);
+                        return { action: "break", reason: "zero-tool-calls-exhausted" };
+                    }
+                    s.zeroToolRetryCount.set(zeroToolKey, attempt);
+                    ctx.ui.notify(`${unitType} ${unitId} completed with 0 tool calls — context exhaustion, will retry (attempt ${attempt}/${MAX_ZERO_TOOL_RETRIES})`, "warning");
+                    return {
+                        action: "retry",
+                        reason: "zero-tool-calls",
+                        data: {
+                            unitStartedAt: _resolveCurrentUnitStartedAtForTest(s.currentUnit),
+                            requestDispatchedAt: unitResult.requestDispatchedAt,
+                        },
+                    };
+                }
+            }
+        }
+    }
+    const skipArtifactVerification = unitType.startsWith("hook/") || unitType === "custom-step";
+    const artifactVerified = skipArtifactVerification ||
+        verifyExpectedArtifact(unitType, unitId, s.basePath);
+    if (s.currentUnitRouting) {
+        deps.recordOutcome(unitType, s.currentUnitRouting.tier, artifactVerified);
+    }
+    if (artifactVerified) {
+        s.unitDispatchCount.delete(dispatchKey);
+        s.unitRecoveryCount.delete(`${unitType}/${unitId}`);
+        s.zeroToolRetryCount.delete(dispatchKey);
+    }
+    // Write phase handoff anchor after successful research/planning completion
+    const anchorPhases = new Set(["research-milestone", "research-slice", "plan-milestone", "plan-slice"]);
+    if (artifactVerified && mid && anchorPhases.has(unitType)) {
+        try {
+            const { writePhaseAnchor } = await import("../phase-anchor.js");
+            writePhaseAnchor(s.basePath, mid, {
+                phase: unitType,
+                milestoneId: mid,
+                generatedAt: new Date().toISOString(),
+                intent: `Completed ${unitType} for ${unitId}`,
+                decisions: [],
+                blockers: [],
+                nextSteps: [],
+            });
+        }
+        catch (err) { /* non-fatal — anchor is advisory */
+            logWarning("engine", `phase anchor failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const unitEndStatus = !artifactVerified && unitResult.status === "completed"
+        ? "no-artifact"
+        : unitResult.status;
+    deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "unit-end", data: { unitType, unitId, status: unitEndStatus, artifactVerified, ...(unitResult.errorContext ? { errorContext: unitResult.errorContext } : {}) }, causedBy: { flowId: ic.flowId, seq: unitStartSeq } });
+    // ── Safety harness: checkpoint cleanup or rollback ──
+    if (s.checkpointSha) {
+        if (unitResult.status === "error" && safetyConfig.auto_rollback) {
+            const rolled = rollbackToCheckpoint(s.basePath, unitId, s.checkpointSha);
+            if (rolled) {
+                ctx.ui.notify(`Rolled back to pre-unit checkpoint for ${unitId}`, "info");
+                debugLog("runUnitPhase", { phase: "checkpoint-rollback", unitId });
+            }
+        }
+        else if (unitResult.status === "error") {
+            ctx.ui.notify(`Unit ${unitId} failed. Pre-unit checkpoint available at ${s.checkpointSha.slice(0, 8)}`, "warning");
+        }
+        else {
+            // Success — clean up checkpoint ref
+            cleanupCheckpoint(s.basePath, unitId);
+            debugLog("runUnitPhase", { phase: "checkpoint-cleaned", unitId });
+        }
+        s.checkpointSha = null;
+    }
+    return { action: "next", data: { unitStartedAt: _resolveCurrentUnitStartedAtForTest(s.currentUnit), requestDispatchedAt: unitResult.requestDispatchedAt } };
+}