@tea-agent/loop-agent 0.39.0-beta.2 → 0.39.0-beta.3

package/dist/workflows/dag/rerun-plan.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { assertTaskContractBindingFresh } from "./task-contract-binding.js";
 import { isSafeReadOnlyPiRetryCandidate, isTransportCrashedExclusiveWriter } from "./retry-policy.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { composeDagPromptOverridePrompt, MAX_DAG_RERUN_PROMPT_OVERRIDE_CHARS, } from "../../shared/dag-prompt-override.js";
 const REVIEW_VERDICT_RECOVERY_NODE_ID = "review-verdict-recovery-pi";
 const SAFE_SHELL_GATE_KEYS = [
     "verdictGate",
@@ -159,12 +160,16 @@ function isCanonicalGeneratedVerifyShell(task) {
         return false;
     if (shell.projectGovernanceGate)
         return false;
-    if (shell.frontendPrewriteGate)
+    if (shell.frontendDesignPolicy)
+        return false;
+    if (shell.frontendWriterAdmission)
         return false;
     if (shell.frontendVerificationBundle)
         return false;
     if (shell.frontendReviewContext)
         return false;
+    if (shell.frontendCloseout)
+        return false;
     if (shell.backendTestPipeline)
         return false;
     if (shell.nonZeroExitPolicy === "record")
@@ -190,12 +195,16 @@ function isSafeGateOnlyShell(task) {
         return false;
     if (shell.preset)
         return false;
-    if (shell.frontendPrewriteGate)
+    if (shell.frontendDesignPolicy)
+        return false;
+    if (shell.frontendWriterAdmission)
         return false;
     if (shell.frontendVerificationBundle)
         return false;
     if (shell.frontendReviewContext)
         return false;
+    if (shell.frontendCloseout)
+        return false;
     if (shell.backendTestPipeline)
         return false;
     if (shell.verifyEvidence)
@@ -306,6 +315,9 @@ export function computeResetClosure(spec, effectiveFromNodeId) {
         ...collectReachableDescendants(spec, effectiveFromNodeId),
     ].sort();
 }
+function isNeverStartedNodeStatus(status) {
+    return status === undefined || status === "SKIPPED" || status === "PENDING";
+}
 export function assessResetClosureSafety(spec, resetNodeIds, options = {}) {
     const tasks = taskById(spec);
     const blockingNodes = [];
@@ -314,9 +326,17 @@ export function assessResetClosureSafety(spec, resetNodeIds, options = {}) {
         const task = tasks.get(nodeId);
         if (!task)
             continue;
+        if (options.parentNodes !== undefined &&
+            isNeverStartedNodeStatus(options.parentNodes[nodeId]?.status)) {
+            continue;
+        }
         if (isWriterTask(task, spec)) {
             if (nodeId === options.allowedTransportWriterNodeId)
                 continue;
+            if (nodeId === options.allowedExclusiveShellFromNodeId &&
+                task.executor === "shell") {
+                continue;
+            }
             blockingNodes.push({
                 nodeId,
                 reasonCode: "restart-subgraph-contains-writer",
@@ -370,6 +390,100 @@ export function assessResetClosureSafety(spec, resetNodeIds, options = {}) {
         reasonCodes: [...new Set(reasonCodes)],
     };
 }
+/**
+ * Experimental prompt-override admission (fail-closed):
+ * - requires the internal switch (see shared/dag-prompt-override.ts);
+ * - the target must be a failed (ERROR) node inside the reset closure, so an
+ *   override can only adjust how an already-failed node retries — never a
+ *   finished, skipped, or not-yet-started node;
+ * - only `subtask_prompt` semantics change: "append" keeps the frozen base
+ *   and adds a marked addendum block, "replace" swaps the whole prompt;
+ *   base/final sha256 are recorded for provenance and bound into planHash.
+ */
+function assessPromptOverrides(input) {
+    const blockingNodes = [];
+    const reasonCodes = [];
+    const tasks = taskById(input.spec);
+    const resetSet = new Set(input.resetNodeIds);
+    const seen = new Set();
+    const entries = [];
+    if (!input.enabled) {
+        reasonCodes.push("prompt-override-disabled");
+    }
+    for (const override of input.overrides) {
+        const nodeId = override.nodeId?.trim() ?? "";
+        if (seen.has(nodeId)) {
+            blockingNodes.push({
+                nodeId,
+                reasonCode: "prompt-override-duplicate-node",
+            });
+            reasonCodes.push("prompt-override-duplicate-node");
+            continue;
+        }
+        seen.add(nodeId);
+        const task = tasks.get(nodeId);
+        if (!task) {
+            blockingNodes.push({
+                nodeId,
+                reasonCode: "prompt-override-node-missing",
+            });
+            reasonCodes.push("prompt-override-node-missing");
+            continue;
+        }
+        if (!resetSet.has(nodeId)) {
+            blockingNodes.push({
+                nodeId,
+                reasonCode: "prompt-override-outside-reset-closure",
+            });
+            reasonCodes.push("prompt-override-outside-reset-closure");
+            continue;
+        }
+        if (input.state.nodes[nodeId]?.status !== "ERROR") {
+            blockingNodes.push({
+                nodeId,
+                reasonCode: "prompt-override-node-not-failed",
+            });
+            reasonCodes.push("prompt-override-node-not-failed");
+            continue;
+        }
+        const mode = override.mode === "append" ? "append" : "replace";
+        const prompt = override.prompt ?? "";
+        if (!prompt.trim() ||
+            prompt.length > MAX_DAG_RERUN_PROMPT_OVERRIDE_CHARS) {
+            blockingNodes.push({
+                nodeId,
+                reasonCode: "prompt-override-invalid-prompt",
+            });
+            reasonCodes.push("prompt-override-invalid-prompt");
+            continue;
+        }
+        const basePromptSha256 = createHash("sha256")
+            .update(task.subtask_prompt, "utf8")
+            .digest("hex");
+        const finalPrompt = composeDagPromptOverridePrompt({
+            basePrompt: task.subtask_prompt,
+            text: prompt,
+            mode,
+        });
+        const promptSha256 = createHash("sha256")
+            .update(finalPrompt, "utf8")
+            .digest("hex");
+        if (promptSha256 === basePromptSha256) {
+            blockingNodes.push({
+                nodeId,
+                reasonCode: "prompt-override-unchanged",
+            });
+            reasonCodes.push("prompt-override-unchanged");
+            continue;
+        }
+        entries.push({ nodeId, mode, basePromptSha256, promptSha256 });
+    }
+    return {
+        entries: entries.length > 0 ? entries : undefined,
+        blockingNodes,
+        reasonCodes: [...new Set(reasonCodes)],
+    };
+}
 export function computePlanHash(planWithoutHash) {
     const canonical = JSON.stringify(sortKeysDeep(planWithoutHash));
     return createHash("sha256").update(canonical, "utf8").digest("hex");
@@ -594,9 +708,17 @@ export async function evaluateDagRerunPlan(input) {
             blockedReasons.push("ambiguous-skipped-rewrite");
         }
     }
-    const closureSafety = assessResetClosureSafety(input.parentSpec, resetNodeIds, transportWriterRestart && effectiveFromNodeId
-        ? { allowedTransportWriterNodeId: effectiveFromNodeId }
-        : {});
+    const closureSafety = assessResetClosureSafety(input.parentSpec, resetNodeIds, {
+        ...(transportWriterRestart && effectiveFromNodeId
+            ? { allowedTransportWriterNodeId: effectiveFromNodeId }
+            : {}),
+        parentNodes: input.parentState.nodes,
+        ...(effectiveFromNodeId &&
+            effectiveTask?.executor === "shell" &&
+            effectiveRecord?.status === "ERROR"
+            ? { allowedExclusiveShellFromNodeId: effectiveFromNodeId }
+            : {}),
+    });
     blockingNodes.push(...closureSafety.blockingNodes);
     for (const code of closureSafety.reasonCodes) {
         reasonCodes.push(code);
@@ -629,6 +751,22 @@ export async function evaluateDagRerunPlan(input) {
             blockingNodes.push({ nodeId, reasonCode: "parent-facts-invalid" });
         }
     }
+    let promptOverrideEntries;
+    if (input.promptOverrides !== undefined && input.promptOverrides.length > 0) {
+        const overrideAssessment = assessPromptOverrides({
+            spec: input.parentSpec,
+            state: input.parentState,
+            resetNodeIds,
+            overrides: input.promptOverrides,
+            enabled: input.promptOverrideEnabled === true,
+        });
+        blockingNodes.push(...overrideAssessment.blockingNodes);
+        for (const code of overrideAssessment.reasonCodes) {
+            reasonCodes.push(code);
+            blockedReasons.push(code);
+        }
+        promptOverrideEntries = overrideAssessment.entries;
+    }
     const uniqueReasonCodes = [...new Set(reasonCodes)];
     const uniqueBlockedReasons = [...new Set(blockedReasons)];
     const eligible = uniqueBlockedReasons.length === 0 &&
@@ -672,6 +810,7 @@ export async function evaluateDagRerunPlan(input) {
             parentLifecycle: input.parentLifecycle,
             workerManaged: input.workerManaged,
         }),
+        ...(promptOverrideEntries ? { promptOverrides: promptOverrideEntries } : {}),
     };
     return {
         ...planWithoutHash,

package/dist/workflows/dag/rerun-run.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { access, copyFile, mkdir, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { composeDagPromptOverridePrompt, isDagRerunPromptOverrideEnabled, } from "../../shared/dag-prompt-override.js";
 import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { readControllerIdentityArtifact, captureControllerIdentity } from "./controller-identity.js";
 import { DAG_RUNS_DIR, getDagRunDir, isDagNonExecutionLifecycle, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
@@ -190,6 +191,8 @@ export async function planDagRerun(input) {
             parentSpec: nonCompletedSpec,
             parentState: nonCompletedState,
             parentLifecycle,
+            promptOverrides: input.promptOverrides,
+            promptOverrideEnabled: isDagRerunPromptOverrideEnabled(),
             workerManaged: nonCompletedWorkerHints.workerManaged,
             workerAssociation: nonCompletedWorkerHints.workerManaged
                 ? {
@@ -229,6 +232,8 @@ export async function planDagRerun(input) {
         parentTerminalWorkspace,
         currentWorkspace,
         skillSnapshotOk,
+        promptOverrides: input.promptOverrides,
+        promptOverrideEnabled: isDagRerunPromptOverrideEnabled(),
         workerManaged: workerHints.workerManaged,
         workerAssociation: workerHints.workerManaged
             ? {
@@ -384,15 +389,57 @@ function buildPendingNodeRecord(task) {
         ...(task.outputMode ? { outputMode: task.outputMode } : {}),
     };
 }
+/**
+ * Stage the continuation spec with operator prompt overrides applied. The
+ * parent spec stays frozen; every override must match the plan entry (sha256
+ * of the composed final prompt and of the parent base prompt) so the
+ * two-phase planHash remains the single source of truth for what changed.
+ * "append" entries keep the frozen base and append the operator addendum in a
+ * marked block; "replace" entries swap the whole prompt.
+ */
+function applyPromptOverridesToSpec(input) {
+    const planned = new Map((input.plan.promptOverrides ?? []).map((entry) => [entry.nodeId, entry]));
+    const spec = structuredClone(input.spec);
+    for (const override of input.overrides) {
+        const entry = planned.get(override.nodeId);
+        if (!entry) {
+            throw new Error(`prompt override is not present in the rerun plan: ${override.nodeId}`);
+        }
+        const task = spec.tasks.find((candidate) => candidate.id === override.nodeId);
+        if (!task) {
+            throw new Error(`prompt override node missing from spec: ${override.nodeId}`);
+        }
+        if (sha256Hex(task.subtask_prompt) !== entry.basePromptSha256) {
+            throw new Error(`prompt override base prompt drifted from plan: ${override.nodeId}`);
+        }
+        const finalPrompt = composeDagPromptOverridePrompt({
+            basePrompt: task.subtask_prompt,
+            text: override.prompt,
+            mode: override.mode === "append" ? "append" : "replace",
+        });
+        if (sha256Hex(finalPrompt) !== entry.promptSha256) {
+            throw new Error(`prompt override text does not match the planned sha256: ${override.nodeId}`);
+        }
+        task.subtask_prompt = finalPrompt;
+    }
+    return spec;
+}
 async function stageContinuationRun(input) {
-    const { ranks } = topoSortToRanks(input.parentSpec);
-    const runId = await buildDagRunId(input.parentSpec, { cwd: input.cwd });
+    const specForRun = input.promptOverrides !== undefined && input.promptOverrides.length > 0
+        ? applyPromptOverridesToSpec({
+            spec: input.parentSpec,
+            plan: input.plan,
+            overrides: input.promptOverrides,
+        })
+        : input.parentSpec;
+    const { ranks } = topoSortToRanks(specForRun);
+    const runId = await buildDagRunId(specForRun, { cwd: input.cwd });
     const runDir = getDagRunDir(input.cwd, "active", runId);
     await prepareActiveRunDir(runDir);
-    await writeRunSpec(runDir, input.parentSpec);
+    await writeRunSpec(runDir, specForRun);
     const resetSet = new Set(input.plan.resetNodeIds);
     const importedSet = new Set(input.plan.importedNodeIds);
-    const tasksById = new Map(input.parentSpec.tasks.map((task) => [task.id, task]));
+    const tasksById = new Map(specForRun.tasks.map((task) => [task.id, task]));
     const importManifestNodes = [];
     const nodes = {};
     for (const nodeId of input.plan.importedNodeIds) {
@@ -433,6 +480,9 @@ async function stageContinuationRun(input) {
         reason: input.reason,
         requestId: input.requestId,
         planHash: input.plan.planHash,
+        ...(input.plan.promptOverrides
+            ? { promptOverrides: input.plan.promptOverrides }
+            : {}),
         createdAt,
     };
     const state = {
@@ -482,7 +532,7 @@ async function stageContinuationRun(input) {
     await writeJsonAtomic(path.join(runDir, IMPORT_MANIFEST_REL_PATH), importManifest);
     await writeJsonAtomic(path.join(runDir, RERUN_PLAN_REL_PATH), input.plan);
     await writeRunState(runDir, state);
-    return { runId, runDir, state };
+    return { runId, runDir, state, spec: specForRun };
 }
 export async function executeDagRerun(input) {
     const existing = await readExistingOperatorRequest(input.cwd, input.requestId);
@@ -493,6 +543,7 @@ export async function executeDagRerun(input) {
         cwd: input.cwd,
         parentRunId: input.parentRunId,
         selectedNodeId: input.selectedNodeId,
+        promptOverrides: input.promptOverrides,
     });
     if (plan.planHash !== input.planHash) {
         return {
@@ -530,10 +581,11 @@ export async function executeDagRerun(input) {
         plan,
         reason: input.reason,
         requestId: input.requestId,
+        promptOverrides: input.promptOverrides,
     });
     const continuationOptions = {
         cwd: input.cwd,
-        spec: parentSpec,
+        spec: staged.spec,
         state: staged.state,
         runDir: staged.runDir,
         ...(input.maxConcurrent !== undefined

package/dist/workflows/dag/retry-policy.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { projectProtocolFailureReason, } from "./frontend-recovery-capsule.js";
+import { TYPED_EVENT_FACT_KINDS } from "./frontend-typed-event-store.js";
 /**
  * Failure categories that are safe to auto-retry for read-only Pi nodes.
  *
@@ -165,6 +167,36 @@ export const WRITER_TRANSPORT_RETRY_POLICY = {
     maxDelayMs: 30000,
     retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
 };
+/**
+ * Implicit runtime retry for canonical final verify shells. Not a DagRetryPolicy:
+ * `spawn-error` / `test-timeout` are runtime command categories and must not enter
+ * `dagRetryPolicySchema` / `ALL_DAG_RETRY_CATEGORIES`.
+ */
+export const VERIFY_SHELL_RETRY_CATEGORIES = [
+    "timeout",
+    "spawn-error",
+    "test-timeout",
+];
+export const VERIFY_SHELL_RETRY_POLICY = {
+    maxAttempts: 2,
+    backoff: "exponential",
+    initialDelayMs: 2000,
+    maxDelayMs: 30000,
+    retryCategories: VERIFY_SHELL_RETRY_CATEGORIES,
+};
+export const TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE = "standard-reviewed-supervised-v1";
+/**
+ * Target-template exclusive implement-pi transport retry. Same schema category
+ * as frontend (`writer-clean-timeout`) so DagSpec validation stays unchanged;
+ * only the delay cap is wider. Do not mutate {@link WRITER_TRANSPORT_RETRY_POLICY}.
+ */
+export const TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY = {
+    maxAttempts: 2,
+    backoff: "exponential",
+    initialDelayMs: 5000,
+    maxDelayMs: 60000,
+    retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
+};
 /**
  * Backend-test generation writers: empty-diff once, plus bounded incomplete-write-set
  * recovery attempts driven by Completeness Gate (missing/broken target files).
@@ -229,15 +261,77 @@ export function isWriterEmptyDiffRetryCandidate(task) {
         task.writerOutcomePolicy?.requireChangedFiles === true);
 }
 /**
- * Standard exclusive implementers (implementation-outcome writers) may take a
- * single clean-timeout transport retry. Backend completeness writers already
- * have their own policy and are excluded here.
+ * Standard exclusive implementers (implementation-outcome and frontend-facts
+ * writers) may take a single clean-timeout transport retry. Backend
+ * completeness writers already have their own policy and are excluded here.
  */
 export function isWriterTransportRetryCandidate(task) {
     return (isExclusivePiImplementer(task) &&
-        task.writerOutcomePolicy?.type === "implementation-outcome-v1" &&
+        (task.writerOutcomePolicy?.type === "implementation-outcome-v1" ||
+            task.writerOutcomePolicy?.type === "frontend-facts-v1") &&
         task.writerOutcomePolicy.requireChangedFiles !== true);
 }
+/**
+ * Canonical standard exclusive `implement-pi` only. Frontend designers and
+ * completeness writers stay on the existing timeout-only transport candidate.
+ */
+export function isTargetTemplateImplementPi(task) {
+    return isWriterTransportRetryCandidate(task) && task.id === "implement-pi";
+}
+export function hasTargetTemplateTransientRetryProfile(task) {
+    return (task?.transientRetryProfile === TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE);
+}
+/**
+ * Dual-condition eligibility: canonical shape AND generated-path stamp.
+ * Custom / other-template nodes that only match id or shape stay ineligible.
+ */
+export function isTargetTemplateTransientRetryNode(task) {
+    if (!hasTargetTemplateTransientRetryProfile(task))
+        return false;
+    return (isCanonicalFinalVerifyShellRetryCandidate(task) ||
+        isTargetTemplateImplementPi(task));
+}
+/**
+ * Shape-based eligibility for implicit canonical final verify-shell retry.
+ * Does not consult node id or a template field.
+ */
+export function isCanonicalFinalVerifyShellRetryCandidate(task) {
+    if (task.executor !== "shell")
+        return false;
+    if (task.role !== "verifier")
+        return false;
+    if (task.writePolicy !== undefined &&
+        task.writePolicy !== "read-only" &&
+        task.writePolicy !== "none") {
+        return false;
+    }
+    if ((task.writeSet?.length ?? 0) > 0)
+        return false;
+    const shell = task.shell;
+    if (!shell || (shell.commands?.length ?? 0) === 0)
+        return false;
+    const evidence = shell.verifyEvidence;
+    if (!evidence)
+        return false;
+    if (evidence.phase !== "final")
+        return false;
+    if (evidence.quota !== "full")
+        return false;
+    if (evidence.commandSource !== "adapter")
+        return false;
+    if (evidence.finalFullRequired !== true)
+        return false;
+    if (shell.frontendPrewriteGate ||
+        shell.frontendVerificationBundle ||
+        shell.frontendBrowserToolPreflight ||
+        shell.backendTestPipeline ||
+        shell.jacocoCoverage ||
+        shell.repairArtifactGate ||
+        shell.verdictGate) {
+        return false;
+    }
+    return true;
+}
 export function isSafeReadOnlyPiRetryCandidate(task) {
     if (task.executor !== "pi")
         return false;
@@ -279,3 +373,133 @@ export function computeBackoffDelayMs(attemptNumber, policy) {
     const raw = policy.initialDelayMs * 2 ** exponent;
     return Math.min(raw, policy.maxDelayMs);
 }
+/**
+ * A+B (AC-001/AC-005): project raw executor signals to the canonical 7-value
+ * protocol failure reason. Specific signals win first, then the existing
+ * alias/enum passthrough; unknown signals fail closed to `undefined`.
+ */
+export function projectFrontendNodeProtocolFailureReason(input) {
+    // 1. length stop reason without a terminal → length-before-terminal.
+    if (input.stopReason === "length" && input.hasTerminalFact === false) {
+        return "length-before-terminal";
+    }
+    // 2. timeout with reasoning-side evidence → reasoning-timeout.
+    if (input.failureCategory === "timeout" &&
+        /(?:reasoning|thinking|thought)/i.test(input.assistantText ?? "")) {
+        return "reasoning-timeout";
+    }
+    // 3. empty output without a terminal → provider-ended-without-terminal.
+    if (input.failureCategory === "empty-output" &&
+        input.hasTerminalFact === false) {
+        return "provider-ended-without-terminal";
+    }
+    // 4. Alias/enum passthrough; unknown fails closed to undefined.
+    return projectProtocolFailureReason(input.failureCategory ?? "");
+}
+export const FRONTEND_PLAN_LADDER = [
+    "normal",
+    "compact-terminal-first",
+    "bounded-tool-only",
+    "backup-model",
+];
+/**
+ * Map a 7-value protocol failure reason to the closest provider capability
+ * fact kind for backup-model routing. `unsupported-tool-capability` is a
+ * protocol reason, not a provider capability kind, so it is deliberately NOT
+ * a valid route (fail-closed to `unsupported-provider-capability`).
+ */
+export function frontendPlanProtocolReasonToCapabilityKind(reason) {
+    switch (reason) {
+        case "length-before-terminal":
+            return "length-before-terminal";
+        case "reasoning-timeout":
+            return "reasoning-timeout";
+        case "provider-ended-without-terminal":
+            return "provider-ended-without-terminal";
+        case "terminal-event-missing":
+        case "terminal-conflict":
+            return "terminal-commit";
+        case "typed-fact-invalid":
+            return "read-only-fact-channel";
+        case "unsupported-tool-capability":
+            return "unsupported-tool-capability";
+        default:
+            return undefined;
+    }
+}
+/**
+ * A+B (AC-003): resolve a backup-model route against the frozen seven-kind
+ * provider capability catalog (the exact set `routeFrontendProviderCapability`
+ * consults). `unsupported-tool-capability` is a protocol reason, not a
+ * provider capability kind, so it (and any unmapped reason) fails closed to
+ * `unsupported-provider-capability` — never swapped for the 7-value reason.
+ */
+export function resolveFrontendPlanBackupRoute(reason) {
+    const factKind = frontendPlanProtocolReasonToCapabilityKind(reason);
+    if (!factKind) {
+        return { ok: false, reason: "unsupported-provider-capability" };
+    }
+    return TYPED_EVENT_FACT_KINDS.includes(factKind)
+        ? { ok: true, factKind }
+        : { ok: false, reason: "unsupported-provider-capability" };
+}
+/**
+ * A+B (AC-002): deterministic ladder resolution. Reason-mandated upgrades
+ * (length → compact-terminal-first; terminal/timeout/empty → bounded-tool-only)
+ * never regress below the current rung. A repeated failure fingerprint with no
+ * new committed fact escalates one rung instead of re-running the same step;
+ * at `backup-model` that becomes `non-converging`, and an unavailable backup
+ * provider route fails closed to `unsupported-provider-capability`.
+ */
+export function resolveFrontendPlanRetryStep(input) {
+    if (input.currentStep === "non-converging" ||
+        input.currentStep === "unsupported-provider-capability") {
+        return input.currentStep;
+    }
+    const currentIndex = FRONTEND_PLAN_LADDER.indexOf(input.currentStep);
+    const reasonStep = reasonMandatedFrontendPlanRetryStep(input.protocolFailureReason);
+    const reasonIndex = reasonStep
+        ? FRONTEND_PLAN_LADDER.indexOf(reasonStep)
+        : -1;
+    let nextIndex = Math.max(currentIndex, reasonIndex);
+    const repeated = input.priorFingerprints.includes(input.fingerprint);
+    if (repeated && !input.hasNewCommittedFact) {
+        nextIndex = Math.max(nextIndex, currentIndex + 1);
+    }
+    const nextStep = nextIndex >= FRONTEND_PLAN_LADDER.length
+        ? "non-converging"
+        : (FRONTEND_PLAN_LADDER[nextIndex] ?? "non-converging");
+    if (nextStep === "backup-model" && input.backupRouteAvailable === false) {
+        return "unsupported-provider-capability";
+    }
+    return nextStep;
+}
+function reasonMandatedFrontendPlanRetryStep(reason) {
+    switch (reason) {
+        case "length-before-terminal":
+            return "compact-terminal-first";
+        case "terminal-event-missing":
+        case "reasoning-timeout":
+        case "provider-ended-without-terminal":
+            return "bounded-tool-only";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Opt-in retry policy mounted on the frontend-plan-pi node. maxAttempts=5 is
+ * the schema cap, matching the four-rung ladder plus one non-converging stop.
+ * `invalid-output` (typed-fact schema violations, e.g. verification targets
+ * referencing undeclared UI states) retries at the `normal` rung with the
+ * contractCheck reason injected via `<retry_instruction>` (§5.1 ladder).
+ */
+export const FRONTEND_PLAN_LADDER_RETRY_POLICY = {
+    maxAttempts: 5,
+    backoff: "exponential",
+    initialDelayMs: 2000,
+    maxDelayMs: 30000,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    ],
+};