@tea-agent/loop-agent 0.35.1-beta.0 → 0.35.1-beta.2

package/dist/workflows/dag/init-hybrid.js

@@ -2199,6 +2199,26 @@ function pruneFrontendTasksForRisk(tasks, risk) {
         return { ...task, depends_on };
     });
 }
+/**
+ * AC-1: shared frontend writer node defaults. frontend-implement-pi and
+ * frontend-repair-pi share one prompt/contract/writeSet-guard surface and an
+ * identical writeSet; only id, depends_on, runIf, outputContract, and
+ * subtask_prompt differ per phase.
+ */
+function buildFrontendWriterNodeDefaults(input) {
+    return {
+        role: "implementer",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: input.complexity,
+        writePolicy: "exclusive",
+        writeSet: input.writeSet,
+        allowedPaths: input.allowedPaths,
+        forbiddenPaths: input.forbiddenPaths,
+        skills: FRONTEND_BOUNDED_IMPLEMENT_SKILLS,
+        writerOutcomePolicy: { type: "implementation-outcome-v1" },
+    };
+}
 async function buildFrontendHybridDagFromTask(sources) {
     const { taskConfig } = sources;
     const mockCapability = sources.frontendMockCapability ?? {
@@ -2532,6 +2552,10 @@ async function buildFrontendHybridDagFromTask(sources) {
                 writePolicy: "read-only",
                 outputMode: "structured-required",
                 retryPolicy: STRUCTURED_REQUIRED_PI_RETRY_POLICY,
+                structuredContractOutput: {
+                    schemaId: "frontend-implementation-contract-v1",
+                    retryOnInvalid: true,
+                },
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
@@ -2545,6 +2569,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "End with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response; the plan text must not contain other balanced JSON objects.",
                     "Each requirement must state its user-observable or logic-observable expectedOutcome. Each interaction must state its trigger and expectedBehavior. IDs plus file paths are not sufficient behavior semantics.",
                     requirementCoverageInstruction,
+                    "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
                     fixedVerificationContext,
                     sourceContext,
@@ -2584,6 +2609,10 @@ async function buildFrontendHybridDagFromTask(sources) {
                 writePolicy: "read-only",
                 outputMode: "structured-required",
                 retryPolicy: STRUCTURED_REQUIRED_PI_RETRY_POLICY,
+                structuredContractOutput: {
+                    schemaId: "frontend-implementation-contract-v1",
+                    retryOnInvalid: true,
+                },
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
@@ -2716,18 +2745,12 @@ async function buildFrontendHybridDagFromTask(sources) {
                         ? ["frontend-lint-baseline-shell"]
                         : []),
                 ],
-                role: "implementer",
-                executor: "pi",
-                toolProfile: "write",
-                complexity: resolveWriterComplexity(taskConfig),
-                writePolicy: "exclusive",
-                writeSet: implementPaths.writeSet,
-                allowedPaths: implementPaths.allowedPaths,
-                forbiddenPaths,
-                skills: FRONTEND_BOUNDED_IMPLEMENT_SKILLS,
-                writerOutcomePolicy: {
-                    type: "implementation-outcome-v1",
-                },
+                ...buildFrontendWriterNodeDefaults({
+                    complexity: resolveWriterComplexity(taskConfig),
+                    writeSet: implementPaths.writeSet,
+                    allowedPaths: implementPaths.allowedPaths,
+                    forbiddenPaths,
+                }),
                 outputContract: "First non-empty line must be exactly one of: IMPLEMENTATION_OUTCOME: changed; IMPLEMENTATION_OUTCOME: already-satisfied; IMPLEMENTATION_OUTCOME: blocked. Then a Markdown delivery summary with Contract Ref (path/schema/hash), Changed Files, Requirements Implemented, UI States, Tests Changed, Verification Attempts, Deviations, and Residual Risks. Follow fixed stages: contract confirm → tests → component/state → API/Mock → focused checks → diff cleanup.",
                 subtask_prompt: [
                     "Implement against the validated run-owned Frontend Implementation Contract from frontend-prewrite-gate-shell (path/schema/hash). Do not rebuild the contract from Markdown alone.",
@@ -2781,18 +2804,12 @@ async function buildFrontendHybridDagFromTask(sources) {
                 id: "frontend-repair-pi",
                 depends_on: ["frontend-verify-assess-shell", implementId],
                 runIf: "$.nodes['frontend-verify-assess-shell'].json.eligible == true",
-                role: "implementer",
-                executor: "pi",
-                toolProfile: "write",
-                complexity: resolveWriterComplexity(taskConfig),
-                writePolicy: "exclusive",
-                writeSet: implementPaths.writeSet,
-                allowedPaths: implementPaths.allowedPaths,
-                forbiddenPaths,
-                skills: FRONTEND_BOUNDED_IMPLEMENT_SKILLS,
-                writerOutcomePolicy: {
-                    type: "implementation-outcome-v1",
-                },
+                ...buildFrontendWriterNodeDefaults({
+                    complexity: resolveWriterComplexity(taskConfig),
+                    writeSet: implementPaths.writeSet,
+                    allowedPaths: implementPaths.allowedPaths,
+                    forbiddenPaths,
+                }),
                 outputContract: "First non-empty line must be exactly one of: IMPLEMENTATION_OUTCOME: changed; IMPLEMENTATION_OUTCOME: already-satisfied; IMPLEMENTATION_OUTCOME: blocked. Then a repair summary for an eligible repairable assessment. Must not expand writeSet, re-interpret requirements, skip tests, or enable Mock by default.",
                 subtask_prompt: [
                     "Read contracts/frontend-repair-assessment.json and the validated frontend implementation contract.",

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

@@ -4,6 +4,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../../shared/git-progress.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";
 import { resolveContextPolicy } from "./context-policy.js";
 import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./prompt.js";
@@ -12,6 +13,8 @@ import { buildOutputLimitRecoverySection, loadBackendTestWriterProgressForRetry,
 import { computeBackoffDelayMs, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, } 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 { 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";
@@ -138,6 +141,20 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             buildProtocolRetryInstruction(task.outputProtocol, previousProtocolReason),
         ].join("\n");
     }
+    if (previousFailureCategory === "invalid-output" &&
+        task.structuredContractOutput &&
+        previousProtocolReason) {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt produced an invalid frontend implementation contract:",
+            previousProtocolReason,
+            "Return exactly one fenced json block conforming to the frontend-implementation-contract-v1 schema.",
+            "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "writer-empty-diff") {
         const maxAttempts = task.retryPolicy?.maxAttempts ?? 3;
         // When a completeness progress exists for this writer, fold the concrete
@@ -395,6 +412,21 @@ export async function executeDagNode(input) {
         await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
     };
     const failSkillSnapshot = (error) => failBeforePrompt(error, "skill-snapshot-integrity");
+    const skipFrontendWriter = async (admission) => {
+        const skippedAt = new Date().toISOString();
+        node.startedAt ??= skippedAt;
+        node.frontendWriterAdmission = admission;
+        node.status = "SKIPPED";
+        node.skippedReason = "frontend-prewrite-not-authorized";
+        node.finishedAt = skippedAt;
+        node.lastActivityAt = skippedAt;
+        node.durationMs = durationBetween(node.startedAt, node.finishedAt);
+        node.timing = { retryBackoffMs: 0, settlementCleanupMs: 0 };
+        state.nodes[nodeId].nodeRecordPath = path.join(runDir, `${nodeId}.json`);
+        await writeNodeRecord(runDir, nodeId, state.nodes[nodeId]);
+        await input.persistState();
+        await notifyNodeObserver(input.observer, "onNodeFinish", nodeId, state);
+    };
     if (task.finalWriteSetApproval) {
         const authorization = parseAndValidateFinalWriteSetApproval({ task, spec, state });
         if (!authorization.ok) {
@@ -423,6 +455,30 @@ export async function executeDagNode(input) {
             effectiveWriteSet: [...authorization.effectiveWriteSet],
         };
     }
+    if (FRONTEND_WRITER_NODE_IDS.includes(nodeId)) {
+        const admission = await readFrontendPrewriteResult(runDir);
+        if (!admission.ok) {
+            await skipFrontendWriter(undefined);
+            return;
+        }
+        const decision = isFrontendWriterAuthorized(admission.result);
+        const record = {
+            schemaVersion: 1,
+            writerNodeId: nodeId,
+            decision,
+            sourceArtifact: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+            artifactHash: admission.artifactHash,
+            checkedAt: new Date().toISOString(),
+            reason: decision === "denied"
+                ? `classification: ${admission.result.classification}`
+                : null,
+        };
+        if (decision === "denied") {
+            await skipFrontendWriter(record);
+            return;
+        }
+        node.frontendWriterAdmission = record;
+    }
     let projectGovernanceContext;
     if (task.governanceStandardReview) {
         try {
@@ -689,6 +745,39 @@ export async function executeDagNode(input) {
                 previousProtocolReason = undefined;
             }
         }
+        // R1: structured contract nodes self-validate their output so schema,
+        // typo, and null violations surface as retryable invalid-output at the
+        // producing node instead of failing the whole run at the prewrite gate.
+        if (result.ok && task.structuredContractOutput) {
+            const validator = getStructuredContractValidator(task.structuredContractOutput.schemaId);
+            if (validator) {
+                const contractText = canonicalNodeOutput(result);
+                const contractCheck = await validator({
+                    runDir,
+                    text: contractText,
+                    sourceBinding: spec.sourceBinding,
+                });
+                if (!contractCheck.ok) {
+                    result = {
+                        ...result,
+                        ok: false,
+                        failureCategory: "invalid-output",
+                        stderr: [result.stderr, contractCheck.reason]
+                            .filter(Boolean)
+                            .join("\n"),
+                    };
+                    previousProtocolReason = contractCheck.reason;
+                }
+                else {
+                    previousProtocolReason = undefined;
+                }
+            }
+            else {
+                // DAG spec validation rejects unknown schemaIds; this is a
+                // defensive fallback for a registry that has not been populated.
+                console.warn(`[run-dag] warning: no structured contract validator registered for schemaId ${task.structuredContractOutput.schemaId}; skipping node self-check`);
+            }
+        }
         const attemptFinishedAt = new Date().toISOString();
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;

package/dist/workflows/dag/recovery-recommendation.js

@@ -269,3 +269,61 @@ export function planDagRecovery(input) {
     }
     return planByNormalizedCategory(input);
 }
+/**
+ * Phase 6: route a frontend recovery outcome to a recovery CTA (read-only; never
+ * mutates a run's status). The six outcomes map to the existing recovery actions
+ * so the Console recovery page reuses the current CTA surface.
+ */
+export function recommendFrontendRecoveryOutcome(outcome) {
+    switch (outcome) {
+        case "none":
+            return {
+                action: "none",
+                summary: "未发生前端恢复；按普通终态展示。",
+                reason: "该 frontend-implementation 根没有触发自动恢复。",
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "recovered":
+            return {
+                action: "none",
+                summary: "自动恢复成功；child 已重新实现并通过验证。",
+                reason: "parent 的 transient 失败已由 child 恢复，全链按 root 计一次成功。",
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "candidate-contract-invalid":
+            return {
+                action: "manual-review",
+                summary: "方案输出无效：candidate JSON 无法解析/推导，重试用尽。",
+                reason: "建议人工检查需求或重新生成方案后再跑。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        case "prewrite-blocked":
+            return {
+                action: "manual-review",
+                summary: "治理门禁阻断：source stale / writeSet 越界 / Mock policy / contract 违规。",
+                reason: "需人工修正任务边界/事实后重跑，不自动重试。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        case "repair-exhausted":
+            return {
+                action: "rerun-after-fix",
+                summary: "自动修复未通过：verify 失败，1 次 repair 后 reverify 仍失败。",
+                reason: "建议 `dag rerun` 或人工排查。",
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "loop-agent dag rerun --run-id <runId>",
+            };
+        case "auto-recovery-blocked":
+            return {
+                action: "manual-review",
+                summary: "自动恢复被阻止：rollback 无法证明完整或存在外部/越界修改。",
+                reason: "必须人工介入，禁止自动覆盖用户文件。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+    }
+}

package/dist/workflows/dag/runner.js

@@ -1,4 +1,5 @@
 import { readdir, readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { hostname } from "node:os";
 import path from "node:path";
@@ -6,7 +7,7 @@ import { isHardBudgetBreached, resolveEffectiveMaxConcurrent, } from "../../appl
 import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-store.js";
 import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
 import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
-import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
+import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
 import { moveToCompletedRunDir, moveToPausedRunDir, prepareRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { createDagNodeExecutor } from "./executor-registry.js";
@@ -21,8 +22,9 @@ import { createSkillSnapshot, prepareSkillSnapshotForContinuation, writeSkillSna
 import { captureWorkspaceCheckpoint, WORKSPACE_CHECKPOINT_START_REL, WORKSPACE_CHECKPOINT_TERMINAL_REL, writeWorkspaceCheckpoint, } from "./workspace-checkpoint.js";
 import { buildNodePrompt, buildNodePromptWithResolvedSkillInstructions, executeDagNode, } from "./node-execution.js";
 import { runConvergencePassController, } from "./convergence/controller.js";
-import { executeDagRanksOnce, isConditionSkippedReason } from "./scheduler.js";
+import { executeDagRanksOnce, FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isConditionSkippedReason, readFrontendPrewriteResult, } from "./scheduler.js";
 import { topoSortToRanks } from "./topo.js";
+import { isFrontendWriterTransientPartialWrite } from "./frontend-writer-recovery.js";
 import { parseDagSpec, resolveModelForTask, } from "./types.js";
 import { executeDynamicCondition } from "./dynamic-runtime/condition.js";
 import { executeDynamicLoopUntil } from "./dynamic-runtime/loop-until.js";
@@ -448,6 +450,39 @@ async function executeDagCheckpoint(input) {
         void persistState().catch(() => { });
     }, runnerLivenessPolicy.heartbeatIntervalMs);
     heartbeatTimer.unref();
+    // Graceful terminal persistence: an outer SIGTERM/SIGINT (operator hard
+    // timeout, supervision layer, or shell wall-clock) must not leave the run
+    // orphaned in RUNNING with a dead heartbeat. Persist a terminal failed
+    // state with an explicit terminalReason before exiting so downstream
+    // liveness/doctor tooling sees a diagnosable terminal instead of an orphan.
+    let terminalSignal;
+    const shutdownOnSignal = (signal) => {
+        if (terminalSignal)
+            return;
+        terminalSignal = signal;
+        clearInterval(heartbeatTimer);
+        if (state.runner)
+            state.runner.heartbeatAt = new Date().toISOString();
+        state.status = "failed";
+        state.finishedAt = new Date().toISOString();
+        state.terminalReason = `runner terminated by ${signal} before run completion`;
+        console.warn(`[run-dag] received ${signal}; persisting terminal state and exiting`);
+        const exit = () => process.exit(signal === "SIGINT" ? 130 : 143);
+        // Best-effort atomic persist with a hard exit deadline so a stuck write
+        // queue cannot keep the process alive past the supervisor's kill window.
+        const hardExit = setTimeout(exit, 5000);
+        hardExit.unref();
+        void persistState()
+            .catch(() => { })
+            .finally(() => {
+            clearTimeout(hardExit);
+            exit();
+        });
+    };
+    const onSigTerm = () => shutdownOnSignal("SIGTERM");
+    const onSigInt = () => shutdownOnSignal("SIGINT");
+    process.once("SIGTERM", onSigTerm);
+    process.once("SIGINT", onSigInt);
     try {
         const tasksById = new Map(spec.tasks.map((task) => [task.id, task]));
         const baseExecuteNode = input.executeNode ??
@@ -504,6 +539,7 @@ async function executeDagCheckpoint(input) {
             tasksById,
             maxConcurrent,
             persistState,
+            runDir,
             abortSignal: input.abortSignal,
             createExecuteNodeForRank: (rankWriterNodeIds) => buildRankAwareExecuteNode({
                 baseExecuteNode,
@@ -595,17 +631,54 @@ async function executeDagCheckpoint(input) {
             runDir = await moveToPausedRunDir(runDir, pausedRunDir);
         }
         else {
-            finalizeTerminalRunStatus(state, spec.tasks.length);
+            const { recoveryPending } = await finalizeTerminalRunStatus(state, spec.tasks.length, runDir, cwd);
             await persistState();
-            await notifyRunObserver(input.observer, "onRunFinish", state);
-            try {
-                const terminalCheckpoint = await captureWorkspaceCheckpoint(cwd);
-                await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_TERMINAL_REL, terminalCheckpoint);
+            if (recoveryPending) {
+                // Recovery coordinator (phase 3c AC-2/AC-3): materialize the reserved
+                // child and run it synchronously. Dynamic import avoids a static
+                // runner ↔ frontend-recovery-run module cycle. stageRecoveryChild
+                // locates the parent via the canonical active/ layout, so recovery
+                // only fires when this run is still the canonical active run dir
+                // (direct runDagContinuation callers using an arbitrary runDir keep
+                // the previous scheduler-layer skip semantics).
+                const canonicalActiveDir = getDagRunDir(cwd, "active", state.runId);
+                if (path.resolve(runDir) === path.resolve(canonicalActiveDir)) {
+                    const { stageRecoveryChild } = await import("./frontend-recovery-run.js");
+                    const staged = await stageRecoveryChild({
+                        cwd,
+                        parentRunId: state.runId,
+                    });
+                    // stageRecoveryChild CAS-advanced the parent's on-disk lineage
+                    // (child-staging → child-running + childRunId). Refresh the in-memory
+                    // copy so the terminal persistState below does not regress the parent
+                    // back to stale child-staging.
+                    const parentOnDisk = await readDagRunState(runDir);
+                    state.frontendRecoveryState = parentOnDisk.frontendRecoveryState;
+                    const childState = await readDagRunState(staged.childRunDir);
+                    const childSpec = await readDagRunSpec(staged.childRunDir);
+                    await runDagContinuation({
+                        cwd,
+                        spec: childSpec,
+                        state: childState,
+                        runDir: staged.childRunDir,
+                        maxConcurrent,
+                        executeNode: input.executeNode,
+                        observer: input.observer,
+                        abortSignal: input.abortSignal,
+                    });
+                }
             }
-            catch (error) {
-                console.warn(`[run-dag] warning: failed to write workspace terminal checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+            await notifyRunObserver(input.observer, "onRunFinish", state);
+            if (!recoveryPending) {
+                try {
+                    const terminalCheckpoint = await captureWorkspaceCheckpoint(cwd);
+                    await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_TERMINAL_REL, terminalCheckpoint);
+                }
+                catch (error) {
+                    console.warn(`[run-dag] warning: failed to write workspace terminal checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                runDir = await moveToCompletedRunDir(runDir, completedRunDir);
             }
-            runDir = await moveToCompletedRunDir(runDir, completedRunDir);
         }
         await relocateRunArtifactPaths({
             runDir,
@@ -628,6 +701,8 @@ async function executeDagCheckpoint(input) {
     }
     finally {
         clearInterval(heartbeatTimer);
+        process.removeListener("SIGTERM", onSigTerm);
+        process.removeListener("SIGINT", onSigInt);
     }
 }
 async function notifyRunObserver(observer, event, state) {
@@ -695,7 +770,153 @@ function isSuccessfulConvergenceTerminal(state) {
         return true;
     return SUCCESSFUL_CONVERGENCE_TERMINAL_REASONS.has(reason);
 }
-function finalizeTerminalRunStatus(state, taskCount) {
+function buildFrontendRecoveryIntent(state, failureSource) {
+    const existing = state.frontendRecoveryState;
+    const requestId = existing?.requestId ?? randomUUID();
+    return {
+        schemaVersion: 1,
+        phase: "child-staging",
+        requestId,
+        recoveryRootRunId: existing?.recoveryRootRunId ?? state.runId,
+        parentRunId: state.runId,
+        ...(existing?.childRunId ? { childRunId: existing.childRunId } : {}),
+        attemptId: existing?.attemptId ?? `recovery-${requestId}`,
+        attemptIndex: existing?.attemptIndex ?? 0,
+        continuationCount: existing?.continuationCount ?? 0,
+        ...(failureSource ? { failureSource } : {}),
+        revision: (existing?.revision ?? 0) + 1,
+    };
+}
+function buildCandidateContractInvalidResult(state, result, artifactHash) {
+    const recovery = state.frontendRecoveryState;
+    return {
+        schemaVersion: 1,
+        outcome: "candidate-contract-invalid",
+        origin: {
+            kind: "frontend-prewrite-gate",
+            parentRunId: recovery?.parentRunId ?? state.runId,
+            ...(recovery?.childRunId ? { childRunId: recovery.childRunId } : {}),
+            requestId: recovery?.requestId ?? "",
+            failedNodeId: result.selectedPlanNodeId,
+        },
+        failureClass: {
+            code: "candidate-contract-invalid",
+            classification: result.classification,
+            reason: result.failureReason ?? "candidate contract invalid",
+        },
+        evidenceRefs: [
+            {
+                runId: state.runId,
+                relativePath: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+                sha256: artifactHash,
+            },
+        ],
+    };
+}
+function buildWriterPartialWriteBlockedResult(state, failedNodeId, reason) {
+    const recovery = state.frontendRecoveryState;
+    return {
+        schemaVersion: 1,
+        outcome: "auto-recovery-blocked",
+        origin: {
+            kind: "frontend-writer",
+            parentRunId: recovery?.parentRunId ?? state.runId,
+            ...(recovery?.childRunId ? { childRunId: recovery.childRunId } : {}),
+            requestId: recovery?.requestId ?? "",
+            failedNodeId,
+        },
+        failureClass: {
+            code: "writer-transient-partial-write",
+            classification: "transient",
+            reason,
+        },
+        evidenceRefs: [],
+    };
+}
+function settleFrontendRecovery(state, outcome) {
+    const recovery = state.frontendRecoveryState;
+    if (!recovery)
+        return;
+    recovery.phase = "settled";
+    if (!state.frontendRecoveryResult) {
+        state.frontendRecoveryResult = {
+            schemaVersion: 1,
+            outcome,
+            origin: {
+                kind: "frontend-prewrite-gate",
+                parentRunId: recovery.parentRunId,
+                ...(recovery.childRunId ? { childRunId: recovery.childRunId } : {}),
+                requestId: recovery.requestId,
+                failedNodeId: "",
+            },
+            evidenceRefs: [],
+        };
+    }
+}
+export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
+    const repoRoot = cwd ?? path.resolve(runDir, "..", "..", "..", "..");
+    // Terminal override: a denied frontend writer must never surface as a
+    // mechanical partial_failed just because prewrite FINISHED while the writer
+    // was SKIPPED. Fail closed on retryable-invalid/blocked before aggregation.
+    let recoveryPending = false;
+    const hasFrontendWriter = Object.keys(state.nodes).some((id) => FRONTEND_WRITER_NODE_IDS.includes(id));
+    if (hasFrontendWriter) {
+        const admission = await readFrontendPrewriteResult(runDir);
+        if (admission.ok) {
+            if (admission.result.classification === "blocked") {
+                state.status = "failed";
+                return { recoveryPending: false };
+            }
+            if (admission.result.classification === "retryable-invalid") {
+                const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+                if (continuationCount >= 1) {
+                    // Continuation quota exhausted: a second retryable-invalid candidate
+                    // is authoritative candidate-contract-invalid → forced failed.
+                    state.frontendRecoveryResult = buildCandidateContractInvalidResult(state, admission.result, admission.artifactHash);
+                    state.status = "failed";
+                    return { recoveryPending: false };
+                }
+                // Root continuation still available: record the recovery intent and let
+                // mechanical aggregation settle partial_failed/failed. The parent keeps
+                // phase != settled (recovery in progress) and no final root manifest.
+                state.frontendRecoveryState = buildFrontendRecoveryIntent(state);
+                recoveryPending = true;
+            }
+        }
+    }
+    // Phase 5: writer transient partial write → rollback + recovery intent. Only
+    // for frontend-implementation writers with a remaining root continuation, and
+    // only when the rollback journal (captured before the provider call) restores
+    // cleanly; otherwise the run stays failed with auto-recovery-blocked.
+    if (hasFrontendWriter && !recoveryPending) {
+        const writerNodeId = FRONTEND_WRITER_NODE_IDS.find((id) => {
+            const node = state.nodes[id];
+            return (node &&
+                node.status === "ERROR" &&
+                isFrontendWriterTransientPartialWrite({
+                    failureCategory: node.failureCategory,
+                }));
+        });
+        if (writerNodeId) {
+            const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+            if (continuationCount < 1) {
+                const { rollbackFrontendWriter } = await import("./frontend-writer-recovery.js");
+                const rollback = await rollbackFrontendWriter({
+                    cwd: repoRoot,
+                    parentRunId: state.runId,
+                });
+                if (rollback.ok) {
+                    state.frontendRecoveryState = buildFrontendRecoveryIntent(state, "frontend-implement-pi");
+                    recoveryPending = true;
+                }
+                else {
+                    state.frontendRecoveryResult = buildWriterPartialWriteBlockedResult(state, writerNodeId, rollback.reason);
+                    state.status = "failed";
+                    return { recoveryPending: false };
+                }
+            }
+        }
+    }
     const finishedCount = Object.values(state.nodes).filter((n) => n.status === "FINISHED").length;
     const { supersededIds, supersededFailures } = collectSupersededIntermediateFailures(state);
     if (state.convergence && supersededFailures.length > 0) {
@@ -719,6 +940,19 @@ function finalizeTerminalRunStatus(state, taskCount) {
     else {
         state.status = "failed";
     }
+    // Terminal recovery bookkeeping for a child attempt: a child that finished
+    // recovered settles its own lineage; any other child terminal settles as
+    // auto-recovery-blocked (phase 3 performs no further recovery).
+    const recovery = state.frontendRecoveryState;
+    if (recovery && recovery.attemptIndex >= 1) {
+        if (state.status === "finished") {
+            settleFrontendRecovery(state, "recovered");
+        }
+        else if (!state.frontendRecoveryResult) {
+            settleFrontendRecovery(state, "auto-recovery-blocked");
+        }
+    }
+    return { recoveryPending };
 }
 function concurrentSiblingWriteSetsForNode(rankWriterNodeIds, nodeId, tasksById) {
     if (rankWriterNodeIds.length <= 1)