@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.11

package/dist/workflows/dag/runner.js

@@ -1,5 +1,5 @@
 import { readdir, readFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { hostname } from "node:os";
 import path from "node:path";
@@ -7,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, readDagRunSpec, readDagRunState, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
+import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, readDagRunState, requireActiveDagRun, } from "./lifecycle.js";
 import { markInterruptNeedsReconcile, mergeAbortSignals, readInterruptRequest, runnerIdentityFromState, settleDagInterrupt, startInterruptWatcher, } from "./interrupt-request.js";
 import { moveToCompletedRunDir, moveToPausedRunDir, prepareRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
@@ -26,7 +26,13 @@ import { runConvergencePassController, } from "./convergence/controller.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 { classifyReviewIssueCategoryFailureOwner, readCommittedDesignRequestFact, readCommittedReviewRequestFact, writeFrontendReviewFindingsPrd, } from "./frontend-review-findings.js";
+import { bindFrontendShapeStateToRunTopology, commitFrontendShapeTransitionCas, commitRuntimeFrontendShapeFact, isCanonicalFrontendShapeDag, } from "./frontend-shape-facts.js";
+import { assertFrontendTopologyBinding, buildFrontendTopologyBinding, computeFrontendShapeSourceDigest, } from "./frontend-shape.js";
+import { ensureFrontendShapeCapsuleRecord } from "./frontend-shape-capsule-store.js";
 import { parseDagSpec, resolveModelForTask, } from "./types.js";
+import { computeActionPayloadHash, } from "../../infrastructure/console/operation-store.js";
+import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, claimDagRecoveryLease, } from "./recovery-lease.js";
 import { executeDynamicCondition } from "./dynamic-runtime/condition.js";
 import { executeDynamicLoopUntil } from "./dynamic-runtime/loop-until.js";
 import { executeDynamicMapExpansion } from "./dynamic-runtime/map.js";
@@ -46,6 +52,51 @@ export function toKebabSlug(text, maxLen = 40) {
         .replace(/^-|-$/g, "")
         .slice(0, maxLen) || "dag");
 }
