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

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

@@ -10,11 +10,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";
@@ -129,26 +133,29 @@ export function buildNodePrompt(spec, task, upstream, options) {
         convergenceFeedback: options?.convergenceFeedback,
     });
 }
-function frontendStructuredArtifactRetryGuidance(schemaId, citationsRequired = true) {
-    const format = citationsRequired
-        ? "one fenced json block immediately followed by one fenced openspec-citations block"
-        : "one fenced json block and no openspec-citations block";
+function frontendStructuredArtifactRetryGuidance(schemaId) {
     if (schemaId === "frontend-implementation-contract-plan-patch-v1") {
         return [
-            citationsRequired
-                ? "Return exactly one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by one fenced openspec-citations block, and nothing else."
-                : `Return exactly ${format} and nothing else; the json block contains only the editable RFC 7386 plan patch.`,
+            "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 [
-            citationsRequired
-                ? "Return exactly one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by one fenced openspec-citations block, and nothing else."
-                : `Return exactly ${format} and nothing else; the json block contains the RFC 7386 merge-patch delta.`,
+            "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 [
@@ -156,30 +163,62 @@ function frontendStructuredArtifactRetryGuidance(schemaId, citationsRequired = t
         "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";
+function isFrontendPlanLadderTask(task) {
+    return task.id === FRONTEND_PLAN_NODE_ID;
 }
-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.";
-    return [
-        "<retry_instruction>",
-        cause,
-        options.reason ? `Validation error: ${options.reason}` : "",
-        ...frontendStructuredArtifactRetryGuidance(options.schemaId, options.citationsRequired),
-        "Use concise values and reference paths/IDs instead of copying source prose. Do not omit required semantics.",
-        "</retry_instruction>",
-    ]
-        .filter(Boolean)
-        .join("\n");
+/**
+ * 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 };
 }
-function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics) {
+function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics, frontendPlanRetryStep) {
     if (attemptNumber <= 1)
         return basePrompt;
+    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) {
@@ -192,13 +231,23 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     if (previousFailureCategory === "invalid-output" &&
         task.structuredContractOutput &&
         previousProtocolReason) {
-        if (isFrontendPlanArtifactSchema(task.structuredContractOutput.schemaId)) {
-            return buildFrontendPlanArtifactRecoveryPrompt({
-                failure: "invalid",
-                reason: previousProtocolReason,
-                schemaId: task.structuredContractOutput.schemaId,
-                citationsRequired: task.structuredContractOutput.citationsRequired,
-            });
+        // 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") {
+            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.",
+                "</retry_instruction>",
+            ].join("\n");
         }
         return [
             basePrompt,
@@ -213,14 +262,17 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     }
     if (previousFailureCategory === "structured-output-truncated" &&
         task.structuredContractOutput) {
-        const schemaId = task.structuredContractOutput.schemaId;
-        if (isFrontendPlanArtifactSchema(schemaId)) {
-            return buildFrontendPlanArtifactRecoveryPrompt({
-                failure: "truncated",
-                reason: previousProtocolReason,
-                schemaId,
-                citationsRequired: task.structuredContractOutput.citationsRequired,
-            });
+        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 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,
@@ -293,17 +345,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,
-                    citationsRequired: task.structuredContractOutput.citationsRequired,
-                });
+            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,
@@ -725,7 +792,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 {
@@ -736,16 +803,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
@@ -783,10 +859,24 @@ 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 result;
         try {
             validateRepairArtifactGateBeforeShell({
@@ -809,12 +899,60 @@ 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,
+                });
+            }
             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,
@@ -830,6 +968,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) {
@@ -866,16 +1033,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"),
@@ -883,14 +1051,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,
@@ -898,6 +1058,9 @@ export async function executeDagNode(input) {
                             stdout: contractCheck.normalizedText,
                         };
                     }
+                    if (contractCheck.artifact) {
+                        pendingStructuredArtifact = contractCheck.artifact;
+                    }
                     previousProtocolReason = undefined;
                 }
             }
@@ -910,6 +1073,7 @@ export async function executeDagNode(input) {
         const attemptFinishedAt = new Date().toISOString();
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;
+        const rawFailureCategory = result.rawFailureCategory ?? result.failureCategory;
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,
@@ -921,6 +1085,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,
@@ -935,6 +1100,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);
@@ -968,13 +1187,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();
@@ -1123,6 +1355,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;

package/dist/workflows/dag/prompt.js

@@ -67,7 +67,6 @@ export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHA
     const toleratedFailures = new Set(task.failureAwareDependsOn ?? []);
     for (const depId of task.depends_on) {
         const record = upstream[depId];
-        const artifactFirst = task.artifactFirstUpstreamNodeIds?.includes(depId);
         const stdout = record?.stdout?.trim() ? record.stdout : "";
         const assistantText = record?.assistantText?.trim()
             ? record.assistantText
@@ -119,23 +118,16 @@ export function buildUpstreamContext(task, upstream, maxChars = MAX_UPSTREAM_CHA
         }
         if (!record || record.status !== "FINISHED")
             continue;
-        if (artifactFirst) {
-            const lines = [
-                `## Upstream artifact: ${depId}`,
-                "Artifact-first input: do not infer fields from a preview. Read the hash-bound payload only when a field is required; do not edit runner evidence.",
-            ];
-            if (record.structuredArtifactPath &&
-                record.structuredArtifactSha256 &&
-                record.structuredArtifactSchemaId) {
-                lines.push(`- payload: ${record.structuredArtifactPath}`, `- schema: ${record.structuredArtifactSchemaId}`, `- sha256: ${record.structuredArtifactSha256}`);
-                if (record.frontendPlanOutput) {
-                    lines.push(`- payload kind: ${record.frontendPlanOutput.payloadKind}`, `- citations: ${record.frontendPlanOutput.citationsArtifactPath}`, `- citations sha256: ${record.frontendPlanOutput.citationsArtifactSha256}`);
-                }
-            }
-            else {
-                lines.push("- artifact: unavailable (do not reconstruct the contract from node prose; treat this as an upstream artifact integrity failure)");
-            }
-            sections.push(lines.join("\n"));
+        if (record.structuredArtifactPath &&
+            record.structuredArtifactSchemaId ===
+                "frontend-implementation-contract-v1") {
+            sections.push([
+                `## Upstream output: ${depId}`,
+                "Validated structured artifact (read-only runner evidence — use read tool to fetch; do not edit). Do not infer the contract from stdout.",
+                `- path: ${record.structuredArtifactPath}`,
+                `- schema: ${record.structuredArtifactSchemaId}`,
+                `- sha256: ${record.structuredArtifactSha256 ?? "unknown"}`,
+            ].join("\n"));
             continue;
         }
         if (!upstreamText)