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

package/dist/workflows/dag/node-execution.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
 import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isFrontendWriterAuthorized, readFrontendPrewriteResult, } from "./scheduler.js";
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
@@ -10,11 +11,15 @@ import { resolveContextPolicy } from "./context-policy.js";
 import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./prompt.js";
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
 import { buildOutputLimitRecoverySection, loadBackendTestWriterProgressForRetry, } from "./backend-test-writer-completeness.js";
-import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, } from "./retry-policy.js";
+import { computeBackoffDelayMs, isCanonicalFinalVerifyShellRetryCandidate, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, projectFrontendNodeProtocolFailureReason, resolveFrontendPlanBackupRoute, resolveFrontendPlanRetryStep, VERIFY_SHELL_RETRY_POLICY, } from "./retry-policy.js";
 import { applyNodeActivity, evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { buildProtocolRetryInstruction, normalizeReviewVerdictAfterRetries, parseJsonReviewVerdict, validateOutputProtocol, } from "./output-protocol.js";
 import { getStructuredContractValidator } from "./contract-output-registry.js";
 import "./contract-validator-registrations.js";
+import { computeNormalizedFailureFingerprint } from "./frontend-recovery-lineage.js";
+import { readTypedEventStoreFromJsonl } from "./frontend-typed-event-store.js";
+import { allowedRepairReadPaths, auditRepairAttemptToolUse, buildStructuredOutputRepairPrompt, freezeStructuredOutputRepairContext, hasNonEmptyStructuredCandidate, isFrontendStructuredRepairSchemaId, isStructuredRepairableFailureCategory, persistStructuredAttemptRaw, sessionEventsByteLength, GOVERNANCE_BLOCKED_CATEGORY, STRUCTURED_REPAIR_EXHAUSTED_CATEGORY, } from "./structured-output-repair.js";
+import { readFrontendCanonicalCandidate } from "./frontend-implementation-contract.js";
 import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { buildProjectGovernanceContext, readCompletedWriterChangeManifests, writeProjectGovernanceContext, } from "./project-governance-context.js";
 import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "./skill-snapshot.js";
@@ -132,16 +137,26 @@ export function buildNodePrompt(spec, task, upstream, options) {
 function frontendStructuredArtifactRetryGuidance(schemaId) {
     if (schemaId === "frontend-implementation-contract-plan-patch-v1") {
         return [
-            "Return exactly two blocks and nothing else: one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by one fenced openspec-citations block.",
+            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by exactly one fenced openspec-citations block.",
             "The runtime applies your patch to its protected contract skeleton. Do not emit schemaVersion, sourceBinding, riskLevel, targets.files, or mockApi.productionDefaultOff; do not emit the full contract.",
             "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+            "The openspec-citations fenced block contains one JSON object per line, each with path/section/line — for example:",
+            "```openspec-citations",
+            '{"path":".harness/tasks/<task>/source/需求.md","section":"Objective","line":5}',
+            '{"path":".harness/tasks/<task>/source/references/product-requirement.md","section":"FR-1","line":16}',
+            "```",
         ];
     }
     if (schemaId === "frontend-implementation-contract-revision-patch-v1") {
         return [
-            "Return exactly two blocks and nothing else: one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by one fenced openspec-citations block.",
+            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by exactly one fenced openspec-citations block.",
             "The delta contains only the fields you change; null deletes a key, arrays and scalars replace, and plain objects merge recursively. Do not emit a full contract or a schemaVersion/targets section.",
             "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+            "The openspec-citations fenced block contains one JSON object per line, each with path/section/line — for example:",
+            "```openspec-citations",
+            '{"path":".harness/tasks/<task>/source/需求.md","section":"Objective","line":5}',
+            '{"path":".harness/tasks/<task>/source/references/product-requirement.md","section":"FR-1","line":16}',
+            "```",
         ];
     }
     return [
@@ -149,30 +164,131 @@ function frontendStructuredArtifactRetryGuidance(schemaId) {
         "The contract JSON fields are the complete implementation plan. Do not emit a separate plan document, Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
     ];
 }
-function isFrontendPlanArtifactSchema(schemaId) {
-    return (schemaId === "frontend-implementation-contract-plan-patch-v1" ||
-        schemaId === "frontend-implementation-contract-revision-patch-v1");
+const FRONTEND_PLAN_NODE_ID = "frontend-plan-pi";
+const COMPACT_RETRY_SECTION_MAX_CHARS = 1_200;
+const COMPACT_RETRY_TASK_MAX_CHARS = 4_800;
+/** Keep alias/field-shape remediation out of the initial Plan prompt. */
+function frontendPlanValidationRetryGuidance(reason) {
+    const guidance = [];
+    if (/notApplicableReason|uiState.*reason/i.test(reason)) {
+        guidance.push("For this retry, use uiStates[].notApplicableReason for a non-applicable state; omit expectedBehavior instead of supplying an empty value.");
+    }
+    if (/interaction.*(?:\bid\b|\bname\b)|requires non-empty interaction\.name/i.test(reason)) {
+        guidance.push("For this retry, use interactions[].name with non-empty trigger and expectedBehavior.");
+    }
+    if (/verificationTargets.*uiStates|uiStates.*verificationTargets/i.test(reason)) {
+        guidance.push("For this retry, provide verificationTargets[].uiStates as an array; use [] when the target has no named UI state.");
+    }
+    return guidance;
 }
-function buildFrontendPlanArtifactRecoveryPrompt(options) {
-    const cause = options.failure === "truncated"
-        ? "Previous response was truncated by the provider (stopReason=length)."
-        : options.failure === "too-large"
-            ? "Previous response could not be retained by the provider."
-            : "Previous response failed structured validation.";
+function compactRetryText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const headChars = Math.floor(maxChars * 0.78);
+    const tailChars = Math.max(0, maxChars - headChars - 52);
+    return `${text.slice(0, headChars)}\n… [omitted after context-overflow] …\n${text.slice(-tailChars)}`;
+}
+function compactRetrySection(prompt, name, maxChars) {
+    const match = prompt.match(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`));
+    return compactRetryText(match?.[1]?.trim() ?? "(not available)", maxChars);
+}
+/**
+ * A context-overflow retry must not resend the full resolved skills, governance
+ * payload, repeated source excerpts, and upstream previews that caused the
+ * previous session to overflow. Keep the immutable node contract plus bounded
+ * objective/criteria/task excerpts; canonical artifacts remain readable by
+ * pointer from the retained task instructions.
+ */
+export function buildContextOverflowRetryPrompt(task, basePrompt) {
     return [
-        "<retry_instruction>",
-        cause,
-        options.reason ? `Validation error: ${options.reason}` : "",
-        ...frontendStructuredArtifactRetryGuidance(options.schemaId),
-        "Use concise values and reference paths/IDs instead of copying source prose. Do not omit required semantics.",
-        "</retry_instruction>",
-    ]
-        .filter(Boolean)
-        .join("\n");
+        "<compact_retry_context>",
+        "This is a fresh, compact retry after provider context-overflow. The original full prompt remains audit evidence but is intentionally not resent.",
+        "Do not re-read task sources, upstream stdout, skills, or full diff artifacts that are already represented by canonical artifacts. Start from the smallest retained artifact and expand only the exact file or diff fragment needed.",
+        "</compact_retry_context>",
+        `<dag_objective>\n${compactRetrySection(basePrompt, "dag_objective", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</dag_objective>`,
+        `<success_criteria>\n${compactRetrySection(basePrompt, "success_criteria", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</success_criteria>`,
+        `<global_constraints>\n${compactRetrySection(basePrompt, "global_constraints", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</global_constraints>`,
+        `<node_contract>\n${compactRetrySection(basePrompt, "node_contract", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</node_contract>`,
+        `<upstream_context>\n${compactRetrySection(basePrompt, "upstream_context", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</upstream_context>`,
+        [
+            "<task>",
+            `Original task id: ${task.id}`,
+            compactRetrySection(basePrompt, "task", COMPACT_RETRY_TASK_MAX_CHARS),
+            "</task>",
+        ].join("\n"),
+    ].join("\n\n");
 }
-function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics) {
+function isFrontendPlanLadderTask(task) {
+    return task.id === FRONTEND_PLAN_NODE_ID;
+}
+/**
+ * Read the committed plan ledger snapshot for the ladder's "no new committed
+ * fact" check. The digest is over the sorted committed payload hashes, and
+ * `hasTerminalFact` reflects a committed `finalize_plan` terminal fact.
+ */
+async function readFrontendPlanCommittedSnapshot(runDir, nodeId) {
+    const records = await readTypedEventStoreFromJsonl(path.join(runDir, nodeId, "plan-typed-facts.jsonl"));
+    const committed = records.filter((record) => record.phase === "committed");
+    const digest = createHash("sha256")
+        .update(committed
+        .map((record) => record.payloadSha256)
+        .sort()
+        .join("\n"))
+        .digest("hex");
+    const hasTerminalFact = committed.some((record) => record.fact.kind === "finalize_plan");
+    return { digest, hasTerminalFact };
+}
+export function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics, frontendPlanRetryStep) {
     if (attemptNumber <= 1)
         return basePrompt;
+    // Context overflow is a transport/session failure, not a plan-protocol
+    // failure. It must take precedence over the plan retry ladder so every
+    // retry, including a repeated plan overflow, starts from the compact
+    // envelope rather than re-sending the original prompt.
+    if (previousFailureCategory === "context-overflow") {
+        return [
+            buildContextOverflowRetryPrompt(task, basePrompt),
+            "",
+            "<retry_instruction>",
+            "The previous attempt exceeded the provider context window. This retry starts a fresh session: keep the evidence surface narrow.",
+            "Do not re-read task sources, upstream stdout, skills, or full diff artifacts that are already represented by the canonical contract/review context. Read the smallest relevant artifact first, then only the specific source file or diff fragment needed to decide a finding.",
+            "Do not read artifacts/diff_patch.patch in full. For frontend review, read the bounded diff summary and then at most the specific per-file diff fragments it identifies, in part order.",
+            "Use concise tool calls and finish the required terminal/output protocol as soon as the evidence is sufficient.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (frontendPlanRetryStep === "compact-terminal-first") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Frontend plan retry ladder step: compact-terminal-first.",
+            "Do NOT rewrite the narrative. Only adopt already staged/quarantined fresh facts, fill the missing required facts, then call finalize_plan exactly once.",
+            "Keep the existing committed ledger intact; do not re-derive already committed facts.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (frontendPlanRetryStep === "bounded-tool-only") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Frontend plan retry ladder step: bounded-tool-only.",
+            "Reduce reasoning and wall-clock time. Use only read / fact / terminal tools and only for the necessary missing facts, then call finalize_plan exactly once.",
+            "Do not expand scope or re-derive already committed facts.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (frontendPlanRetryStep === "backup-model") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Frontend plan retry ladder step: backup-model.",
+            "A backup provider/model route was selected after repeated non-converging failures. Re-derive only the missing committed facts, then call finalize_plan exactly once; do not repeat the failed strategy.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "protocol-invalid" &&
         task.outputProtocol &&
         previousProtocolReason) {
@@ -182,15 +298,64 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             buildProtocolRetryInstruction(task.outputProtocol, previousProtocolReason),
         ].join("\n");
     }
+    if (previousFailureCategory === "review-terminal-missing") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "The review emitted a verdict in response text but never committed the authoritative typed terminal tool call (approve_review / request_review_changes). The response text is NOT the authority: no branch or gate reads it.",
+            "Call exactly one typed terminal tool to finish: approve_review (implementation passes, no Critical/Important findings) or request_review_changes (with typed issueCategory, at least one evidenceRef, and non-empty findings). Do not repeat the review analysis; commit the terminal tool once and stop.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "read-burst") {
+        if (task.id !== FRONTEND_PLAN_NODE_ID) {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "The previous attempt exceeded its read budget. Start a fresh, evidence-minimal pass: do not re-read task sources, upstream stdout, skills, or full diff artifacts already represented by a canonical context artifact.",
+                "Read the smallest relevant summary first, then only the specific source file or diff fragment needed for the required decision. Finish the required terminal/output protocol as soon as evidence is sufficient.",
+                "</retry_instruction>",
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous plan attempt issued too many read-only tool calls (read/grep/ls/find) and blew up the context window. Trust the upstream frontend-contract-pi typed requirement facts and frontend-scout-pi target surface already provided — do NOT re-read contract/scout stdout, PRD/source files, or component sources you already inspected.",
+            "Minimize discovery reads: only read what you genuinely need, once. Commit record_plan_requirement / record_plan_verification_target / record_* facts directly from the facts already in context (one tool call per message), then call finalize_plan exactly once.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "invalid-output" &&
         task.structuredContractOutput &&
         previousProtocolReason) {
-        if (isFrontendPlanArtifactSchema(task.structuredContractOutput.schemaId)) {
-            return buildFrontendPlanArtifactRecoveryPrompt({
-                failure: "invalid",
-                reason: previousProtocolReason,
-                schemaId: task.structuredContractOutput.schemaId,
-            });
+        // The frontend plan node's compile authority is the committed typed
+        // ledger, not a fenced JSON text artifact: its retry guidance must
+        // direct the model to re-commit corrected record_* facts and
+        // finalize_plan. The legacy full-contract JSON guidance below applies
+        // only to nodes whose authority is still a text contract artifact.
+        if (task.structuredContractOutput.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1") {
+            const splitGuidance = /write-set-too-large|split the task/.test(previousProtocolReason ?? "")
+                ? [
+                    "",
+                    "The writeSet is too large for one implement node. Do NOT delete implementation files to squeeze under the limit — that drops required work. Split the task via record_split_proposal (or narrow targets.files to a genuine subset) so each implement node stays bounded; the full file set must remain covered across the split.",
+                ]
+                : [];
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous plan ledger facts failed canonical contract validation:",
+                previousProtocolReason,
+                "Fix the reported violations by re-committing corrected record_* facts and calling finalize_plan exactly once. The committed typed ledger is the only compile authority.",
+                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                ...frontendPlanValidationRetryGuidance(previousProtocolReason),
+                ...splitGuidance,
+                "</retry_instruction>",
+            ].join("\n");
         }
         return [
             basePrompt,
@@ -203,15 +368,30 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             "</retry_instruction>",
         ].join("\n");
     }
+    if (previousFailureCategory === "invalid-output" &&
+        task.id === "frontend-scout-pi") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "The previous Scout attempt did not commit a complete, runtime-evidenced target surface.",
+            "Search the repository only as needed to establish the real entrypoint, implementation ownership, and applicable test path. Commit record_target_surface with completeness=complete and unresolvedPaths=[] only after at least one named target has fresh runtime evidence. If ownership truly cannot be established, record completeness=blocked with each unresolved path; do not make Plan discover it.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "structured-output-truncated" &&
         task.structuredContractOutput) {
-        const schemaId = task.structuredContractOutput.schemaId;
-        if (isFrontendPlanArtifactSchema(schemaId)) {
-            return buildFrontendPlanArtifactRecoveryPrompt({
-                failure: "truncated",
-                reason: previousProtocolReason,
-                schemaId,
-            });
+        if (task.structuredContractOutput.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1") {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous attempt was truncated by the provider (stopReason=length) before the plan facts were fully committed.",
+                "Re-commit the missing record_* facts and call finalize_plan exactly once; the committed typed ledger is the only compile authority. Do NOT re-read contract/scout outputs or source files — use the facts already in context. Commit record_* facts one tool call per message, then finalize_plan immediately.",
+                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                "</retry_instruction>",
+            ].join("\n");
         }
         return [
             basePrompt,
@@ -284,16 +464,32 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             "</retry_instruction>",
         ].join("\n");
     }
+    if (previousFailureCategory === "writer-clean-timeout") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt ended in a clean provider/transport failure with zero attributed workspace writes and zero write/edit tool calls.",
+            "Do not invent existing implementation progress. Continue from the original task only if the workspace is still unchanged.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory !== "output-too-large") {
         return basePrompt;
     }
     if (task.outputMode === "structured-required") {
         if (task.structuredContractOutput) {
-            if (isFrontendPlanArtifactSchema(task.structuredContractOutput.schemaId)) {
-                return buildFrontendPlanArtifactRecoveryPrompt({
-                    failure: "too-large",
-                    schemaId: task.structuredContractOutput.schemaId,
-                });
+            if (task.structuredContractOutput.schemaId ===
+                "frontend-implementation-contract-plan-patch-v1") {
+                return [
+                    basePrompt,
+                    "",
+                    "<retry_instruction>",
+                    "Previous attempt exceeded the structured output size limit.",
+                    "Re-commit corrected record_* facts and call finalize_plan exactly once; the committed typed ledger is the only compile authority.",
+                    "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                    "</retry_instruction>",
+                ].join("\n");
             }
             return [
                 basePrompt,
@@ -326,6 +522,35 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
         "</retry_instruction>",
     ].join("\n");
 }
+const PROMPT_RESTART_CANDIDATE_MAX_BYTES = 64 * 1024;
+function promptRestartCandidateForAttempt(input) {
+    if (input.attemptPrompt === input.baseRuntimePrompt) {
+        return input.taskPrompt;
+    }
+    const appendedPrefix = `${input.baseRuntimePrompt}\n\n`;
+    if (input.attemptPrompt.startsWith(appendedPrefix)) {
+        return [
+            input.taskPrompt,
+            input.attemptPrompt.slice(appendedPrefix.length),
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    return input.attemptPrompt;
+}
+async function persistFailedPromptRestartCandidate(input) {
+    const redacted = redactSecrets(input.prompt);
+    const preview = truncateUtf8Preview(redacted, PROMPT_RESTART_CANDIDATE_MAX_BYTES);
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, `prompt-candidate-attempt-${input.attempt}.json`, {
+        schemaVersion: 1,
+        attempt: input.attempt,
+        failureCategory: input.failureCategory ?? "unknown",
+        prompt: preview,
+        truncated: preview !== redacted,
+        maxBytes: PROMPT_RESTART_CANDIDATE_MAX_BYTES,
+        sha256: createHash("sha256").update(redacted).digest("hex"),
+    });
+}
 export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
     const policy = resolveContextPolicy(spec);
     const skillNames = policy.resolveSkills(spec, task);
@@ -715,7 +940,7 @@ export async function executeDagNode(input) {
     }
     node.resolvedSkills = resolvedSkills;
     await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
-    const model = resolveModelForTask(task, spec.executorModels);
+    let model = resolveModelForTask(task, spec.executorModels);
     let thinking;
     if (task.executor === "pi") {
         try {
@@ -726,16 +951,25 @@ export async function executeDagNode(input) {
             // Invalid or missing harness preserves the previous no-override behavior.
         }
     }
-    const retryPolicy = task.retryPolicy &&
+    const specRetryPolicy = task.retryPolicy &&
         (isSafeReadOnlyPiRetryCandidate(task) ||
             isWriterEmptyDiffRetryCandidate(task) ||
             isWriterTransportRetryCandidate(task))
         ? task.retryPolicy
         : undefined;
+    const implicitVerifyRetryPolicy = specRetryPolicy === undefined &&
+        isCanonicalFinalVerifyShellRetryCandidate(task) &&
+        isTargetTemplateTransientRetryNode(task)
+        ? VERIFY_SHELL_RETRY_POLICY
+        : undefined;
+    const retryPolicy = specRetryPolicy ?? implicitVerifyRetryPolicy;
     const maxAttempts = retryPolicy?.maxAttempts ?? 1;
     const attempts = [];
     let totalAttemptWallDurationMs = 0;
     let totalBackoffMs = 0;
+    const frontendPlanLadderEnabled = isFrontendPlanLadderTask(task);
+    let frontendPlanRetryStep = "normal";
+    const frontendPriorFingerprints = [];
     const livenessPolicy = resolveLivenessPolicy(spec.defaults?.livenessPolicy, task.livenessPolicy);
     /**
      * Attempt-fenced, throttled activity sink. Late events from a previous
@@ -773,10 +1007,25 @@ export async function executeDagNode(input) {
     let terminalResult;
     let previousFailureCategory;
     let previousProtocolReason;
+    let pendingStructuredArtifact;
+    let lastRepairAllowlist = [];
     for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
         const attemptStartedAt = new Date().toISOString();
         node.currentAttempt = attemptNumber;
         node.livenessStatus = "active";
+        const beforeCommittedDigest = frontendPlanLadderEnabled
+            ? (await readFrontendPlanCommittedSnapshot(runDir, nodeId)).digest
+            : undefined;
+        if (frontendPlanLadderEnabled &&
+            frontendPlanRetryStep === "backup-model") {
+            model = resolveModelForTask(task, spec.executorModels);
+        }
+        // Capture the session-events.jsonl length BEFORE the executor appends this
+        // attempt's events, so the post-attempt repair tool audit can be scoped to
+        // exactly this attempt's segment (B1: earlier attempts legitimately use
+        // ls/find and must not be attributed to the repair attempt).
+        const attemptSessionEventsOffset = await sessionEventsByteLength(runDir, nodeId);
+        let promptRestartCandidate = task.subtask_prompt;
         let result;
         try {
             validateRepairArtifactGateBeforeShell({
@@ -799,12 +1048,65 @@ export async function executeDagNode(input) {
                 (acc[i.path] ??= []).push(i.detail);
                 return acc;
             }, {});
+            let attemptPrompt = buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics, frontendPlanRetryStep);
+            if (attemptNumber > 1 &&
+                // The plan node (frontend-plan-pi) is a typed-facts ladder task:
+                // its retry is driven by the §5.1 ladder (compact-terminal-first
+                // / backup-model) and its compile authority is the committed
+                // ledger — never the legacy frozen fenced-JSON repair. The
+                // frozen repair path below applies only to non-ladder
+                // structured nodes whose output authority is a text artifact.
+                !frontendPlanLadderEnabled &&
+                isFrontendStructuredRepairSchemaId(task.structuredContractOutput?.schemaId) &&
+                isStructuredRepairableFailureCategory(previousFailureCategory) &&
+                (await hasNonEmptyStructuredCandidate({
+                    runDir,
+                    nodeId,
+                    beforeAttempt: attemptNumber,
+                }))) {
+                const originalCanonical = task.structuredContractOutput?.schemaId ===
+                    "frontend-implementation-contract-revision-patch-v1"
+                    ? (await readFrontendCanonicalCandidate(runDir, "frontend-plan-pi"))
+                    : undefined;
+                const frozen = await freezeStructuredOutputRepairContext({
+                    runDir,
+                    runId: state.runId,
+                    taskId: spec.sourceBinding?.taskId ?? task.id,
+                    nodeId,
+                    nodeAttempt: attemptNumber,
+                    targetSchemaId: task.structuredContractOutput.schemaId,
+                    skeleton: task.structuredContractOutput?.skeleton,
+                    originalCanonical,
+                    latestStopReason: previousFailureCategory === "structured-output-truncated"
+                        ? "length"
+                        : previousFailureCategory,
+                });
+                lastRepairAllowlist = allowedRepairReadPaths({
+                    runDir,
+                    context: frozen.context,
+                    contextPath: frozen.relativePath,
+                });
+                attemptPrompt = await buildStructuredOutputRepairPrompt({
+                    runDir,
+                    context: frozen.context,
+                    contextPath: frozen.relativePath,
+                    contextSha256: frozen.sha256,
+                    maxAttempts,
+                    schemaGuidance: frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+                    previousReason: previousProtocolReason,
+                });
+            }
+            promptRestartCandidate = promptRestartCandidateForAttempt({
+                taskPrompt: task.subtask_prompt,
+                baseRuntimePrompt: prompt,
+                attemptPrompt,
+            });
             result = await executeNode({
                 task,
                 cwd,
                 model,
                 ...(thinking ? { thinking } : {}),
-                prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics),
+                prompt: attemptPrompt,
                 attempt: attemptNumber,
                 reportActivity,
                 timeoutMs: livenessPolicy.absoluteMaxWallClockMs,
@@ -820,6 +1122,35 @@ export async function executeDagNode(input) {
                 durationMs: 0,
             };
         }
+        if (isFrontendStructuredRepairSchemaId(task.structuredContractOutput?.schemaId)) {
+            const rawText = canonicalNodeOutput(result);
+            if (rawText.trim().length > 0) {
+                await persistStructuredAttemptRaw({
+                    runDir,
+                    nodeId,
+                    attempt: attemptNumber,
+                    text: rawText,
+                });
+            }
+            if (attemptNumber > 1 && lastRepairAllowlist.length > 0) {
+                const audit = await auditRepairAttemptToolUse({
+                    runDir,
+                    nodeId,
+                    allowedPaths: lastRepairAllowlist,
+                    fromByteOffset: attemptSessionEventsOffset,
+                });
+                if (!audit.ok) {
+                    result = {
+                        ...result,
+                        ok: false,
+                        failureCategory: GOVERNANCE_BLOCKED_CATEGORY,
+                        stderr: [result.stderr, audit.reason]
+                            .filter(Boolean)
+                            .join("\n"),
+                    };
+                }
+            }
+        }
         // R0: executor ok=true still fails closed when outputProtocol is violated.
         // Valid semantic results (e.g. VERDICT: request-revision) pass validation.
         if (result.ok && task.outputProtocol) {
@@ -856,16 +1187,17 @@ export async function executeDagNode(input) {
                     structuredContractOutput: task.structuredContractOutput,
                 });
                 if (!contractCheck.ok) {
-                    // A provider stopReason=length means the response was cut before the
-                    // JSON contract could complete; separate it from an ordinary bad
-                    // contract so the retry switches to a JSON-only output strategy.
                     const attemptStopReason = result.stopReason;
+                    const failureCategory = contractCheck.classification === "governance-blocked"
+                        ? GOVERNANCE_BLOCKED_CATEGORY
+                        : attemptStopReason === "length" ||
+                            contractCheck.classification === "truncated"
+                            ? "structured-output-truncated"
+                            : "invalid-output";
                     result = {
                         ...result,
                         ok: false,
-                        failureCategory: attemptStopReason === "length"
-                            ? "structured-output-truncated"
-                            : "invalid-output",
+                        failureCategory,
                         stderr: [result.stderr, contractCheck.reason]
                             .filter(Boolean)
                             .join("\n"),
@@ -873,14 +1205,6 @@ export async function executeDagNode(input) {
                     previousProtocolReason = contractCheck.reason;
                 }
                 else {
-                    if (contractCheck.structuredArtifact) {
-                        node.structuredArtifactPath = contractCheck.structuredArtifact.path;
-                        node.structuredArtifactSha256 = contractCheck.structuredArtifact.sha256;
-                        node.structuredArtifactSchemaId = contractCheck.structuredArtifact.schemaId;
-                    }
-                    if (contractCheck.frontendPlanOutput) {
-                        node.frontendPlanOutput = contractCheck.frontendPlanOutput;
-                    }
                     if (contractCheck.normalizedText) {
                         result = {
                             ...result,
@@ -888,6 +1212,9 @@ export async function executeDagNode(input) {
                             stdout: contractCheck.normalizedText,
                         };
                     }
+                    if (contractCheck.artifact) {
+                        pendingStructuredArtifact = contractCheck.artifact;
+                    }
                     previousProtocolReason = undefined;
                 }
             }
@@ -900,6 +1227,16 @@ export async function executeDagNode(input) {
         const attemptFinishedAt = new Date().toISOString();
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;
+        const rawFailureCategory = result.rawFailureCategory ?? result.failureCategory;
+        if (task.executor === "pi" && !result.ok) {
+            await persistFailedPromptRestartCandidate({
+                runDir,
+                nodeId,
+                attempt: attemptNumber,
+                failureCategory: result.failureCategory,
+                prompt: promptRestartCandidate,
+            });
+        }
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,
@@ -911,6 +1248,7 @@ export async function executeDagNode(input) {
             stderr: result.stderr,
             assistantText: result.assistantText,
             failureCategory: result.failureCategory,
+            ...(rawFailureCategory ? { rawFailureCategory } : {}),
             backend: result.backend,
             sdkAttempted: result.sdkAttempted,
             tokensUsed: result.tokensUsed,
@@ -925,6 +1263,60 @@ export async function executeDagNode(input) {
             await writeDagNodeJsonArtifact(runDir, nodeId, `attempt-${attemptNumber}.json`, attemptRecord);
             node.attempts = attempts;
         }
+        // Frontend plan retry ladder: project the 7-value protocol failure
+        // reason, detect new committed facts, and escalate instead of re-running.
+        if (frontendPlanLadderEnabled && !result.ok) {
+            const afterSnapshot = await readFrontendPlanCommittedSnapshot(runDir, nodeId);
+            const hasNewCommittedFact = beforeCommittedDigest !== undefined &&
+                afterSnapshot.digest !== beforeCommittedDigest;
+            const protocolReason = projectFrontendNodeProtocolFailureReason({
+                failureCategory: result.failureCategory,
+                stopReason: result.stopReason,
+                assistantText: result.assistantText ?? result.stdout,
+                hasTerminalFact: afterSnapshot.hasTerminalFact,
+            });
+            const fingerprint = computeNormalizedFailureFingerprint({
+                failureOwner: "plan",
+                protocolFailureReason: protocolReason ?? "",
+            });
+            const backupRoute = resolveFrontendPlanBackupRoute(protocolReason);
+            const nextStep = resolveFrontendPlanRetryStep({
+                currentStep: frontendPlanRetryStep,
+                protocolFailureReason: protocolReason,
+                hasNewCommittedFact,
+                fingerprint,
+                priorFingerprints: frontendPriorFingerprints,
+                backupRouteAvailable: backupRoute.ok,
+            });
+            frontendPriorFingerprints.push(fingerprint);
+            frontendPlanRetryStep = nextStep;
+            if (nextStep === "unsupported-provider-capability") {
+                result = {
+                    ...result,
+                    ok: false,
+                    failureCategory: "unsupported-provider-capability",
+                    stderr: [
+                        result.stderr,
+                        "frontend plan retry ladder: no compatible provider capability route for the protocol failure reason",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+            }
+            else if (nextStep === "non-converging") {
+                result = {
+                    ...result,
+                    ok: false,
+                    failureCategory: "non-converging",
+                    stderr: [
+                        result.stderr,
+                        "frontend plan retry ladder: repeated failure fingerprint with no new committed fact",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+            }
+        }
         // Reflect the latest attempt on the node so progress is observable,
         // but keep node.status RUNNING while retry is still possible.
         node.durationMs = durationBetween(node.startedAt, attemptFinishedAt);
@@ -958,13 +1350,26 @@ export async function executeDagNode(input) {
             break;
         const canRetry = retryPolicy !== undefined && attemptNumber < maxAttempts;
         const retryable = retryPolicy !== undefined &&
+            result.failureCategory !== GOVERNANCE_BLOCKED_CATEGORY &&
             (isRetryablePiFailureCategory(result.failureCategory, {
                 retryCategories: retryPolicy.retryCategories,
             }) ||
                 (result.failureCategory === "protocol-invalid" &&
                     task.outputProtocol?.retryOnInvalid === true));
-        if (!canRetry || !retryable)
+        if (!canRetry || !retryable) {
+            if (!canRetry &&
+                isFrontendStructuredRepairSchemaId(task.structuredContractOutput?.schemaId) &&
+                isStructuredRepairableFailureCategory(result.failureCategory)) {
+                result = {
+                    ...result,
+                    failureCategory: STRUCTURED_REPAIR_EXHAUSTED_CATEGORY,
+                };
+                terminalResult = result;
+                previousFailureCategory = result.failureCategory;
+                node.failureCategory = result.failureCategory;
+            }
             break;
+        }
         const delayMs = computeBackoffDelayMs(attemptNumber + 1, retryPolicy);
         if (delayMs > 0) {
             const backoffStartedAt = new Date().toISOString();
@@ -1113,6 +1518,11 @@ export async function executeDagNode(input) {
                 node.structuredArtifactSchemaId = "backend-test-result-v1";
             }
         }
+        else if (pendingStructuredArtifact) {
+            node.structuredArtifactPath = pendingStructuredArtifact.path;
+            node.structuredArtifactSha256 = pendingStructuredArtifact.sha256;
+            node.structuredArtifactSchemaId = pendingStructuredArtifact.schemaId;
+        }
     }
     const finishedAt = new Date().toISOString();
     node.finishedAt = finishedAt;