+export async function loadCanonicalFrontendTaskSourceBinding(cwd, spec) {
+    const binding = spec.sourceBinding;
+    if (!binding?.taskId)
+        throw new Error("canonical frontend DAG requires sourceBinding.taskId");
+    const requirement = binding.sources.find((source) => source.kind === "requirement");
+    if (!requirement)
+        throw new Error("canonical frontend DAG requires a bound requirement source");
+    const constraint = binding.sources.find((source) => source.kind === "constraint");
+    const readFreshSource = async (source) => {
+        let bytes;
+        try {
+            bytes = await readFile(path.resolve(cwd, source.path));
+        }
+        catch (error) {
+            throw new Error(`canonical frontend ${source.kind} source freshness read failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const actualSha256 = createHash("sha256").update(bytes).digest("hex");
+        if (actualSha256 !== source.sha256) {
+            throw new Error(`canonical frontend ${source.kind} source sha256 drifted: expected ${source.sha256}, received ${actualSha256}`);
+        }
+        return bytes.toString("utf8");
+    };
+    const requirementMarkdown = await readFreshSource(requirement);
+    const constraintMarkdown = constraint ? await readFreshSource(constraint) : "";
+    return {
+        taskId: binding.taskId,
+        requirementMarkdown,
+        constraintMarkdown,
+        sourceDigest: computeFrontendShapeSourceDigest({ requirementMarkdown, constraintMarkdown }),
+    };
+}
+export async function ensureFreshFrontendShapeCapsuleRecord(input) {
+    const freshSource = await loadCanonicalFrontendTaskSourceBinding(input.cwd, input.spec);
+    if (freshSource.taskId !== input.canonicalSource.taskId ||
+        freshSource.sourceDigest !== input.canonicalSource.sourceDigest) {
+        throw new Error("canonical frontend task source freshness binding drifted before transition commit");
+    }
+    await (input.ensureRecord ?? ensureFrontendShapeCapsuleRecord)({
+        repoRoot: input.cwd,
+        taskId: input.canonicalSource.taskId,
+        parentRunId: input.parentRunId,
+        terminalOutcome: input.terminalOutcome,
+        capsule: input.capsule,
+    });
+}
 export function extractTaskIdFromDagSpec(spec) {
     if (spec.objective) {
         const match = spec.objective.match(TASK_ID_IN_TEXT_PATTERN);
@@ -180,6 +231,15 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
         ...(opts.workerAssociation
             ? { workerAssociation: structuredClone(opts.workerAssociation) }
             : {}),
+        ...(isCanonicalFrontendShapeDag(new Map(spec.tasks.map((task) => [task.id, task])))
+            ? {
+                frontendShapeState: {
+                    frozenTopology: buildFrontendTopologyBinding(spec.tasks.map((task) => task.id)),
+                    revision: 0,
+                    committedFacts: {},
+                },
+            }
+            : {}),
     };
     initRunBudgetLedger(state, spec.budget);
     return state;
@@ -301,6 +361,7 @@ export async function runDag(spec, opts) {
             activeRunDir,
             completedRunDir,
             pausedRunDir,
+            recovery: opts.recovery,
         });
     }
     finally {
@@ -322,6 +383,16 @@ export async function runDagContinuation(opts) {
     await assertTaskContractBindingConsistent({ repoRoot: opts.cwd, spec: opts.spec });
     const { maxConcurrent } = resolveEffectiveMaxConcurrent(Math.max(1, opts.maxConcurrent ?? 4), opts.spec.budget);
     const state = opts.state;
+    const canonicalFrontend = isCanonicalFrontendShapeDag(new Map(opts.spec.tasks.map((task) => [task.id, task])));
+    if (canonicalFrontend) {
+        assertFrontendTopologyBinding(state.frontendShapeState?.frozenTopology, opts.spec.tasks.map((task) => task.id));
+    }
+    else if (state.frontendShapeState) {
+        throw new Error("non-frontend DAG unexpectedly contains frontend topology state");
+    }
+    if (state.frontendShapeState?.terminalOutcome) {
+        throw new Error(`dag run ${state.runId} is terminal due to frontend shape ${state.frontendShapeState.terminalOutcome}`);
+    }
     state.status = "running";
     const resumedAt = new Date().toISOString();
     state.runner = {
@@ -347,6 +418,7 @@ export async function runDagContinuation(opts) {
         activeRunDir,
         completedRunDir,
         pausedRunDir,
+        recovery: opts.recovery,
     });
 }
 export async function resumeDagRun(opts) {
@@ -449,9 +521,13 @@ export async function resumeDagRun(opts) {
 }
 async function executeDagCheckpoint(input) {
     const { spec, state, ranks, runDir: initialRunDir, cwd, maxConcurrent, completedRunDir, pausedRunDir, } = input;
+    bindFrontendShapeStateToRunTopology(state);
     let runDir = initialRunDir;
     let stateWriteQueue = Promise.resolve();
+    let shapeTransitionBarrier;
     const persistState = async (options) => {
+        if (shapeTransitionBarrier)
+            await shapeTransitionBarrier;
         stateWriteQueue = stateWriteQueue.then(() => writeRunState(runDir, state, options));
         await stateWriteQueue;
     };
@@ -576,12 +652,50 @@ async function executeDagCheckpoint(input) {
                 .map((rank) => rank.filter((nodeId) => nodeId === "closeout-pi"))
                 .filter((rank) => rank.length > 0)
             : [];
+        const canonicalFrontendSource = isCanonicalFrontendShapeDag(tasksById)
+            ? await loadCanonicalFrontendTaskSourceBinding(cwd, spec)
+            : undefined;
         const executeRanks = (selectedRanks) => executeDagRanksOnce({
             state,
             ranks: selectedRanks,
             tasksById,
             maxConcurrent,
             persistState,
+            commitFrontendShapeTransition: async (request) => {
+                let releaseBarrier;
+                shapeTransitionBarrier = new Promise((resolve) => {
+                    releaseBarrier = resolve;
+                });
+                try {
+                    if (!canonicalFrontendSource) {
+                        throw new Error("frontend shape transition requires canonical task source binding");
+                    }
+                    return await commitFrontendShapeTransitionCas({
+                        state,
+                        tasksById,
+                        request,
+                        taskSourceDigest: canonicalFrontendSource.sourceDigest,
+                        ensureRecord: async (capsule, terminalOutcome) => {
+                            await ensureFreshFrontendShapeCapsuleRecord({
+                                cwd,
+                                spec,
+                                canonicalSource: canonicalFrontendSource,
+                                parentRunId: state.runId,
+                                terminalOutcome,
+                                capsule,
+                            });
+                        },
+                        persist: async (nextState) => {
+                            stateWriteQueue = stateWriteQueue.then(() => writeRunState(runDir, nextState));
+                            await stateWriteQueue;
+                        },
+                    });
+                }
+                finally {
+                    releaseBarrier();
+                    shapeTransitionBarrier = undefined;
+                }
+            },
             runDir,
             abortSignal: input.abortSignal,
             createExecuteNodeForRank: (rankWriterNodeIds) => buildRankAwareExecuteNode({
@@ -617,6 +731,18 @@ async function executeDagCheckpoint(input) {
                 });
                 const node = state.nodes[nodeId];
                 if (node && (node.status === "FINISHED" || node.status === "ERROR")) {
+                    if (node.status === "FINISHED") {
+                        if (canonicalFrontendSource) {
+                            await commitRuntimeFrontendShapeFact({
+                                state,
+                                tasksById,
+                                sourceNodeId: nodeId,
+                                taskId: canonicalFrontendSource.taskId,
+                                requirementMarkdown: canonicalFrontendSource.requirementMarkdown,
+                                constraintMarkdown: canonicalFrontendSource.constraintMarkdown,
+                            });
+                        }
+                    }
                     recordFinishedNodeBudget(state, node);
                     await writeBudgetLedgerArtifacts(runDir, state.budgetLedger);
                     await persistState();
@@ -626,6 +752,9 @@ async function executeDagCheckpoint(input) {
         let pausedByNodeId;
         while (true) {
             pausedByNodeId = await executeRanks(convergenceRanks);
+            if (state.frontendShapeState?.terminalOutcome) {
+                break;
+            }
             if (pausedByNodeId) {
                 break;
             }
@@ -681,7 +810,7 @@ async function executeDagCheckpoint(input) {
             runDir = await moveToPausedRunDir(runDir, pausedRunDir);
         }
         else {
-            const { recoveryPending } = await finalizeTerminalRunStatus(state, spec.tasks.length, runDir, cwd);
+            const { recoveryPending, recovery: recoveryTrigger } = await finalizeTerminalRunStatus(state, spec.tasks.length, runDir, cwd, spec.frontendRecovery?.maxContinuations ?? 1);
             await finalizeRunOwnedInterrupt({
                 runDir,
                 state,
@@ -689,56 +818,103 @@ async function executeDagCheckpoint(input) {
                 interruptAborted: interruptController.signal.aborted,
             });
             await persistState();
-            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,
+            if (recoveryPending && input.recovery && recoveryTrigger) {
+                // M6 recovery operation controller path: construct/reuse one recovery
+                // operation keyed by a deterministic clientRequestId and supervise it
+                // to terminal, instead of staging an in-process child run.
+                const created = await createRecoveryOperation({
+                    cwd,
+                    runDir,
+                    spec,
+                    state,
+                    trigger: recoveryTrigger,
+                    deps: input.recovery,
+                });
+                if (created.kind === "conflict") {
+                    // Same clientRequestId with a different payload → fail closed; never
+                    // create a second recovery operation (AC-004).
+                    state.status = "failed";
+                    state.terminalReason =
+                        "frontend recovery request-id reuse conflict";
+                    state.frontendRecoveryResult = buildRecoveryResultForTrigger(state, recoveryTrigger, "auto-recovery-blocked");
+                }
+                else if (created.kind === "lease-held") {
+                    // A different recovery entrance has already durably claimed this
+                    // parent. Do not "help" by running its operation: that would reopen
+                    // the exact two-child-DAG race the lease prevents.
+                    state.status = "failed";
+                    state.terminalReason =
+                        "frontend recovery parent lease already held";
+                    state.frontendRecoveryResult = buildRecoveryResultForTrigger(state, recoveryTrigger, "auto-recovery-blocked");
+                }
+                else {
+                    const { runRecoveryOperationController } = await import("./frontend-recovery-controller.js");
+                    const result = await runRecoveryOperationController({
+                        operationId: created.operation.operationId,
                         parentRunId: state.runId,
+                        observeOnly: created.kind === "observed",
+                        deps: {
+                            ...input.recovery,
+                            failureOwner: input.recovery.failureOwner ??
+                                recoveryTrigger.failureOwner,
+                            protocolFailureReason: input.recovery.protocolFailureReason ??
+                                recoveryTrigger.protocolFailureReason,
+                            recoveryMode: input.recovery.recoveryMode ?? recoveryTrigger.recoveryMode,
+                        },
                     });
-                    // 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,
-                    });
+                    // The recovery CLI stages its child by writing a fresh
+                    // `frontendRecoveryState` into the parent run on disk. A successful
+                    // operation without that bound lineage is not a successful recovery:
+                    // fail closed instead of archiving a false-positive `recovered` result.
+                    let recoveryLineageError;
+                    if (result.terminalReason === "succeeded") {
+                        try {
+                            const persistedParentState = await readDagRunState(runDir);
+                            const persistedRecovery = persistedParentState.frontendRecoveryState;
+                            if (!persistedRecovery ||
+                                persistedRecovery.phase !== "child-running" ||
+                                persistedRecovery.parentRunId !== state.runId ||
+                                persistedRecovery.requestId !== recoveryTrigger.requestId ||
+                                !persistedRecovery.childRunId) {
+                                throw new Error("persisted recovery lineage is missing or unbound");
+                            }
+                            await assertRecoveredFrontendLineage({
+                                cwd,
+                                rootRunId: state.runId,
+                                rootRequestId: recoveryTrigger.requestId,
+                                recovery: persistedRecovery,
+                                maxContinuations: spec.frontendRecovery?.maxContinuations ?? 1,
+                            });
+                            state.frontendRecoveryState = structuredClone(persistedRecovery);
+                        }
+                        catch (error) {
+                            recoveryLineageError =
+                                error instanceof Error ? error.message : String(error);
+                            state.status = "failed";
+                            state.terminalReason =
+                                `frontend recovery lineage invalid: ${recoveryLineageError}`;
+                        }
+                    }
+                    state.frontendRecoveryResult = buildRecoveryResultForTrigger(state, recoveryTrigger, result.terminalReason === "succeeded" && !recoveryLineageError
+                        ? "recovered"
+                        : "auto-recovery-blocked");
                 }
             }
             await notifyRunObserver(input.observer, "onRunFinish", state);
-            if (!recoveryPending) {
-                if (input.beforeTerminalArchive) {
-                    await input.beforeTerminalArchive({ runDir, state });
-                    await persistState();
-                }
-                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);
+            if (input.beforeTerminalArchive) {
+                await input.beforeTerminalArchive({ runDir, state });
+                await persistState();
             }
+            // Parent is always archived to completed/ — no active/ retention for an
+            // in-process child CAS anymore (recovery runs as a separate operation).
+            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);
         }
         await relocateRunArtifactPaths({
             runDir,
@@ -766,6 +942,56 @@ async function executeDagCheckpoint(input) {
         process.removeListener("SIGINT", onSigInt);
     }
 }
+async function assertRecoveredFrontendLineage(input) {
+    const maxContinuations = Math.max(1, Math.min(5, input.maxContinuations));
+    let parentRunId = input.rootRunId;
+    let recovery = input.recovery;
+    const recoveryRootRunId = recovery.recoveryRootRunId;
+    const visited = new Set();
+    if (recoveryRootRunId !== input.rootRunId) {
+        throw new Error("recovery root lineage binding mismatch");
+    }
+    for (let depth = 0; depth < maxContinuations; depth += 1) {
+        // The persisted parent intent represents the edge about to be traversed,
+        // so its counters equal the number of already-completed continuation edges.
+        // Each completed child increments both counters exactly once; no edge may
+        // exceed the frozen DAG quota.
+        if (recovery.continuationCount !== depth ||
+            recovery.attemptIndex !== depth) {
+            throw new Error("recovery child lineage counters are not monotonic");
+        }
+        if (recovery.phase !== "child-running" ||
+            recovery.parentRunId !== parentRunId ||
+            recovery.recoveryRootRunId !== recoveryRootRunId ||
+            !recovery.childRunId ||
+            (depth === 0
+                ? recovery.requestId !== input.rootRequestId
+                : recovery.requestId !== parentRunId)) {
+            throw new Error("persisted recovery lineage is missing or unbound");
+        }
+        if (visited.has(recovery.childRunId)) {
+            throw new Error("recovery child lineage contains a cycle");
+        }
+        visited.add(recovery.childRunId);
+        const child = await locateDagRun(input.cwd, recovery.childRunId);
+        if (!child || child.lifecycle !== "completed") {
+            throw new Error("recovery child is not completed");
+        }
+        const childState = await readDagRunState(child.runDir);
+        if (childState.runId !== recovery.childRunId) {
+            throw new Error("recovery child state binding mismatch");
+        }
+        if (childState.status === "finished")
+            return;
+        if (childState.frontendRecoveryResult?.outcome !== "recovered" ||
+            !childState.frontendRecoveryState) {
+            throw new Error("recovery child terminal state is not successful");
+        }
+        parentRunId = childState.runId;
+        recovery = childState.frontendRecoveryState;
+    }
+    throw new Error("recovery child lineage exceeds the continuation quota");
+}
 async function finalizeRunOwnedInterrupt(input) {
     const request = await readInterruptRequest(input.runDir);
     if (!request)
@@ -871,39 +1097,21 @@ function isSuccessfulConvergenceTerminal(state) {
         return true;
     return SUCCESSFUL_CONVERGENCE_TERMINAL_REASONS.has(reason);
 }
-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,
+            parentRunId: state.runId,
+            requestId: state.runId,
+            failedNodeId: result.failureSource ?? "frontend-plan-pi",
         },
         failureClass: {
             code: "candidate-contract-invalid",
             classification: result.classification,
-            reason: result.failureReason ?? "candidate contract invalid",
+            reason: result.findings.map((finding) => `${finding.code}: ${finding.message}`).join("; ") ??
+                "candidate contract invalid",
         },
         evidenceRefs: [
             {
@@ -915,15 +1123,13 @@ function buildCandidateContractInvalidResult(state, result, 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 ?? "",
+            parentRunId: state.runId,
+            requestId: state.runId,
             failedNodeId,
         },
         failureClass: {
@@ -934,64 +1140,119 @@ function buildWriterPartialWriteBlockedResult(state, failedNodeId, 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: [],
-        };
-    }
+function buildRecoveryResultForTrigger(state, trigger, outcome) {
+    return {
+        schemaVersion: 1,
+        outcome,
+        origin: {
+            kind: trigger.failureSource === "frontend-implement-pi"
+                ? "frontend-writer"
+                : "frontend-prewrite-gate",
+            parentRunId: state.runId,
+            requestId: trigger.requestId,
+            failedNodeId: trigger.failureSource,
+        },
+        evidenceRefs: [],
+    };
 }
-export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
+export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd, frontendRecoveryQuota = 1) {
     const repoRoot = cwd ?? path.resolve(runDir, "..", "..", "..", "..");
+    if (state.frontendShapeState?.terminalOutcome &&
+        state.frontendShapeState.transitionCapsule) {
+        state.status = "failed";
+        return { recoveryPending: false };
+    }
     // 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;
+    // was SKIPPED. Fail closed on blocked before aggregation.
+    let recoveryTrigger;
     const skipFrontendRecovery = state.failureCategory === "controller-interrupted" ||
         state.continuation?.writerTransaction !== undefined;
     const hasFrontendWriter = Object.keys(state.nodes).some((id) => FRONTEND_WRITER_NODE_IDS.includes(id));
     if (hasFrontendWriter && !skipFrontendRecovery) {
         const admission = await readFrontendPrewriteResult(runDir);
         if (admission.ok) {
-            if (admission.result.classification === "blocked") {
+            // M8: admission uses the accepted/blocked state machine. A blocked admission whose
+            // failureSource is frontend-plan-pi is the contract-invalid analog of
+            // the old retryable-invalid path (candidate continuation may re-plan);
+            // every other blocked admission is terminal.
+            const planContractInvalid = admission.result.classification === "blocked" &&
+                admission.result.failureSource === "frontend-plan-pi";
+            // A blocked admission caused by the design review committing
+            // `request_design_changes` is a definite finding (not a protocol or
+            // environment error): the design was reviewed and rejected. It is the
+            // design-review analog of review-request-changes — not terminal, but
+            // re-enters the next plan round with the committed design findings.
+            // The failureSource may be frontend-writer-admission-shell or
+            // frontend-design-policy-shell; the committed design fact is the
+            // authoritative signal.
+            const designRequestFact = await readCommittedDesignRequestFact({
+                runDir,
+            });
+            const designRejected = admission.result.classification === "blocked" &&
+                designRequestFact !== undefined;
+            const terminalAdmissionDenial = (admission.result.classification === "blocked" ||
+                admission.result.classification === "stale") &&
+                !planContractInvalid &&
+                !designRejected;
+            if (terminalAdmissionDenial) {
                 state.status = "failed";
                 return { recoveryPending: false };
             }
-            if (admission.result.classification === "retryable-invalid") {
+            if (designRejected && designRequestFact) {
+                state.terminalReason = "design-request-changes";
+                try {
+                    await writeFrontendReviewFindingsPrd({
+                        runDir,
+                        parentRunId: state.runId,
+                        fact: designRequestFact,
+                    });
+                }
+                catch (error) {
+                    console.warn(`[run-dag] warning: failed to write frontend design findings PRD: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+                if (continuationCount < frontendRecoveryQuota) {
+                    recoveryTrigger = {
+                        requestId: state.runId,
+                        // The rejected design is a plan input defect. Reset from the
+                        // planner so the next child can incorporate the committed
+                        // findings before design review runs again.
+                        failureSource: "frontend-plan-pi",
+                        failureOwner: classifyReviewIssueCategoryFailureOwner(designRequestFact.issueCategory),
+                        protocolFailureReason: `frontend design review request_design_changes (issueCategory=${designRequestFact.issueCategory})`,
+                        recoveryMode: "new-dag",
+                    };
+                }
+            }
+            if (planContractInvalid) {
                 const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
-                if (continuationCount >= 1) {
-                    // Continuation quota exhausted: a second retryable-invalid candidate
+                if (continuationCount >= frontendRecoveryQuota) {
+                    // Continuation quota exhausted: a second contract-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;
+                // Root continuation still available: emit a recovery trigger for the
+                // M6 operation controller. The parent no longer writes
+                // frontendRecoveryState or stays in active/ for a child CAS.
+                recoveryTrigger = {
+                    requestId: state.runId,
+                    failureSource: admission.result.failureSource ?? "frontend-plan-pi",
+                    failureOwner: "plan",
+                    protocolFailureReason: "frontend candidate contract invalid",
+                    recoveryMode: "new-dag",
+                };
             }
         }
     }
-    // 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 && !skipFrontendRecovery) {
+    // Phase 5: writer transient partial write → rollback + recovery trigger.
+    // 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 && !recoveryTrigger && !skipFrontendRecovery) {
         const writerNodeId = FRONTEND_WRITER_NODE_IDS.find((id) => {
             const node = state.nodes[id];
             return (node &&
@@ -1002,15 +1263,20 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
         });
         if (writerNodeId) {
             const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
-            if (continuationCount < 1) {
+            if (continuationCount < frontendRecoveryQuota) {
                 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;
+                    recoveryTrigger = {
+                        requestId: state.runId,
+                        failureSource: "frontend-implement-pi",
+                        failureOwner: "implementation",
+                        protocolFailureReason: "frontend writer transient partial write",
+                        recoveryMode: "continuation",
+                    };
                 }
                 else {
                     state.frontendRecoveryResult = buildWriterPartialWriteBlockedResult(state, writerNodeId, rollback.reason);
@@ -1020,6 +1286,64 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
             }
         }
     }
+    // Phase 6: verification failure → automatic recovery (re-implement +
+    // re-verify). The verify shell is terminal by design so the failed run's
+    // evidence stays clean; the M6 recovery operation re-runs implement and
+    // verify in a fresh continuation, guarded by the same continuation quota,
+    // budget fold and failure fingerprint as the other recovery paths.
+    if (hasFrontendWriter && !recoveryTrigger && !skipFrontendRecovery) {
+        const verifyFailed = state.nodes["frontend-verify-shell"]?.status === "ERROR";
+        if (verifyFailed) {
+            const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+            if (continuationCount < frontendRecoveryQuota) {
+                recoveryTrigger = {
+                    requestId: state.runId,
+                    failureSource: "frontend-verify-shell",
+                    failureOwner: "implementation",
+                    protocolFailureReason: "frontend verification failure",
+                    recoveryMode: "continuation",
+                };
+            }
+        }
+    }
+    // Phase 7: frontend review "request changes" → not passed. When the review
+    // node FINISHED but committed `request_review_changes` (typed terminal
+    // verdict), the implementation was reviewed and rejected. The run must not
+    // surface as finished: terminal aggregation below stays partial_failed, a
+    // terminal reason is recorded, the committed findings are rendered into a
+    // downstream-task PRD draft (run-owned), and a recovery trigger carries the
+    // issueCategory-derived owner so a later DAG round consumes the findings
+    // instead of repeating the previous flow.
+    const reviewRequestFact = await readCommittedReviewRequestFact({
+        runDir,
+    });
+    if (reviewRequestFact) {
+        state.terminalReason = "review-request-changes";
+        try {
+            await writeFrontendReviewFindingsPrd({
+                runDir,
+                parentRunId: state.runId,
+                fact: reviewRequestFact,
+            });
+        }
+        catch (error) {
+            // The PRD draft is additive; a write failure must not mask the
+            // not-passed verdict. The terminal aggregation below still applies.
+            console.warn(`[run-dag] warning: failed to write frontend review findings PRD: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!recoveryTrigger && !skipFrontendRecovery) {
+            const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+            if (continuationCount < frontendRecoveryQuota) {
+                recoveryTrigger = {
+                    requestId: state.runId,
+                    failureSource: "frontend-review-pi",
+                    failureOwner: classifyReviewIssueCategoryFailureOwner(reviewRequestFact.issueCategory),
+                    protocolFailureReason: `frontend review request_review_changes (issueCategory=${reviewRequestFact.issueCategory})`,
+                    recoveryMode: "new-dag",
+                };
+            }
+        }
+    }
     const finishedCount = Object.values(state.nodes).filter((n) => n.status === "FINISHED").length;
     const { supersededIds, supersededFailures } = collectSupersededIntermediateFailures(state);
     if (state.convergence && supersededFailures.length > 0) {
@@ -1035,7 +1359,13 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
     if (effectiveErrorCount === 0 &&
         successTerminal &&
         finishedCount + conditionSkippedCount + supersededErrorCount === taskCount) {
-        state.status = "finished";
+        // Phase 7 guard: a committed `request_review_changes` means the review
+        // rejected the implementation; the run must never surface as finished
+        // even though every node technically FINISHED.
+        state.status =
+            state.terminalReason === "review-request-changes"
+                ? "partial_failed"
+                : "finished";
     }
     else if (finishedCount > 0) {
         state.status = "partial_failed";
@@ -1043,19 +1373,145 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
     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");
+    return recoveryTrigger
+        ? { recoveryPending: true, recovery: recoveryTrigger }
+        : { recoveryPending: false };
+}
+/**
+ * Construct (or reuse) the recovery operation for a failed frontend run.
+ *
+ * A parent-run atomic lease is acquired before `OperationStore.create`, then
+ * its operation id is persisted into that lease before the controller may run.
+ * `clientRequestId` remains a useful store-level replay key, but is not a
+ * cross-process recovery admission boundary. The reset partition is frozen via
+ * `computeFrontendRecoveryPlanForSource` and serialized under the run dir's
+ * bounded `.runtime/` namespace for audit. The operation invokes
+ * `dag rerun-task`, which regenerates a valid child DagSpec and carries typed
+ * parent feedback through the managed rerun path. `planHash` is the second
+ * idempotency dimension of `actionParams`.
+ */
+async function createRecoveryOperation(input) {
+    const { cwd, runDir, spec, state, trigger } = input;
+    const recoveryLease = await acquireDagRecoveryLease({
+        cwd,
+        parentRunId: state.runId,
+        requestId: trigger.requestId,
+        kind: "auto-frontend-recovery",
+    });
+    let effectiveLease = recoveryLease;
+    let observeOnly = false;
+    if (recoveryLease.kind === "held") {
+        if (recoveryLease.lease.kind !== "auto-frontend-recovery" ||
+            recoveryLease.lease.requestId !== trigger.requestId) {
+            return { kind: "lease-held", lease: recoveryLease.lease };
+        }
+        const claimed = await claimDagRecoveryLease({
+            leasePath: recoveryLease.leasePath,
+            lease: recoveryLease.lease,
+        });
+        effectiveLease = claimed;
+        if (claimed.kind === "held") {
+            if (!claimed.lease.executionRef) {
+                return { kind: "lease-held", lease: claimed.lease };
+            }
+            observeOnly = true;
+        }
+    }
+    const { computeFrontendRecoveryPlanForSource } = await import("./frontend-recovery-plan.js");
+    const plan = computeFrontendRecoveryPlanForSource({
+        spec,
+        parentRunId: state.runId,
+        requestId: trigger.requestId,
+        failureSource: trigger.failureSource,
+    });
+    const planHash = createHash("sha256")
+        .update(JSON.stringify(plan))
+        .digest("hex");
+    const continuationPath = path.join(runDir, ".runtime", "frontend-recovery", `${trigger.requestId}.json`);
+    await writeJsonAtomic(continuationPath, {
+        schemaVersion: 1,
+        parentRunId: state.runId,
+        requestId: trigger.requestId,
+        failureSource: trigger.failureSource,
+        recoveryMode: trigger.recoveryMode,
+        planHash,
+        plan,
+    });
+    const operationInput = {
+        clientRequestId: `dag-recovery-${state.runId}`,
+        action: "dagRunTask",
+        actionParams: {
+            parentRunId: state.runId,
+            requestId: trigger.requestId,
+            failureSource: trigger.failureSource,
+            failureOwner: trigger.failureOwner,
+            protocolFailureReason: trigger.protocolFailureReason,
+            recoveryMode: trigger.recoveryMode,
+            planHash,
+        },
+        cliArgs: [
+            "dag",
+            "rerun-task",
+            "--run-id",
+            state.runId,
+            "--reason",
+            trigger.protocolFailureReason ?? "frontend automatic recovery",
+            "--request-id",
+            trigger.requestId,
+            "--frontend-recovery",
+            "--json",
+        ],
+    };
+    let created;
+    if (effectiveLease.lease.executionRef) {
+        // Replay the exact operation bound by the durable lease. A missing record
+        // cannot be replaced with a new operation id without violating the fence.
+        const existing = await input.deps.store.get(effectiveLease.lease.executionRef);
+        if (!existing) {
+            throw new Error(`frontend recovery lease operation not found: ${effectiveLease.lease.executionRef}`);
         }
-        else if (!state.frontendRecoveryResult) {
-            settleFrontendRecovery(state, "auto-recovery-blocked");
+        if (existing.clientRequestId !== operationInput.clientRequestId ||
+            existing.action !== operationInput.action ||
+            existing.payloadHash !==
+                computeActionPayloadHash(operationInput.action, operationInput.actionParams)) {
+            throw new Error("frontend recovery lease execution identity drift: referenced operation payload does not match the recovery request");
         }
+        created = { kind: "idempotent", operation: existing };
+    }
+    else {
+        created = await input.deps.store.create(operationInput);
+    }
+    if (created.kind !== "conflict" && !observeOnly) {
+        // The durable lease must name the operation before controller execution.
+        // This also repairs a lease left behind by a crash before the original bind.
+        await bindDagRecoveryLeaseExecution({
+            leasePath: effectiveLease.leasePath,
+            lease: effectiveLease.lease,
+            executionRef: created.operation.operationId,
+        });
+        // Repair CLI args on both fresh and replayed operations. This closes the
+        // crash window after operation creation but before args were persisted.
+        await input.deps.store.update(created.operation.operationId, {
+            cliArgs: [
+                "dag",
+                "rerun-task",
+                "--run-id",
+                state.runId,
+                "--reason",
+                trigger.protocolFailureReason ?? "frontend automatic recovery",
+                "--request-id",
+                trigger.requestId,
+                "--frontend-recovery",
+                "--recovery-operation-id",
+                created.operation.operationId,
+                "--json",
+            ],
+        });
+    }
+    if (created.kind !== "conflict" && observeOnly) {
+        return { kind: "observed", operation: created.operation };
     }
-    return { recoveryPending };
+    return created;
 }
 function concurrentSiblingWriteSetsForNode(rankWriterNodeIds, nodeId, tasksById) {
     if (rankWriterNodeIds.length <= 1)