@opengsd/gsd-pi 1.2.0-dev.9ad8ae33 → 1.2.0-dev.a6376d75

package/dist/resources/extensions/claude-code-cli/turn-assembler.js

@@ -153,6 +153,38 @@ export function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
         block.externalResult = externalResult;
     }
 }
+function textFromExternalResult(result) {
+    return (result?.content ?? [])
+        .map((block) => typeof block.text === "string" ? block.text : "")
+        .join("\n");
+}
+function isEmptyToolArguments(value) {
+    return !!value
+        && typeof value === "object"
+        && !Array.isArray(value)
+        && Object.keys(value).length === 0;
+}
+function sameToolSurface(a, b) {
+    return a.name === b.name
+        && a.mcpServer === b.mcpServer;
+}
+export function shouldSuppressDuplicateToolUnavailableBlock(block, allBlocks) {
+    if (block.type !== "toolCall")
+        return false;
+    const externalResult = block.externalResult;
+    if (!externalResult?.isError)
+        return false;
+    if (!isEmptyToolArguments(block.arguments))
+        return false;
+    if (!/No such tool available:/i.test(textFromExternalResult(externalResult)))
+        return false;
+    return allBlocks.some((candidate) => {
+        if (candidate.type !== "toolCall" || candidate.id === block.id)
+            return false;
+        const candidateResult = candidate.externalResult;
+        return candidateResult?.isError === false && sameToolSurface(block, candidate);
+    });
+}
 /**
  * Build the final assistant content that Agent Core consumes in
  * `externalToolExecution` mode. This preserves tool-call blocks, attaches any
@@ -165,7 +197,7 @@ export function buildFinalAssistantContent(params) {
         mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
     }
     attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
-    const finalContent = [...mergedToolBlocks];
+    const finalContent = mergedToolBlocks.filter((block) => !shouldSuppressDuplicateToolUnavailableBlock(block, mergedToolBlocks));
     if (params.pendingContent && params.pendingContent.length > 0) {
         for (const block of params.pendingContent) {
             if (block.type === "text" || block.type === "thinking") {

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

@@ -0,0 +1,215 @@
+// Project/App: gsd-pi
+// File Purpose: Auto-loop closeout, milestone report, and merge helpers.
+import { importExtensionModule } from "@gsd/pi-coding-agent";
+import { MergeConflictError } from "../git-service.js";
+import { findUnmergedCompletedMilestones } from "../unmerged-milestone-guard.js";
+import { getIsolationMode } from "../preferences.js";
+import { isDbAvailable, getMilestone } from "../gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
+import { isClosedStatus } from "../status-guards.js";
+import { logWarning, logError } from "../workflow-logger.js";
+import { debugLog } from "../debug-logger.js";
+import { _resolveReportBasePath } from "./phase-helpers.js";
+/**
+ * If a unit is in-flight, close it out, then stop auto-mode.
+ */
+export async function closeoutAndStop(ctx, pi, s, deps, reason) {
+    if (s.currentUnit) {
+        await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+        s.clearCurrentUnit();
+    }
+    await deps.stopAuto(ctx, pi, reason);
+}
+export async function stopOnPostflightRecoveryNeeded(ic, result, milestoneId) {
+    if (!result.needsManualRecovery)
+        return null;
+    const { ctx, pi, deps } = ic;
+    const reason = `Post-merge stash restore failed for milestone ${milestoneId}`;
+    ctx.ui.notify(`${reason}. Resolve the working tree before resuming auto-mode. ${result.message}`, "error");
+    await deps.stopAuto(ctx, pi, reason);
+    return { action: "break", reason: "postflight-stash-restore-failed" };
+}
+export async function restorePreflightStashOrStop(ic, preflight, milestoneId) {
+    if (!preflight.stashPushed)
+        return null;
+    const { s, deps } = ic;
+    const result = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ic.ctx.ui.notify.bind(ic.ctx.ui));
+    return stopOnPostflightRecoveryNeeded(ic, result, milestoneId);
+}
+/**
+ * Run a milestone merge surrounded by preflight stash + always-on postflight
+ * pop. The previous code popped the stash only after a successful merge, which
+ * leaked `gsd-preflight-stash:M00x:*` entries whenever `mergeAndExit` threw —
+ * leaving the user's pre-merge working tree silently stashed away after a
+ * merge-conflict or other merge error. This helper restores the stash on
+ * every exit path, then surfaces the merge or stash failure (in priority
+ * order) as the loop's stop reason.
+ *
+ * Returns a `break` action when auto-mode must stop, or `null` when the merge
+ * succeeded and the stash (if any) was restored cleanly.
+ */
+export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, options = {}) {
+    const { ctx, pi, s, deps } = ic;
+    const preflight = deps.preflightCleanRoot(s.originalBasePath || s.basePath, milestoneId, ctx.ui.notify.bind(ctx.ui));
+    if (preflight.blocked) {
+        const reason = preflight.blockedReason === "unmerged-conflicts"
+            ? `Pre-merge unresolved Git conflicts block milestone ${milestoneId}`
+            : `Pre-merge dirty working tree overlaps milestone ${milestoneId}`;
+        await deps.stopAuto(ctx, pi, reason, {
+            preserveCompletedMilestoneBranch: true,
+            preserveCloseoutTranscript: options.preserveCloseoutTranscript,
+        });
+        return {
+            action: "break",
+            reason: preflight.blockedReason === "unmerged-conflicts"
+                ? "preflight-unmerged-conflicts"
+                : "preflight-dirty-overlap",
+        };
+    }
+    let mergeError = null;
+    const exitResult = deps.lifecycle.exitMilestone(milestoneId, { merge: true }, ctx.ui);
+    if (exitResult.ok) {
+        s.milestoneMergedInPhases = true;
+        try {
+            const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+            const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+            await rebuildMarkdownProjectionsFromDb(projectRoot);
+        }
+        catch (err) {
+            logWarning("engine", `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+    }
+    // Always attempt to restore the stashed working tree, even on merge error.
+    // postflightPopStash itself does not throw; failures surface via the
+    // PostflightResult.needsManualRecovery flag.
+    let stashResult = null;
+    if (preflight.stashPushed) {
+        stashResult = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ctx.ui.notify.bind(ctx.ui));
+    }
+    // Merge failure takes priority over stash recovery — the merge is the
+    // authoritative gate. If the stash also needed manual recovery, the user
+    // already saw the postflightPopStash notify above.
+    if (mergeError) {
+        if (mergeError instanceof MergeConflictError) {
+            // A merge conflict is a recoverable human checkpoint, not an
+            // infrastructure failure — the user resolves the conflict and runs
+            // `/gsd auto` to resume. Pause (don't stop): stopAuto tears down the
+            // session and, because `milestoneMergedInPhases` stays false here,
+            // re-runs the already-failed worktree merge in its cleanup step
+            // (#2645), then drops the user out of the interactive TUI onto a
+            // "stopped" surface.
+            const conflictReason = `Merge conflict on milestone ${milestoneId}: ${mergeError.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`;
+            ctx.ui.notify(conflictReason, "error");
+            await deps.pauseAuto(ctx, pi, {
+                message: conflictReason,
+                category: "unknown",
+            });
+            return { action: "break", reason: "merge-conflict" };
+        }
+        logError("engine", "Milestone merge failed with non-conflict error", {
+            milestone: milestoneId,
+            error: String(mergeError),
+        });
+        // Like a merge conflict, a non-conflict merge failure (index lock,
+        // network, permissions) is recoverable — the user fixes the cause and
+        // runs `/gsd auto` to resume. Pause (don't stop) so the session stays
+        // resumable and stopAuto's teardown does not re-run the failed merge.
+        const mergeFailReason = `Merge error on milestone ${milestoneId}: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}. Resolve and run /gsd auto to resume.`;
+        ctx.ui.notify(mergeFailReason, "error");
+        await deps.pauseAuto(ctx, pi, {
+            message: mergeFailReason,
+            category: "unknown",
+        });
+        return { action: "break", reason: "merge-failed" };
+    }
+    if (stashResult) {
+        return stopOnPostflightRecoveryNeeded(ic, stashResult, milestoneId);
+    }
+    return null;
+}
+export async function _runMilestoneMergeOnceWithStashRestore(ic, milestoneId, options = {}) {
+    if (ic.s.milestoneMergedInPhases) {
+        debugLog("autoLoop", {
+            phase: "milestone-merge-skip",
+            reason: "already-merged-in-phases",
+            milestoneId,
+        });
+        return null;
+    }
+    return _runMilestoneMergeWithStashRestore(ic, milestoneId, options);
+}
+export async function shouldSkipTerminalMilestoneCloseout(s, state, mid) {
+    const closeoutMilestoneId = mid ?? s.currentMilestoneId ?? state.lastCompletedMilestone?.id;
+    if (s.completionStopInProgress) {
+        return { skip: true, milestoneId: closeoutMilestoneId };
+    }
+    if (!closeoutMilestoneId) {
+        return { skip: false };
+    }
+    if (isDbAvailable())
+        refreshWorkflowDatabaseFromDisk();
+    const closeoutBasePath = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+    let closeoutMergePending = false;
+    if (getIsolationMode(closeoutBasePath) !== "none") {
+        try {
+            const blockers = await findUnmergedCompletedMilestones(closeoutBasePath);
+            closeoutMergePending = blockers.some((blocker) => blocker.milestoneId === closeoutMilestoneId);
+        }
+        catch {
+            // Fail open: without git/DB inspection we cannot safely treat closeout as done.
+            closeoutMergePending = true;
+        }
+    }
+    const milestoneAlreadyClosedOut = isDbAvailable()
+        && isClosedStatus(getMilestone(closeoutMilestoneId)?.status ?? "")
+        && !closeoutMergePending;
+    if (milestoneAlreadyClosedOut) {
+        return { skip: true, milestoneId: closeoutMilestoneId };
+    }
+    return { skip: false, milestoneId: closeoutMilestoneId };
+}
+/**
+ * Generate and write an HTML milestone report snapshot.
+ */
+export async function generateMilestoneReport(s, ctx, milestoneId) {
+    const { loadVisualizerData } = await importExtensionModule(import.meta.url, "../visualizer-data.js");
+    const { generateHtmlReport } = await importExtensionModule(import.meta.url, "../export-html.js");
+    const { writeReportSnapshot } = await importExtensionModule(import.meta.url, "../reports.js");
+    const { basename } = await import("node:path");
+    const reportBasePath = _resolveReportBasePath(s);
+    const snapData = await loadVisualizerData(reportBasePath);
+    const completedMs = snapData.milestones.find((m) => m.id === milestoneId);
+    const msTitle = completedMs?.title ?? milestoneId;
+    const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
+    const projName = basename(reportBasePath);
+    const doneSlices = snapData.milestones.reduce((acc, m) => acc + m.slices.filter((sl) => sl.done).length, 0);
+    const totalSlices = snapData.milestones.reduce((acc, m) => acc + m.slices.length, 0);
+    const outPath = writeReportSnapshot({
+        basePath: reportBasePath,
+        html: generateHtmlReport(snapData, {
+            projectName: projName,
+            projectPath: reportBasePath,
+            gsdVersion,
+            milestoneId,
+            indexRelPath: "index.html",
+        }),
+        milestoneId,
+        milestoneTitle: msTitle,
+        kind: "milestone",
+        projectName: projName,
+        projectPath: reportBasePath,
+        gsdVersion,
+        totalCost: snapData.totals?.cost ?? 0,
+        totalTokens: snapData.totals?.tokens.total ?? 0,
+        totalDuration: snapData.totals?.duration ?? 0,
+        doneSlices,
+        totalSlices,
+        doneMilestones: snapData.milestones.filter((m) => m.status === "complete").length,
+        totalMilestones: snapData.milestones.length,
+        phase: snapData.phase,
+    });
+    ctx.ui.notify(`Report saved: .gsd/reports/${basename(outPath)} — open index.html to browse progression.`, "info");
+}

package/dist/resources/extensions/gsd/auto/dispatch-history.js

@@ -26,7 +26,7 @@
  * grammar itself lives in auto/dispatch-key.ts and is re-exported here for
  * import stability.
  */
-import { buildDispatchKey, normalizeDispatchKey } from "./dispatch-key.js";
+import { buildDispatchKey, normalizeDispatchKey, parseDispatchKey } from "./dispatch-key.js";
 import { detectStuck } from "./detect-stuck.js";
 import { getLatestForUnit, getRecentUnitKeysForProjectRoot, } from "../db/unit-dispatches.js";
 import { debugLog } from "../debug-logger.js";
@@ -37,12 +37,18 @@ export { buildDispatchKey, normalizeDispatchKey, parseDispatchKey } from "./disp
  * cutover (issue #5791).
  */
 export const STUCK_WINDOW_SIZE = 6;
-function lookupLatestLedgerError(unitType, unitId) {
+/**
+ * Fetch the latest dispatch ledger error for a unit, the single canonical
+ * lookup shared by the DispatchHistory window and the legacy
+ * `loopState.recentUnits` path in dispatch.ts. The ledger keys rows by the
+ * bare unit id with the unit type in its own column, so the lookup must use
+ * the bare id and require a unit_type match (a compound `type/id` key would
+ * miss the row, and another unit type's error on the same id must never be
+ * attached — it would trip the repeat-error rule spuriously).
+ */
+export function lookupLatestLedgerError(unitType, unitId) {
     try {
         const row = getLatestForUnit(unitId);
-        // The ledger keys rows by bare unit id; require a unit_type match so
-        // another unit type's error on the same id is never attached (it would
-        // trip the repeat-error rule spuriously).
         if (!row || row.unit_type !== unitType)
             return undefined;
         return row.error_summary ?? undefined;
@@ -85,7 +91,16 @@ export function createDispatchHistory(options) {
                 const persisted = getRecentUnitKeysForProjectRoot(scopeId, windowSize);
                 if (persisted.length === 0)
                     return 0;
-                window = persisted.map(({ key }) => ({ key: normalizeDispatchKey(key) }));
+                const rebuilt = [];
+                for (const { key } of persisted) {
+                    const normalized = normalizeDispatchKey(key);
+                    const parsed = parseDispatchKey(normalized);
+                    const error = parsed && rebuilt.some((entry) => entry.key === normalized)
+                        ? lookupLatestLedgerError(parsed.unitType, parsed.unitId)
+                        : undefined;
+                    rebuilt.push({ key: normalized, error });
+                }
+                window = rebuilt;
                 while (window.length > windowSize)
                     window.shift();
                 return window.length;

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

@@ -0,0 +1,365 @@
+// Project/App: gsd-pi
+// File Purpose: Auto-loop dispatch phase.
+import { detectStuck } from "./detect-stuck.js";
+import { STUCK_WINDOW_SIZE, lookupLatestLedgerError } from "./dispatch-history.js";
+import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps, refreshRecoveryDbForArtifact, } from "../auto-recovery.js";
+import { getConsecutiveDispatchBlocker } from "../dispatch-guard.js";
+import { debugLog } from "../debug-logger.js";
+import { getToolBaselineSnapshot, getRegisteredToolSnapshot, } from "../auto-model-selection.js";
+import { supportsStructuredQuestions } from "../workflow-mcp.js";
+import { isDbAvailable, getTask, getSlice } from "../gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
+import { isClosedStatus } from "../status-guards.js";
+import { parseUnitId } from "../unit-id.js";
+import { validateSourceWriteWorktreeSafety } from "./worktree-safety-phase.js";
+import { closeoutAndStop } from "./closeout.js";
+import { persistStuckRecoveryAttempts, _resolveDispatchGuardBasePath, } from "./phase-helpers.js";
+export function getAlreadyClosedDispatchReason(unitType, unitId) {
+    if (!isDbAvailable())
+        return null;
+    refreshWorkflowDatabaseFromDisk();
+    const { milestone, slice, task } = parseUnitId(unitId);
+    if (unitType === "execute-task" && milestone && slice && task) {
+        const row = getTask(milestone, slice, task);
+        return row && isClosedStatus(row.status)
+            ? `execute-task ${unitId} is already ${row.status}`
+            : null;
+    }
+    if (unitType === "complete-slice" && milestone && slice) {
+        const row = getSlice(milestone, slice);
+        return row && isClosedStatus(row.status)
+            ? `complete-slice ${unitId} is already ${row.status}`
+            : null;
+    }
+    return null;
+}
+function isUnhandledPhaseWarning(dispatchResult) {
+    return dispatchResult.action === "stop" &&
+        dispatchResult.level === "warning" &&
+        dispatchResult.matchedRule === "<no-match>" &&
+        /^Unhandled phase "/.test(dispatchResult.reason);
+}
+export { isUnhandledPhaseWarning };
+/**
+ * Phase 3: Dispatch resolution — resolve next unit, stuck detection, pre-dispatch hooks.
+ * Returns break/continue to control the loop, or next with IterationData on success.
+ */
+export async function runDispatch(ic, preData, loopState) {
+    const { ctx, pi, s, deps, prefs } = ic;
+    const { state, mid, midTitle } = preData;
+    const provider = ctx.model?.provider;
+    const authMode = provider && typeof ctx.modelRegistry?.getProviderAuthMode === "function"
+        ? ctx.modelRegistry.getProviderAuthMode(provider)
+        : undefined;
+    // Use the baseline snapshot rather than the live active-tool set: a prior
+    // unit's per-provider narrowing (hook overrides, Groq 128-tool cap, etc.)
+    // can strip required MCP tools from the live set even though
+    // selectAndApplyModel will restore them before the unit is dispatched.
+    // Checking a stale-narrowed set causes false transport-preflight warnings
+    // that repeat on every /gsd auto resume (#477 follow-up).
+    const activeTools = getToolBaselineSnapshot(pi);
+    const registeredTools = getRegisteredToolSnapshot(pi);
+    // Deep planning intentionally keeps human checkpoints in plain chat. In
+    // Claude Code/local MCP transports, structured question requests can be
+    // cancelled outside the normal chat flow, which made approval gates easy to
+    // skip or bury under tool output.
+    const structuredQuestionsAvailable = prefs?.planning_depth === "deep"
+        ? "false"
+        : supportsStructuredQuestions(activeTools, {
+            authMode,
+            baseUrl: ctx.model?.baseUrl,
+        }) ? "true" : "false";
+    debugLog("autoLoop", { phase: "dispatch-resolve", iteration: ic.iteration });
+    let dispatchResult = await deps.resolveDispatch({
+        basePath: s.basePath,
+        mid,
+        midTitle,
+        state,
+        prefs,
+        session: s,
+        structuredQuestionsAvailable,
+        sessionContextWindow: ctx.model?.contextWindow,
+        sessionProvider: ctx.model?.provider,
+        modelRegistry: ctx.modelRegistry,
+        activeTools,
+        registeredTools,
+        sessionBaseUrl: ctx.model?.baseUrl,
+        sessionAuthMode: authMode,
+    });
+    if (isUnhandledPhaseWarning(dispatchResult)) {
+        deps.invalidateAllCaches();
+        const freshState = await deps.deriveState(s.canonicalProjectRoot);
+        const freshMid = freshState.activeMilestone?.id ?? mid;
+        const freshMidTitle = freshState.activeMilestone?.title ?? freshMid ?? midTitle;
+        debugLog("autoLoop", {
+            phase: "dispatch-unhandled-phase-retry",
+            iteration: ic.iteration,
+            stalePhase: state.phase,
+            freshPhase: freshState.phase,
+        });
+        dispatchResult = await deps.resolveDispatch({
+            basePath: s.basePath,
+            mid: freshMid,
+            midTitle: freshMidTitle,
+            state: freshState,
+            prefs,
+            session: s,
+            structuredQuestionsAvailable,
+            sessionContextWindow: ctx.model?.contextWindow,
+            sessionProvider: ctx.model?.provider,
+            modelRegistry: ctx.modelRegistry,
+            activeTools,
+            registeredTools,
+            sessionBaseUrl: ctx.model?.baseUrl,
+            sessionAuthMode: authMode,
+        });
+    }
+    if (dispatchResult.action === "stop") {
+        deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "dispatch-stop", rule: dispatchResult.matchedRule, data: { reason: dispatchResult.reason } });
+        // Warning-level stops are recoverable human checkpoints (e.g. UAT verdict
+        // gate) — pause instead of hard-stopping so the session is resumable with
+        // `/gsd auto`. Error/info-level stops remain hard stops for infrastructure
+        // failures and terminal conditions respectively.
+        // See: https://github.com/open-gsd/gsd-pi/issues/2474
+        if (dispatchResult.level === "warning") {
+            ctx.ui.notify(dispatchResult.reason, "warning");
+            await deps.pauseAuto(ctx, pi, {
+                message: dispatchResult.reason,
+                category: "unknown",
+            });
+        }
+        else {
+            await closeoutAndStop(ctx, pi, s, deps, dispatchResult.reason);
+        }
+        debugLog("autoLoop", { phase: "exit", reason: "dispatch-stop" });
+        return { action: "break", reason: "dispatch-stop" };
+    }
+    if (dispatchResult.action !== "dispatch") {
+        // Non-dispatch action (e.g. "skip") — re-derive state
+        await new Promise((r) => setImmediate(r));
+        return { action: "continue" };
+    }
+    let unitType = dispatchResult.unitType;
+    let unitId = dispatchResult.unitId;
+    let prompt = dispatchResult.prompt;
+    let pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
+    let dispatchState = state;
+    let dispatchMid = mid;
+    let dispatchMidTitle = midTitle;
+    const pendingRetryDispatch = s.pendingVerificationRetryDispatch;
+    if (pendingRetryDispatch) {
+        unitType = pendingRetryDispatch.unitType;
+        unitId = pendingRetryDispatch.unitId;
+        prompt = pendingRetryDispatch.prompt;
+        pauseAfterUatDispatch = pendingRetryDispatch.pauseAfterUatDispatch;
+        dispatchState = pendingRetryDispatch.state;
+        dispatchMid = pendingRetryDispatch.mid ?? mid;
+        dispatchMidTitle = pendingRetryDispatch.midTitle ?? midTitle;
+        s.pendingVerificationRetryDispatch = null;
+        debugLog("autoLoop", {
+            phase: "dispatch-pending-verification-retry",
+            unitType,
+            unitId,
+        });
+    }
+    const alreadyClosedReason = getAlreadyClosedDispatchReason(unitType, unitId);
+    if (alreadyClosedReason) {
+        s.pendingVerificationRetry = null;
+        loopState.recentUnits = [];
+        loopState.stuckRecoveryAttempts = Math.max(loopState.stuckRecoveryAttempts, 1);
+        deps.invalidateAllCaches();
+        debugLog("autoLoop", {
+            phase: "dispatch-skip-already-closed",
+            unitType,
+            unitId,
+            reason: alreadyClosedReason,
+        });
+        deps.emitJournalEvent({
+            ts: new Date().toISOString(),
+            flowId: ic.flowId,
+            seq: ic.nextSeq(),
+            eventType: "guard-block",
+            data: { unitType, unitId, reason: alreadyClosedReason },
+        });
+        ctx.ui.notify(`Skipping ${unitType} ${unitId}: ${alreadyClosedReason}.`, "info");
+        await new Promise((r) => setImmediate(r));
+        return { action: "continue" };
+    }
+    deps.emitJournalEvent({
+        ts: new Date().toISOString(),
+        flowId: ic.flowId,
+        seq: ic.nextSeq(),
+        eventType: "dispatch-match",
+        rule: pendingRetryDispatch ? "verification-retry" : dispatchResult.matchedRule,
+        data: { unitType, unitId },
+    });
+    // Resolve hooks and prior-slice gating before health/stuck accounting so
+    // those checks run against the final dispatch unit.
+    const preDispatchResult = deps.runPreDispatchHooks(unitType, unitId, prompt, s.basePath);
+    if (preDispatchResult.firedHooks.length > 0) {
+        ctx.ui.notify(`Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`, "info");
+        deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "pre-dispatch-hook", data: { firedHooks: preDispatchResult.firedHooks, action: preDispatchResult.action } });
+    }
+    if (preDispatchResult.action === "skip") {
+        ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
+        await new Promise((r) => setImmediate(r));
+        return { action: "continue" };
+    }
+    if (preDispatchResult.action === "replace") {
+        prompt = preDispatchResult.prompt ?? prompt;
+        if (preDispatchResult.unitType)
+            unitType = preDispatchResult.unitType;
+    }
+    else if (preDispatchResult.prompt) {
+        prompt = preDispatchResult.prompt;
+    }
+    const guardBasePath = _resolveDispatchGuardBasePath(s);
+    let mainBranch = "main";
+    try {
+        mainBranch = deps.getMainBranch(guardBasePath);
+    }
+    catch (err) {
+        debugLog("autoLoop", { phase: "getMainBranch-failed", error: String(err) });
+    }
+    const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(guardBasePath, mainBranch, unitType, unitId);
+    if (priorSliceBlocker) {
+        await deps.stopAuto(ctx, pi, priorSliceBlocker);
+        debugLog("autoLoop", { phase: "exit", reason: "prior-slice-blocker" });
+        return { action: "break", reason: "prior-slice-blocker" };
+    }
+    const consecutiveDispatchBlocker = getConsecutiveDispatchBlocker(loopState, state.phase, unitType, unitId);
+    if (consecutiveDispatchBlocker) {
+        await deps.stopAuto(ctx, pi, consecutiveDispatchBlocker);
+        debugLog("autoLoop", { phase: "exit", reason: "consecutive-dispatch-blocker" });
+        return { action: "break", reason: "consecutive-dispatch-blocker" };
+    }
+    const worktreeSafetyBlock = await validateSourceWriteWorktreeSafety(ic, unitType, unitId, mid, "pre-dispatch");
+    if (worktreeSafetyBlock)
+        return worktreeSafetyBlock;
+    // ── Sliding-window stuck detection with graduated recovery ──
+    const derivedKey = `${unitType}/${unitId}`;
+    // Always record this dispatch in the sliding window and run detection so
+    // Rules 1/3/4 can catch retry loops with repeated failure content (#5719).
+    // Rules 2/2b suppress legitimate retry backoff through the dispatch ledger.
+    //
+    // Mirror DispatchHistory.recordDispatch: attach the latest ledger error
+    // only on a repeat (the key already exists in the window) so a first
+    // dispatch never trips the repeat-error rule, and first-dispatch advances
+    // (the common path) pay zero DB cost. The ledger keys rows by the bare unit
+    // id with the unit type in its own column, so look up by (unitType, unitId)
+    // — the compound `derivedKey` would miss the row and silently drop
+    // repeat-error detection here. derivedKey stays the window-entry key.
+    const recentError = loopState.recentUnits.some((entry) => entry.key === derivedKey)
+        ? lookupLatestLedgerError(unitType, unitId)
+        : undefined;
+    loopState.recentUnits.push({ key: derivedKey, error: recentError });
+    while (loopState.recentUnits.length > STUCK_WINDOW_SIZE) {
+        loopState.recentUnits.shift();
+    }
+    const stuckSignal = detectStuck(loopState.recentUnits, {
+        pendingRetry: !!s.pendingVerificationRetry,
+        retryAttempt: s.pendingVerificationRetry?.attempt,
+    });
+    if (stuckSignal) {
+        debugLog("autoLoop", {
+            phase: "stuck-check",
+            unitType,
+            unitId,
+            reason: stuckSignal.reason,
+            recoveryAttempts: loopState.stuckRecoveryAttempts,
+        });
+        if (loopState.stuckRecoveryAttempts === 0) {
+            // Level 1: try verifying the artifact, then cache invalidation + retry
+            loopState.stuckRecoveryAttempts++;
+            persistStuckRecoveryAttempts(s, loopState);
+            const artifactExists = verifyExpectedArtifact(unitType, unitId, s.basePath);
+            if (artifactExists) {
+                debugLog("autoLoop", {
+                    phase: "stuck-recovery",
+                    level: 1,
+                    action: "artifact-found",
+                });
+                const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId, s.basePath);
+                if (!recoveryDb.ok) {
+                    ctx.ui.notify(recoveryDb.fatal
+                        ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                        : `${recoveryDb.message} Keeping stuck state for retry.`, "warning");
+                    if (recoveryDb.fatal) {
+                        await deps.pauseAuto(ctx, pi);
+                        return { action: "break", reason: recoveryDb.reason };
+                    }
+                    return { action: "continue" };
+                }
+                ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk. Invalidating caches.`, "info");
+                deps.invalidateAllCaches();
+                loopState.recentUnits.length = 0;
+                return { action: "continue" };
+            }
+            ctx.ui.notify(`Stuck on ${unitType} ${unitId} (${stuckSignal.reason}). Invalidating caches and retrying.`, "warning");
+            deps.invalidateAllCaches();
+        }
+        else {
+            // Level 2: hard stop — genuinely stuck
+            deps.invalidateAllCaches();
+            const artifactExists = verifyExpectedArtifact(unitType, unitId, s.basePath);
+            if (artifactExists) {
+                debugLog("autoLoop", {
+                    phase: "stuck-recovery",
+                    level: 2,
+                    action: "artifact-found",
+                });
+                const recoveryDb = refreshRecoveryDbForArtifact(unitType, unitId, s.basePath);
+                if (recoveryDb.ok) {
+                    ctx.ui.notify(`Stuck recovery: artifact for ${unitType} ${unitId} found on disk after cache invalidation. Continuing.`, "info");
+                    loopState.recentUnits.length = 0;
+                    return { action: "continue" };
+                }
+                ctx.ui.notify(recoveryDb.fatal
+                    ? `${recoveryDb.message} Pausing auto-mode for manual recovery.`
+                    : `${recoveryDb.message} Stopping for manual recovery.`, "warning");
+                if (recoveryDb.fatal) {
+                    await deps.pauseAuto(ctx, pi);
+                    return { action: "break", reason: recoveryDb.reason };
+                }
+            }
+            debugLog("autoLoop", {
+                phase: "stuck-detected",
+                unitType,
+                unitId,
+                reason: stuckSignal.reason,
+            });
+            const stuckDiag = diagnoseExpectedArtifact(unitType, unitId, s.basePath);
+            const stuckRemediation = buildLoopRemediationSteps(unitType, unitId, s.basePath);
+            const stuckParts = [`Stuck on ${unitType} ${unitId} — ${stuckSignal.reason}.`];
+            if (stuckDiag)
+                stuckParts.push(`Expected: ${stuckDiag}`);
+            if (stuckRemediation)
+                stuckParts.push(`To recover:\n${stuckRemediation}`);
+            ctx.ui.notify(stuckParts.join(" "), "error");
+            await deps.stopAuto(ctx, pi, `Stuck: ${stuckSignal.reason}`);
+            return { action: "break", reason: "stuck-detected" };
+        }
+    }
+    else {
+        // Progress detected — reset recovery counter
+        if (loopState.stuckRecoveryAttempts > 0) {
+            debugLog("autoLoop", {
+                phase: "stuck-counter-reset",
+                from: loopState.recentUnits[loopState.recentUnits.length - 2]?.key ?? "",
+                to: derivedKey,
+            });
+            loopState.stuckRecoveryAttempts = 0;
+            persistStuckRecoveryAttempts(s, loopState);
+        }
+    }
+    return {
+        action: "next",
+        data: {
+            unitType, unitId, prompt, finalPrompt: prompt,
+            pauseAfterUatDispatch,
+            state: dispatchState, mid: dispatchMid, midTitle: dispatchMidTitle,
+            isRetry: Boolean(pendingRetryDispatch), previousTier: undefined,
+            hookModelOverride: preDispatchResult.model,
+        },
+    };
+}