@tea-agent/loop-agent 0.39.0-beta.0 → 0.39.0-beta.10

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";
@@ -11,6 +12,7 @@ import { prepareActiveRunDir, writeNodeRecord, writeRunSpec, writeRunState, } fr
 import { cloneParentSkillSnapshotForContinuation, readSkillSnapshot, } from "./skill-snapshot.js";
 import { topoSortToRanks } from "./topo.js";
 import { captureWorkspaceCheckpoint, readWorkspaceCheckpoint, WORKSPACE_CHECKPOINT_START_REL, WORKSPACE_CHECKPOINT_TERMINAL_REL, writeWorkspaceCheckpoint, } from "./workspace-checkpoint.js";
+import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, } from "./recovery-lease.js";
 export const RERUN_PLAN_REL_PATH = ".runtime/rerun-plan.json";
 export const IMPORT_MANIFEST_REL_PATH = ".runtime/import-manifest.json";
 export const WORKER_ASSOCIATION_REL_PATH = ".runtime/worker-association.json";
@@ -190,6 +192,8 @@ export async function planDagRerun(input) {
             parentSpec: nonCompletedSpec,
             parentState: nonCompletedState,
             parentLifecycle,
+            promptOverrides: input.promptOverrides,
+            promptOverrideEnabled: isDagRerunPromptOverrideEnabled(),
             workerManaged: nonCompletedWorkerHints.workerManaged,
             workerAssociation: nonCompletedWorkerHints.workerManaged
                 ? {
@@ -229,6 +233,8 @@ export async function planDagRerun(input) {
         parentTerminalWorkspace,
         currentWorkspace,
         skillSnapshotOk,
+        promptOverrides: input.promptOverrides,
+        promptOverrideEnabled: isDagRerunPromptOverrideEnabled(),
         workerManaged: workerHints.workerManaged,
         workerAssociation: workerHints.workerManaged
             ? {
@@ -384,15 +390,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 +481,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 +533,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 +544,7 @@ export async function executeDagRerun(input) {
         cwd: input.cwd,
         parentRunId: input.parentRunId,
         selectedNodeId: input.selectedNodeId,
+        promptOverrides: input.promptOverrides,
     });
     if (plan.planHash !== input.planHash) {
         return {
@@ -521,6 +573,20 @@ export async function executeDagRerun(input) {
     }
     const parentSpec = await readDagRunSpec(located.runDir);
     const parentState = await readDagRunState(located.runDir);
+    const recoveryLease = await acquireDagRecoveryLease({
+        cwd: input.cwd,
+        parentRunId: input.parentRunId,
+        requestId: input.requestId,
+        kind: "rerun-from-node",
+    });
+    if (recoveryLease.kind === "held") {
+        return {
+            ok: false,
+            plan,
+            errorCode: "RECOVERY_LEASE_HELD",
+            message: `parent run recovery is already claimed by ${recoveryLease.lease.kind} request ${recoveryLease.lease.requestId}`,
+        };
+    }
     const staged = await stageContinuationRun({
         cwd: input.cwd,
         parentRunDir: located.runDir,
@@ -530,10 +596,19 @@ export async function executeDagRerun(input) {
         plan,
         reason: input.reason,
         requestId: input.requestId,
+        promptOverrides: input.promptOverrides,
+    });
+    // Stage is non-executing; bind the child identity immediately before handing
+    // it to the runner so no recovery DAG can start without durable parent
+    // lineage ownership.
+    await bindDagRecoveryLeaseExecution({
+        leasePath: recoveryLease.leasePath,
+        lease: recoveryLease.lease,
+        executionRef: staged.state.runId,
     });
     const continuationOptions = {
         cwd: input.cwd,
-        spec: parentSpec,
+        spec: staged.spec,
         state: staged.state,
         runDir: staged.runDir,
         ...(input.maxConcurrent !== undefined

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

@@ -4,6 +4,7 @@ import { generateTaskDagUseCase } from "../../application/dag/generate-task-dag.
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { DAG_RUNS_DIR, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 import { deriveDagRerunFeedback } from "./rerun-feedback.js";
+import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, } from "./recovery-lease.js";
 import { parseDagSpec, } from "./types.js";
 export const RERUN_TASK_LINEAGE_REL_PATH = ".runtime/rerun-task-lineage.json";
 export function parseDagRerunTaskArgs(args) {
@@ -369,6 +370,34 @@ export async function rerunStandaloneTask(input) {
             }
         }
     }
+    const recoveryLease = execute
+        ? await acquireDagRecoveryLease({
+            cwd: input.cwd,
+            parentRunId: input.parentRunId,
+            requestId: input.requestId,
+            kind: "standalone-task-rerun",
+        })
+        : undefined;
+    if (recoveryLease?.kind === "held") {
+        return blockedResult({
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+            blockedReason: "recovery-lease-held",
+            note: `parent run recovery is already claimed by ${recoveryLease.lease.kind} request ${recoveryLease.lease.requestId}`,
+            taskId: taskResolution.taskId,
+        });
+    }
+    if (recoveryLease?.kind === "acquired") {
+        // Persist a non-empty execution identity before generateTaskDagUseCase can
+        // execute its new DAG. The generated run id is not available yet, so the
+        // request id is the stable lineage handle for this entry point.
+        await bindDagRecoveryLeaseExecution({
+            leasePath: recoveryLease.leasePath,
+            lease: recoveryLease.lease,
+            executionRef: `standalone-task-rerun:${input.requestId}`,
+        });
+    }
     const generateResult = await generateTaskDagUseCase({
         repoRoot: input.cwd,
         taskId: taskResolution.taskId,

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.
  *
@@ -23,6 +25,29 @@ export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
 export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
 /** Provider stopReason=length truncated the response before the JSON contract completed. */
 export const STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY = "structured-output-truncated";
+/**
+ * The review node emitted a verdict in response text (e.g. "VERDICT: pass")
+ * but never committed the authoritative typed terminal tool call
+ * (approve_review / request_review_changes). Read-only and safe to retry with
+ * a corrected instruction; the typed terminal is the only authority.
+ */
+export const REVIEW_TERMINAL_MISSING_RETRY_CATEGORY = "review-terminal-missing";
+/**
+ * The plan node issued too many read-only tool calls (read/grep/ls/find),
+ * blowing up the context window and eventually a 400 request-too-large. The
+ * plan should trust upstream typed facts instead of re-reading contract/scout
+ * outputs and source files repeatedly. Read-only and safe to retry with a
+ * reduced-reading instruction.
+ */
+export const READ_BURST_RETRY_CATEGORY = "read-burst";
+/**
+ * Provider returned a context-overflow error (400 request-too-large / context
+ * window exceeded). The SDK compacts and auto-retries once internally; when it
+ * still surfaces, the executor classifies this so retry policies and reports
+ * treat it as overflow (not empty-output) and can retry with a compacted
+ * session / fresh context.
+ */
+export const CONTEXT_OVERFLOW_RETRY_CATEGORY = "context-overflow";
 /** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
 export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
 /** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
@@ -55,6 +80,9 @@ export const ALL_DAG_RETRY_CATEGORIES = [
     WRITER_EMPTY_DIFF_RETRY_CATEGORY,
     INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
     WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
+    REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
+    READ_BURST_RETRY_CATEGORY,
+    CONTEXT_OVERFLOW_RETRY_CATEGORY,
 ];
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
@@ -104,13 +132,35 @@ export const dagRetryPolicySchema = z
 /**
  * The default retry policy applied to safe generated read-only Pi nodes.
  * Total attempts: 3, exponential backoff with cap.
+ *
+ * Includes `context-overflow`: a read-only node that blew the context window
+ * (400 request too large, e.g. a review node accumulating too many reads) is a
+ * transient, safe-to-retry failure — the retry re-runs the node with a
+ * compact-context instruction instead of failing the whole run. Previously
+ * only writer transport policies had context-overflow; contract/scout/
+ * design-review/review fell straight to ERROR without a retry attempt.
  */
 export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
     maxAttempts: 3,
     backoff: "exponential",
     initialDelayMs: 2000,
     maxDelayMs: 30000,
-    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES],
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
+};
+/** Scout is the discovery authority. A missing/incomplete typed target surface
+ * is safe to retry in-node, rather than making Plan rediscover the repository. */
+export const FRONTEND_SCOUT_COMPLETENESS_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Structured planner nodes may retry with a compact-output instruction
@@ -120,7 +170,11 @@ export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
  */
 export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
-    retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
+    retryCategories: [
+        ...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Planner read-only nodes (standard DAG contract-pi / plan-pi) may retry with
@@ -131,7 +185,12 @@ export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
  */
 export const PLANNER_OUTPUT_LIMIT_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
-    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES, STRUCTURED_OUTPUT_RETRY_CATEGORY],
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_OUTPUT_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Default retry for reviewer / recovery nodes that declare outputProtocol.
@@ -141,6 +200,22 @@ export const PROTOCOL_AWARE_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
     retryCategories: [...PROTOCOL_AWARE_DAG_RETRY_CATEGORIES],
 };
+/**
+ * frontend-review-pi retry policy. The review verdict must be committed
+ * through the typed terminal tools (approve_review / request_review_changes);
+ * a model that only echoes "VERDICT: pass" text fails as
+ * review-terminal-missing. That is read-only and safe to retry with a
+ * corrected instruction so a single model slip does not burn the whole run.
+ */
+export const FRONTEND_REVIEW_TERMINAL_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+        REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
+    ],
+};
 /**
  * The sole writer retry policy for requireChangedFiles writers. It is
  * intentionally not included in any read-only default: a writer may retry only
@@ -163,7 +238,46 @@ export const WRITER_TRANSPORT_RETRY_POLICY = {
     backoff: "exponential",
     initialDelayMs: 5000,
     maxDelayMs: 30000,
-    retryCategories: [WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY],
+    retryCategories: [
+        WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_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. Context overflow is added so a writer whose
+ * session hit the context window (compact+retry inside the SDK) can retry once
+ * more at the DAG level with a fresh attempt. 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,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Backend-test generation writers: empty-diff once, plus bounded incomplete-write-set
@@ -229,15 +343,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 +455,137 @@ 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=3
+ * bounds plan retry cost: the four-rung ladder is only partially traversable
+ * before the run fails non-converging (rungs: normal → bounded-tool-only →
+ * compact-terminal-first → backup-model). `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: 3,
+    backoff: "exponential",
+    initialDelayMs: 2000,
+    maxDelayMs: 30000,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
+};