@tea-agent/loop-agent 0.35.2 → 0.35.3

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 ?? {
@@ -2339,6 +2359,12 @@ async function buildFrontendHybridDagFromTask(sources) {
             `Every requirement MUST have a non-empty expectedOutcome. Every interaction MUST have non-empty trigger and expectedBehavior. UI states with applicable=true MUST have non-empty expectedBehavior. Empty strings or omitted fields for these will cause contract rejection.`,
         ].join("\n")
         : "";
+    const verificationTargetFileInstruction = [
+        `## Verification target file semantics`,
+        `verificationTargets[].file is the code file that the target verifies (the file the writer changes), NOT where the command is defined.`,
+        `Non-static targets (type unit/component/integration/mock) MUST set file to a concrete code file inside the implementation writeSet (task allowedPaths); the prewrite gate rejects any non-static target whose file falls outside the writeSet.`,
+        `Command-level checks that run project-wide (all tests, typecheck, build, governance) MUST use type "static" and must NOT be bound as non-static targets with file=package.json/tsconfig.json/vite.config.ts/scripts/*. Static targets are exempt from the writeSet containment check.`,
+    ].join("\n");
     const strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
     const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
@@ -2532,6 +2558,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 +2575,8 @@ 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.",
+                    verificationTargetFileInstruction,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
                     fixedVerificationContext,
                     sourceContext,
@@ -2584,6 +2616,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,
@@ -2598,6 +2634,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "End the response with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer when the design review requests revision: 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. Bind it to the supplied task sources; map every requirement and applicable UI state to concrete implementation and verification targets or an explicit blocking evidence gap. Do not include secrets or unsafe paths.",
                     "Preserve each requirement expectedOutcome and each interaction trigger/expectedBehavior in the revised contract; do not reduce behavior semantics to IDs and paths.",
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
+                    verificationTargetFileInstruction,
                     fixedVerificationContext,
                     sourceContext,
                     frontendContractSchemaBlock,
@@ -2716,18 +2753,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 +2812,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)