@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.10

package/dist/executors/dag-pi-executor.js

@@ -1,21 +1,32 @@
 import { classifyFrontendPlanRecovery } from "../workflows/dag/frontend-plan-recovery-policy.js";
-import { collectFrontendExecutionGroups, frontendExecutionSchema } from "../workflows/dag/frontend-execution-groups.js";
+import { collectFrontendExecutionGroups } from "../workflows/dag/frontend-execution-groups.js";
 import { FRONTEND_SCOPE_TARGET_BYTES, packFrontendInputUnits, parseFrontendInputBlock, projectFrontendContractPrompt, projectFrontendInputScope } from "../workflows/dag/frontend-input-projection.js";
 import { createDurableFrontendTools } from "../workflows/dag/frontend-durable-tools.js";
 import { sha256OfCanonicalJson } from "../task/contract/hash.js";
 import { z } from "zod";
-import { createFrontendReviewScopeProtocol, loadFrontendReviewScopes } from "../workflows/dag/frontend-review-scopes.js";
-import { observeFrontendSession } from "../workflows/dag/frontend-session-budget.js";
+import { loadFrontendReviewScopes } from "../workflows/dag/frontend-review-scopes.js";
+import { observeFrontendFinalization, observeFrontendSession } from "../workflows/dag/frontend-session-budget.js";
 import path from "node:path";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
-import { writeJsonAtomic } from "../infrastructure/harness/atomic-write.js";
-import { mapContractBlockedOwner } from "../workflows/dag/frontend-human-decision.js";
-import { routeFrontendProviderCapability } from "../workflows/dag/frontend-provider-capability-matrix.js";
 import { executePiStep, resolvePiBackend, } from "./pi-executor.js";
 import { resolveDagPiExtensions, } from "./pi-extension-resolver.js";
 import { buildPiWriterToolPolicyContext, createPiReaderCustomTools, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
+import { resolveDagPiModelConfig } from "./dag-pi/model-config.js";
+import { isRecordObject } from "./dag-pi/guards.js";
+import { createFrontendReviewTerminalTools } from "./dag-pi/tools/review-terminal-tools.js";
+import { createFrontendDesignTerminalTools } from "./dag-pi/tools/design-terminal-tools.js";
+import { createFrontendScoutEvidenceTools } from "./dag-pi/tools/scout-evidence-tools.js";
+import { createFrontendPlanDecisionTools, translateDecisionPatchFindings } from "./dag-pi/tools/plan-decision-tools.js";
+import { createFrontendContractTools } from "./dag-pi/tools/contract-tools.js";
+import { loadContractRequirementInheritance } from "./dag-pi/plan/ledger-contract.js";
+import { createFrontendPlanProgressGuard } from "../workflows/dag/frontend-plan-progress.js";
+import { buildPlanSchemas } from "./dag-pi/plan/schema.js";
+import { buildPlanRecordTools } from "./dag-pi/plan/record-tools.js";
+import { buildPlanFinalizeTools } from "./dag-pi/plan/finalize-tools.js";
+import { createPlanFactAdopter } from "./dag-pi/plan/fact-adoption.js";
+import { collectFrontendPlanMissingFacts, collectFrontendPlanPhaseMissingFacts, committedFactFromPlanRecord, planFactStringList, planFactScopeIntersects } from "./dag-pi/plan/facts.js";
 import { createPiReadBudgetCustomTools, } from "./pi-read-budget-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
@@ -24,9 +35,8 @@ import { splitDocumentIntoFragments, sha256Text, } from "../task/source-prepare/
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
-import { pathMatchesPattern } from "../shared/git-progress.js";
 import { readTypedEventStoreFromJsonl, typedEventPayloadSha256, } from "../workflows/dag/frontend-typed-event-store.js";
-import { collectCanonicalStateFlowNames, frontendEvidenceExpectationSchema, resolveFrontendContractRequirements, validateFrontendRequiredDeliverables, } from "../workflows/dag/frontend-contract-facts.js";
+import { resolveFrontendContractRequirements, } from "../workflows/dag/frontend-contract-facts.js";
 import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, OUTPUT_LIMIT_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestCollectionRepairOutcomeRecoveryCandidate, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
@@ -348,15 +358,7 @@ export const DAG_PI_WRITE_TOOLS = [
     "ls",
     "bash",
 ];
-export const DEFAULT_DAG_PI_PROVIDER = "wizard-local";
 const WRITER_OUTCOME_PROTOCOL_LINE = "IMPLEMENTATION_OUTCOME:";
-export const DAG_PI_MODEL_PROVIDERS = {
-    "gpt-5.3-codex-spark": "wizard-local",
-    "gpt-5.5": "wizard-local",
-    "glm-5.2": "wizard-local",
-    "deepseek-v4-flash": "deepseek",
-    "deepseek-v4-pro": "deepseek",
-};
 const SAFE_PI_STEPS = new Set([
     "analyze",
     "plan",
@@ -829,360 +831,6 @@ export function scanDesignTerminalKindsFromSessionEvents(content) {
     }
     return kinds;
 }
-/**
- * M5: build the two committed typed review terminal tools (approve_review /
- * request_review_changes). Each tool validates its parameters with the review
- * fact zod schemas, stages + adopts a terminal fact into the typed event
- * store, and returns a structured receipt. Terminal conflicts (a second
- * terminal commit) are caught inside execute and returned as an error receipt
- * rather than crashing the node.
- */
-export async function createFrontendReviewTerminalTools(input) {
-    const [{ Type }, { defineTool }] = await Promise.all([
-        import("typebox"),
-        import("@earendil-works/pi-coding-agent"),
-    ]);
-    const { approveReviewFactSchema, readCommittedEvents, requestReviewChangesFactSchema, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
-    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
-    let store = input.store;
-    const attemptId = input.attemptId;
-    const findingSchema = Type.Object({
-        severity: Type.Enum({ Critical: "Critical", Important: "Important", Minor: "Minor", Info: "Info" }),
-        file: Type.Optional(Type.String({ minLength: 1 })),
-        line: Type.Optional(Type.Integer({ minimum: 1 })),
-        issue: Type.String({ minLength: 1 }),
-        requiredChange: Type.Optional(Type.String({ minLength: 1 })),
-    }, { additionalProperties: false });
-    const scopeProtocol = createFrontendReviewScopeProtocol({ phase: "review", inventory: input.inventory, getStore: () => store, attemptId });
-    const savedFindings = () => [...new Map(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "review-finding").map(r => [r.fact.id, r.fact.finding])).values()];
-    const allFindings = (direct) => [...new Map([...savedFindings(), ...(Array.isArray(direct) ? direct : [])].map(finding => [JSON.stringify(finding), finding])).values()];
-    const recordFindingTool = defineTool({
-        name: "record_review_finding", label: "record_review_finding",
-        description: "Save one finding with a stable id. Submit findings incrementally, then finalize without repeating the findings array. Saved blocking findings cannot be omitted from approval; correct a finding explicitly with replace:true.",
-        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema }, { additionalProperties: false }),
-        async execute(_callId, params) {
-            const fact = { kind: "review-finding", id: params.id, finding: params.finding };
-            const requestId = `${attemptId}:finding:${randomUUID()}`;
-            const staged = stageTypedEventFact({ store, requestId, attemptId, fact });
-            const adopted = await adoptTypedEventFact({ store, requestId, attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
-            const details = { ok: true, eventId: adopted.eventId, revision: adopted.revision };
-            return { content: [{ type: "text", text: JSON.stringify(details) }], details };
-        },
-    });
-    const approveParameters = Type.Object({
-        findings: Type.Optional(Type.Array(findingSchema, {
-            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
-        })),
-    }, { additionalProperties: false });
-    const requestParameters = Type.Object({
-        issueCategory: Type.Enum({
-            "implementation-mismatch": "implementation-mismatch",
-            "approved-design-defect": "approved-design-defect",
-            "target-surface-defect": "target-surface-defect",
-            "contract-requirement-gap": "contract-requirement-gap",
-            "unknown": "unknown",
-        }, { description: "Typed issue category (five-value enum)" }),
-        evidenceRefs: Type.Array(Type.String({ minLength: 1 }), {
-            description: "Evidence refs (paths or artifact ids); at least one", minItems: 1,
-        }),
-        findings: Type.Optional(Type.Array(findingSchema, {
-            description: "At least one finding", minItems: 1,
-        })),
-    }, { additionalProperties: false });
-    async function adoptReviewFact(kind, fact) {
-        const requestId = randomUUID();
-        try {
-            scopeProtocol.assertComplete();
-            const parsed = kind === "approve_review"
-                ? approveReviewFactSchema.parse(fact)
-                : requestReviewChangesFactSchema.parse(fact);
-            const staged = stageTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: parsed,
-            });
-            const adopted = await adoptTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: parsed,
-                eventId: staged.eventId,
-                expectedRevision: store.revision,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            ok: true,
-                            kind,
-                            eventId: adopted.eventId,
-                            revision: adopted.revision,
-                        }),
-                    },
-                ],
-                details: {
-                    ok: true,
-                    kind,
-                    eventId: adopted.eventId,
-                    revision: adopted.revision,
-                },
-            };
-        }
-        catch (error) {
-            const code = error?.code;
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ ok: false, kind, code, error: message }),
-                    },
-                ],
-                details: { ok: false, kind, code, error: message },
-            };
-        }
-    }
-    const approveReviewTool = defineTool({
-        name: "approve_review",
-        label: "approve_review",
-        description: "Commit the authoritative approve_review terminal fact. Use only when the implementation passes review with no Critical/Important findings.",
-        promptSnippet: "Commit the authoritative approve_review terminal verdict (no Critical/Important findings).",
-        parameters: approveParameters,
-        async execute(_toolCallId, params) {
-            return adoptReviewFact("approve_review", {
-                kind: "approve_review",
-                verdict: "approve_review",
-                findings: allFindings(params?.findings),
-            });
-        },
-    });
-    const requestReviewChangesTool = defineTool({
-        name: "request_review_changes",
-        label: "request_review_changes",
-        description: "Commit the authoritative request_review_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
-        promptSnippet: "Commit the authoritative request_review_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
-        parameters: requestParameters,
-        async execute(_toolCallId, params) {
-            return adoptReviewFact("request_review_changes", {
-                kind: "request_review_changes",
-                verdict: "request_review_changes",
-                issueCategory: params?.issueCategory,
-                evidenceRefs: params?.evidenceRefs,
-                findings: allFindings(params?.findings),
-            });
-        },
-    });
-    const durable = await createDurableFrontendTools({
-        file: path.join(input.runDir, input.nodeId, "review-typed-facts.jsonl"), attemptId, store: input.store,
-        binding: { inputDigest: input.inputDigest, scopeDigest: input.inventory?.digest }, setWorkingStore: next => { store = next; }, tools: [...scopeProtocol.customTools, recordFindingTool, approveReviewTool, requestReviewChangesTool], validateRestored: async () => { await input.inventory?.validate(); },
-    });
-    return { ...durable, scopeProtocol };
-}
-/**
- * M8: build the two committed typed design terminal tools (approve_design /
- * request_design_changes). Each tool validates its parameters with the design
- * fact zod schemas, stages + adopts a terminal fact into the typed event
- * store, and returns a structured receipt. Terminal conflicts are caught
- * inside execute and returned as an error receipt rather than crashing the
- * node.
- */
-export async function createFrontendDesignTerminalTools(input) {
-    const [{ Type }, { defineTool }] = await Promise.all([
-        import("typebox"),
-        import("@earendil-works/pi-coding-agent"),
-    ]);
-    const { approveDesignFactSchema, readCommittedEvents, requestDesignChangesFactSchema, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
-    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
-    let store = input.store;
-    const attemptId = input.attemptId;
-    const findingSchema = Type.Object({
-        severity: Type.Enum({ Critical: "Critical", Important: "Important", Minor: "Minor", Info: "Info" }),
-        file: Type.Optional(Type.String({ minLength: 1 })),
-        line: Type.Optional(Type.Integer({ minimum: 1 })),
-        issue: Type.String({ minLength: 1 }),
-        requiredChange: Type.Optional(Type.String({ minLength: 1 })),
-    }, { additionalProperties: false });
-    const scopeProtocol = createFrontendReviewScopeProtocol({ phase: "design", inventory: input.inventory, getStore: () => store, attemptId });
-    const savedFindings = () => [...new Map(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "design-finding").map(r => [r.fact.id, r.fact.finding])).values()];
-    const allFindings = (direct) => [...new Map([...savedFindings(), ...(Array.isArray(direct) ? direct : [])].map(finding => [JSON.stringify(finding), finding])).values()];
-    const recordFindingTool = defineTool({
-        name: "record_design_finding", label: "record_design_finding",
-        description: "Save one finding with a stable id. Submit findings incrementally, then finalize without repeating the findings array. Saved blocking findings cannot be omitted from approval; correct a finding explicitly with replace:true.",
-        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema }, { additionalProperties: false }),
-        async execute(_callId, params) {
-            const fact = { kind: "design-finding", id: params.id, finding: params.finding };
-            const requestId = `${attemptId}:finding:${randomUUID()}`;
-            const staged = stageTypedEventFact({ store, requestId, attemptId, fact });
-            const adopted = await adoptTypedEventFact({ store, requestId, attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
-            const details = { ok: true, eventId: adopted.eventId, revision: adopted.revision };
-            return { content: [{ type: "text", text: JSON.stringify(details) }], details };
-        },
-    });
-    const approveParameters = Type.Object({
-        findings: Type.Optional(Type.Array(findingSchema, {
-            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
-        })),
-    }, { additionalProperties: false });
-    const requestParameters = Type.Object({
-        issueCategory: Type.Enum({
-            "implementation-mismatch": "implementation-mismatch",
-            "approved-design-defect": "approved-design-defect",
-            "target-surface-defect": "target-surface-defect",
-            "contract-requirement-gap": "contract-requirement-gap",
-            "unknown": "unknown",
-        }, { description: "Typed issue category (five-value enum)" }),
-        evidenceRefs: Type.Array(Type.String({ minLength: 1 }), {
-            description: "Evidence refs (paths or artifact ids); at least one", minItems: 1,
-        }),
-        findings: Type.Optional(Type.Array(findingSchema, {
-            description: "At least one finding", minItems: 1,
-        })),
-    }, { additionalProperties: false });
-    async function adoptDesignFact(kind, fact) {
-        const requestId = randomUUID();
-        try {
-            scopeProtocol.assertComplete();
-            const parsed = kind === "approve_design"
-                ? approveDesignFactSchema.parse(fact)
-                : requestDesignChangesFactSchema.parse(fact);
-            const staged = stageTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: parsed,
-            });
-            const adopted = await adoptTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: parsed,
-                eventId: staged.eventId,
-                expectedRevision: store.revision,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            ok: true,
-                            kind,
-                            eventId: adopted.eventId,
-                            revision: adopted.revision,
-                        }),
-                    },
-                ],
-                details: {
-                    ok: true,
-                    kind,
-                    eventId: adopted.eventId,
-                    revision: adopted.revision,
-                },
-            };
-        }
-        catch (error) {
-            const code = error?.code;
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ ok: false, kind, code, error: message }),
-                    },
-                ],
-                details: { ok: false, kind, code, error: message },
-            };
-        }
-    }
-    const approveDesignTool = defineTool({
-        name: "approve_design",
-        label: "approve_design",
-        description: "Commit the authoritative approve_design terminal fact. Use only when the plan passes design review with no Critical/Important findings.",
-        promptSnippet: "Commit the authoritative approve_design terminal verdict (no Critical/Important findings).",
-        parameters: approveParameters,
-        async execute(_toolCallId, params) {
-            return adoptDesignFact("approve_design", {
-                kind: "approve_design",
-                verdict: "approve_design",
-                findings: allFindings(params?.findings),
-            });
-        },
-    });
-    const requestDesignChangesTool = defineTool({
-        name: "request_design_changes",
-        label: "request_design_changes",
-        description: "Commit the authoritative request_design_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
-        promptSnippet: "Commit the authoritative request_design_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
-        parameters: requestParameters,
-        async execute(_toolCallId, params) {
-            return adoptDesignFact("request_design_changes", {
-                kind: "request_design_changes",
-                verdict: "request_design_changes",
-                issueCategory: params?.issueCategory,
-                evidenceRefs: params?.evidenceRefs,
-                findings: allFindings(params?.findings),
-            });
-        },
-    });
-    const durable = await createDurableFrontendTools({
-        file: path.join(input.runDir, input.nodeId, "design-typed-facts.jsonl"), attemptId, store: input.store,
-        binding: { inputDigest: input.inputDigest, scopeDigest: input.inventory?.digest }, setWorkingStore: next => { store = next; }, tools: [...scopeProtocol.customTools, recordFindingTool, approveDesignTool, requestDesignChangesTool], validateRestored: async () => { await input.inventory?.validate(); },
-    });
-    return { ...durable, scopeProtocol };
-}
-/**
- * Source fidelity ledger (AC-005/AC-006): load the contract node's committed
- * requirement facts and build a requirement-id → provenance map. The contract
- * node declared sourceFragmentIds/sourceRefs from the ledger's
- * requirement→fragment mapping; the plan inherits them by id so the compiled
- * canonical contract carries authoritative provenance without the plan
- * re-deriving (or fabricating) it. Best-effort: missing/unreadable contract
- * ledger yields an empty map and the plan compiles as before (the design
- * policy shell will then fail closed on missing provenance).
- */
-async function loadContractRequirementInheritance(runDir) {
-    const { readTypedEventStoreFromJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
-    let records;
-    try {
-        records = await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
-    }
-    catch {
-        return new Map();
-    }
-    const byId = new Map();
-    for (const record of records) {
-        const fact = record.fact;
-        if (!fact || typeof fact !== "object")
-            continue;
-        const recordFact = fact;
-        if (recordFact.origin !== "contract" ||
-            recordFact.kind !== "requirement") {
-            continue;
-        }
-        // Contract requirement facts carry id/sourceFragmentIds/sourceRefs on
-        // the fact itself (origin=contract, kind=requirement, id, text, ...),
-        // not inside an `entry` wrapper.
-        const id = typeof recordFact.id === "string" ? recordFact.id : "";
-        if (!id)
-            continue;
-        const sourceFragmentIds = Array.isArray(recordFact.sourceFragmentIds)
-            ? recordFact.sourceFragmentIds.filter((value) => typeof value === "string")
-            : undefined;
-        const sourceRefs = Array.isArray(recordFact.sourceRefs)
-            ? recordFact.sourceRefs.filter((value) => typeof value === "string")
-            : undefined;
-        if (sourceFragmentIds || sourceRefs) {
-            byId.set(id, {
-                ...(typeof recordFact.text === "string" ? { text: recordFact.text } : {}),
-                ...(recordFact.execution !== undefined ? { execution: frontendExecutionSchema.parse(recordFact.execution) } : {}),
-                ...(sourceFragmentIds ? { sourceFragmentIds } : {}),
-                ...(sourceRefs ? { sourceRefs } : {}),
-            });
-        }
-    }
-    return byId;
-}
 export async function resolveFrontendDecisionAuthority(input) {
     const inheritance = await loadContractRequirementInheritance(input.runDir);
     if (inheritance.size === 0)
@@ -1447,1353 +1095,125 @@ export async function createFrontendPlanLedgerTools(input) {
     const { loadTypedEventStore, readCommittedEvents, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
     const { adoptStagedFact, adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
     const { assemblePlanPatchFromCommittedFacts } = await import("../workflows/dag/frontend-committed-facts.js");
-    let store = input.store;
-    const attemptId = input.attemptId;
-    let activeRequirementScope = [];
-    const scopedRequirementIds = () => [...activeRequirementScope];
+    const session = {
+        store: input.store,
+        attemptId: input.attemptId,
+        activeRequirementScope: [],
+    };
+    const scopedRequirementIds = () => [...session.activeRequirementScope];
     const contractInheritance = await loadContractRequirementInheritance(input.runDir);
     const executionGroups = collectFrontendExecutionGroups([...contractInheritance].map(([id, r]) => ({ id, ...r })));
-    const stringArray = Type.Array(Type.String({}));
-    const optionalString = Type.Optional(Type.String({}));
-    const optionalStringArray = Type.Optional(stringArray);
-    const requirementSchema = Type.Object({
-        id: Type.String({}),
-        expectedOutcome: Type.Optional(Type.String({
-            description: "Optional. When omitted, the runtime derives it from the contract requirement. Prefer omitting it to keep this tool call small.",
-        })),
-        implementationTargets: stringArray,
-        verificationTargetIds: Type.Optional(stringArray),
-        evidenceGap: Type.Optional(Type.Object({
-            requirementId: optionalString,
-            description: Type.String({}),
-            blocking: Type.Boolean(),
-        }, { additionalProperties: false })),
-    }, { additionalProperties: false });
-    const uiStateSchema = Type.Object({
-        name: Type.String({}),
-        applicable: Type.Boolean(),
-        expectedBehavior: optionalString,
-        implementationTargets: optionalStringArray,
-        verificationTargetIds: optionalStringArray,
-        notApplicableReason: optionalString,
-        reason: Type.Optional(Type.String({})),
-    }, { additionalProperties: false });
-    const interactionSchema = Type.Object({
-        name: optionalString,
-        id: Type.Optional(Type.String({})),
-        trigger: Type.String({}),
-        expectedBehavior: Type.String({}),
-        implementationTargets: stringArray,
-        verificationTargetIds: stringArray,
-    }, { additionalProperties: false });
-    const mockEndpointSchema = Type.Object({
-        method: Type.Enum({ GET: "GET", POST: "POST", PUT: "PUT", PATCH: "PATCH", DELETE: "DELETE", HEAD: "HEAD", OPTIONS: "OPTIONS" }),
-        path: Type.String({}),
-        fixture: optionalString,
-        consumer: optionalString,
-    }, { additionalProperties: false });
-    const mockApiSchema = Type.Object({
-        strategy: Type.Union([
-            Type.Literal("native"),
-            Type.Literal("browser-intercept"),
-            Type.Literal("request-adapter"),
-            Type.Literal("not-needed"),
-        ], {
-            description: "native | browser-intercept | request-adapter | not-needed",
-        }),
-        activation: Type.String({}),
-        endpoints: Type.Array(mockEndpointSchema),
-    }, { additionalProperties: false });
-    const designEvidenceSchema = Type.Object({
-        source: Type.String({}),
-        paths: stringArray,
-        conflicts: stringArray,
-    }, { additionalProperties: false });
-    // Verification mode is runtime-owned (contract v2): the plan submits a
-    // commandId referencing the frozen command directory, never a type. A
-    // soft Type.String would let the model commit values that only fail at
-    // compile time — keep the reference a required string and validate it
-    // against the directory at the tool boundary below.
-    const verificationTargetScopeSchema = Type.Union([
-        Type.Literal("unit"),
-        Type.Literal("component"),
-        Type.Literal("integration"),
-    ]);
-    const verificationTargetSchema = Type.Object({
-        id: Type.String({}),
-        commandId: Type.String({
-            description: "Frozen command directory key (e.g. verify-npm-run-build); the runtime resolves mode and label from it.",
-        }),
-        file: Type.String({}),
-        requirementIds: stringArray,
-        scope: Type.Optional(verificationTargetScopeSchema),
-        uiStates: Type.Optional(Type.Array(Type.String({}), {
-            description: "Optional only at this tool boundary. An omitted value is deterministically recorded as []. Pass an explicit array for new calls.",
-        })),
-    }, { additionalProperties: false });
-    const evidenceGapSchema = Type.Object({
-        requirementId: optionalString,
-        description: Type.String({}),
-        blocking: Type.Boolean(),
-    }, { additionalProperties: false });
-    const uiComponentChoiceSchema = Type.Object({
-        purpose: Type.String({}),
-        component: Type.String({}),
-        decision: Type.Union([
-            Type.Literal("specified"),
-            Type.Literal("reuse-existing"),
-            Type.Literal("new"),
-        ], {
-            description: "specified | reuse-existing | new",
-        }),
-        specReference: Type.Optional(Type.Object({
-            path: Type.String({}),
-            section: Type.String({}),
-            line: Type.Optional(Type.Integer({ minimum: 1 })),
-        }, { additionalProperties: false })),
-        rationale: Type.Optional(Type.String({ minLength: 1 })),
-        covers: Type.Optional(Type.Array(Type.String({}), {
-            description: "UI state and/or interaction names this single component choice covers (one choice may cover many ids).",
-        })),
-        evidencePath: Type.Optional(Type.String({
-            description: "REQUIRED for decision=reuse-existing: repo-relative path whose existing file is the reuse evidence. Greenfield paths must use decision=new.",
-        })),
-    }, { additionalProperties: false });
-    const stringList = (value) => Array.isArray(value)
-        ? value.filter((item) => typeof item === "string")
-        : [];
-    const nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0
-        ? value.trim()
-        : undefined;
-    const planToolReceipt = (details) => ({
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify(details),
-            },
-        ],
-        details,
+    const planSchemas = buildPlanSchemas(Type);
+    const adoptPlanFact = createPlanFactAdopter({
+        session,
+        stageTypedEventFact,
+        adoptTypedEventFact,
     });
-    async function adoptPlanFact(kind, requestId, fact) {
-        // A+B (AC-005): a provider-capability fact kind reaching the plan ledger
-        // is out of route — it belongs to the provider capability channel,
-        // not the plan decision ledger. Route it through the frozen seven-kind
-        // matrix and fail closed to `unsupported-provider-capability` instead of
-        // silently widening the plan catalog.
-        const capabilityRoute = routeFrontendProviderCapability({ factKind: kind });
-        if (capabilityRoute.ok) {
-            return {
-                ok: false,
-                kind,
-                code: "unsupported-provider-capability",
-                error: `plan ledger cannot adopt provider capability fact kind: ${kind}`,
-            };
-        }
-        try {
-            const staged = stageTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-            });
-            const committed = await adoptTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-                eventId: staged.eventId,
-                expectedRevision: store.revision,
-            });
-            return {
-                ok: true,
-                kind,
-                eventId: committed.eventId,
-                revision: committed.revision,
-                error: "",
-            };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                kind,
-                code: error?.code,
-                error: error instanceof Error ? error.message : String(error),
-            };
-        }
-    }
-    const recordRouteSelectionTool = defineTool({
-        name: "record_route_selection",
-        label: "record_route_selection",
-        description: "Record the route selection needed by this plan. Repository target surface and file ownership belong to Scout/runtime. Example: {\"routes\": [\"/<route>\"]}",
-        promptSnippet: "Record the selected routes.",
-        parameters: Type.Object({ routes: stringArray }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const routes = stringList(params?.routes);
-            const result = await adoptPlanFact("target-surface", `${attemptId}:record_route_selection:${randomUUID()}`, { kind: "target-surface", origin: "plan", routes });
-            return planToolReceipt(result);
-        },
+    const { recordRouteSelectionTool, recordComponentChoiceTool, recordStateRegistryTool, recordStateFlowTool, recordDataFlowTool, recordMockApiTool, recordMockEndpointTool, recordDesignDeviationTool, recordDependencyTool, recordPlanRequirementTool, recordPlanGroupCoverageTool, recordPlanVerificationTargetTool, recordPlanEvidenceGapTool, } = buildPlanRecordTools({
+        Type, defineTool, session, schemas: planSchemas, input, readCommittedEvents,
+        scopedRequirementIds, executionGroups, adoptPlanFact,
     });
-    const recordComponentChoiceTool = defineTool({
-        name: "record_component_choice",
-        label: "record_component_choice",
-        description: "Record ONE component choice (origin=plan component-choice fact). One choice may cover MULTIPLE UI states/interactions via covers: [\"<state-or-interaction name>\", ...]; do not emit one row per interaction. For decision=new, pass sourceRequirementIds containing the frozen requirement ID(s) that mandate the component and sourceFragmentId selecting one frozen citation listed in the plan checklist; the runtime validates the relation and derives the exact PRD specReference. Do not read the PRD or invent a path/line. decision=reuse-existing is only for components that already exist in the repo and REQUIRES evidencePath: a repo-relative path to the existing file that proves the reuse — the runtime verifies the file exists (fresh evidence); a path with no existing file is greenfield and must use decision=new instead. Call up to 5 component choices per assistant message; never more than 5 per message. Optionally include stylingStrategy (set it once, on the first call). Example: {\"choice\": {\"purpose\": \"<interaction or UI state name>\", \"component\": \"<component name>\", \"decision\": \"new\", \"covers\": [\"<other interaction names this component also serves>\"]}, \"sourceRequirementIds\": [\"<AC-XXX mandating this component>\"], \"sourceFragmentId\": \"<REQ-SRC-...>\"} or {\"choice\": {\"purpose\": \"FocusQueuePanel\", \"component\": \"FocusQueuePanel\", \"decision\": \"reuse-existing\", \"evidencePath\": \"src/journal.ts\"}}",
-        promptSnippet: "Record 1-5 component choices (up to 5 per message).",
-        parameters: Type.Object({
-            choice: uiComponentChoiceSchema,
-            sourceRequirementIds: Type.Optional(stringArray),
-            sourceFragmentId: optionalString,
-            stylingStrategy: optionalString,
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const rawChoice = params?.choice;
-            if (!isRecordObject(rawChoice)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "component-choice",
-                    error: "record_component_choice requires a non-empty choice object",
-                });
-            }
-            const sourceRequirementIds = stringList(params?.sourceRequirementIds);
-            const sourceFragmentId = nonEmptyString(params?.sourceFragmentId);
-            const choice = { ...rawChoice };
-            if (choice.decision === "new") {
-                if (sourceRequirementIds.length === 0) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "component-choice",
-                        error: "decision=new requires sourceRequirementIds so runtime can materialize the task-source specReference",
-                    });
-                }
-                if (!sourceFragmentId) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "component-choice",
-                        error: "decision=new requires sourceFragmentId selecting a frozen task-source citation",
-                    });
-                }
-                const citation = sourceRequirementIds
-                    .flatMap((id) => input.componentNewSourceReferences?.get(id) ?? [])
-                    .find((candidate) => candidate.fragmentId === sourceFragmentId);
-                if (!citation) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "component-choice",
-                        error: `decision=new sourceFragmentId ${sourceFragmentId} is not bound to sourceRequirementIds ${sourceRequirementIds.join(", ")}`,
-                    });
-                }
-                choice.specReference = {
-                    path: citation.path,
-                    section: citation.section,
-                    ...(citation.line !== undefined ? { line: citation.line } : {}),
-                };
-            }
-            if (choice.decision === "reuse-existing") {
-                // reuse-existing must cite a file that actually exists NOW (fresh
-                // existence evidence, same semantics as Scout pathEvidence.fresh).
-                // A path with no file on disk is greenfield: decision=new is the
-                // only honest choice (dogfood run dag-1788504923861-0f7b17a9
-                // claimed 18 reuse-existing conventions in a not-yet-written
-                // src/planner.ts and every gate let it through).
-                const evidencePath = typeof choice.evidencePath === "string"
-                    ? choice.evidencePath.trim()
-                    : "";
-                if (!evidencePath) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "component-choice",
-                        error: "decision=reuse-existing requires evidencePath naming the existing repo file that proves the reuse; if the file does not exist yet, use decision=new",
-                    });
-                }
-                if (input.workspaceRoot) {
-                    const absolute = path.resolve(input.workspaceRoot, evidencePath);
-                    const workspaceRoot = path.resolve(input.workspaceRoot);
-                    const contained = absolute === workspaceRoot ||
-                        absolute.startsWith(`${workspaceRoot}${path.sep}`);
-                    let exists = false;
-                    if (contained) {
-                        try {
-                            exists = (await stat(absolute)).isFile();
-                        }
-                        catch {
-                            exists = false;
-                        }
-                    }
-                    if (!exists) {
-                        return planToolReceipt({
-                            ok: false,
-                            kind: "component-choice",
-                            error: `decision=reuse-existing evidencePath "${evidencePath}" has no fresh existence evidence (file not found in the workspace); reuse requires an existing file — use decision=new for greenfield paths`,
-                        });
+    const { finalizePlanTool, adoptStagedFactTool, readPlanFactsTool, } = buildPlanFinalizeTools({
+        Type, defineTool, session, schemas: planSchemas, input, readCommittedEvents,
+        assemblePlanPatchFromCommittedFacts, contractInheritance, adoptStagedFact, adoptPlanFact,
+    });
+    const planControl = createFrontendPlanProgressGuard();
+    const durable = await createDurableFrontendTools({
+        planControl,
+        file: path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), attemptId: session.attemptId, store: input.store,
+        setWorkingStore: next => { session.store = next; },
+        binding: { sourceBinding: input.sourceBinding, skeleton: input.skeleton, requirementIds: input.requirementIds, writeSet: input.writeSetPatterns, declaredUiStateIds: input.declaredUiStateIds, citations: input.componentNewSourceReferences, contractInheritance },
+        tools: [
+            recordRouteSelectionTool,
+            recordComponentChoiceTool,
+            recordStateRegistryTool,
+            recordStateFlowTool,
+            recordDataFlowTool,
+            recordMockApiTool,
+            recordMockEndpointTool,
+            recordDesignDeviationTool,
+            recordDependencyTool,
+            recordPlanRequirementTool,
+            recordPlanGroupCoverageTool,
+            recordPlanVerificationTargetTool,
+            recordPlanEvidenceGapTool,
+            adoptStagedFactTool,
+            finalizePlanTool,
+        ],
+    });
+    const durableFinalizePlanTool = durable.customTools.find((tool) => typeof tool === "object" && tool !== null && tool.name === "finalize_plan");
+    if (!durableFinalizePlanTool)
+        throw new Error("frontend plan durable finalize tool unavailable");
+    return {
+        planControl,
+        customTools: [...durable.customTools, { ...readPlanFactsTool, execute: async (...args) => { await durable.flush(); return readPlanFactsTool.execute(...args); } }],
+        adoptCommittedFacts: async (records) => durable.commitExternal(async () => {
+            for (const record of records) {
+                if (record.phase !== "committed")
+                    continue;
+                const fact = record.fact;
+                if (!fact || typeof fact !== "object" || Array.isArray(fact))
+                    continue;
+                const kind = typeof fact.kind === "string"
+                    ? fact.kind
+                    : "plan-fact";
+                const entry = fact.entry;
+                const identity = (kind === "plan-requirement" || kind === "plan-verification-target") &&
+                    typeof entry?.id === "string"
+                    ? `${kind}:${entry.id}`
+                    : undefined;
+                const sourceShardPrefix = `${session.attemptId}:parallel-merge:${record.attemptId}:`;
+                const requestId = `${sourceShardPrefix}${record.eventId}`;
+                const committed = readCommittedEvents(session.store, session.attemptId);
+                const replay = committed.find((candidate) => candidate.requestId === requestId);
+                if (replay) {
+                    if (replay.payloadSha256 !== record.payloadSha256) {
+                        throw new Error(`frontend plan shard fact merge replay conflict: source event ${record.eventId} changed payload`);
                     }
+                    continue;
                 }
-            }
-            const components = typeof choice.component === "string" ? [choice.component] : [];
-            const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
-                kind: "component-choice",
-                origin: "plan",
-                scopeRequirementIds: scopedRequirementIds(),
-                components,
-                uiComponentChoices: [choice],
-                ...(params?.stylingStrategy
-                    ? { stylingStrategy: params.stylingStrategy }
-                    : {}),
-            });
-            // Echo the frozen citation the runtime derived: the model sees the
-            // purpose↔citation mapping it just committed and can re-record the
-            // choice (last-wins per purpose at compile) when it mismatches.
-            const echo = {
-                ...result,
-                ...(choice.specReference
-                    ? { derivedSpecReference: choice.specReference }
-                    : {}),
-            };
-            return planToolReceipt(echo);
-        },
-    });
-    // Global UX vocabulary: one compact registry committed BEFORE any state
-    // flow details. Coverage may slice by AC; UX must not — the registry is
-    // the anti-duplication anchor that keeps every later slice on the same
-    // named concepts instead of re-inventing them per AC chunk.
-    const recordStateRegistryTool = defineTool({
-        name: "record_state_registry",
-        label: "record_state_registry",
-        description: "Commit the GLOBAL UX vocabulary (origin=plan state-registry fact) BEFORE any record_state_flow call: uiStateNames (use the contract's declared authoritative state ids when provided) and interactionNames (stable behavior-domain kebab-case names, e.g. planner-task-edit / focus-queue-move — one name per behavior domain, never one per AC). Empty arrays explicitly mean the request has no UI state or interaction vocabulary. Re-record the full vocabulary to correct it; the latest commit wins, but it may not remove names still referenced by committed state-flow facts. Example: {\"uiStateNames\": [\"planner-empty\"], \"interactionNames\": [\"planner-task-create\", \"focus-queue-move\"]}",
-        promptSnippet: "Record the global UI-state/interaction vocabulary once, before any state flow.",
-        parameters: Type.Object({
-            uiStateNames: stringArray,
-            interactionNames: stringArray,
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const uiStateNames = [...new Set(stringList(params?.uiStateNames).map((name) => name.trim()))];
-            const interactionNames = [
-                ...new Set(stringList(params?.interactionNames).map((name) => name.trim())),
-            ];
-            if (uiStateNames.some((name) => name.length === 0) || interactionNames.some((name) => name.length === 0)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "state-registry",
-                    error: "record_state_registry names must be non-empty strings",
-                });
-            }
-            const invalidInteractionNames = interactionNames.filter((name) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name));
-            if (invalidInteractionNames.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "state-registry",
-                    error: `record_state_registry interactionNames must be stable kebab-case behavior-domain names: ${invalidInteractionNames.join(", ")}`,
+                const explicitReplacement = typeof fact.replaces === "string" &&
+                    fact.replaces === entry?.id;
+                const conflicting = committed.find((candidate) => {
+                    const candidateFact = candidate.fact;
+                    const candidateEntry = candidateFact.entry;
+                    const sameSourceShard = candidate.requestId.startsWith(sourceShardPrefix);
+                    return (candidateFact.kind === kind &&
+                        typeof candidateEntry?.id === "string" &&
+                        `${kind}:${candidateEntry.id}` === identity &&
+                        !(sameSourceShard && explicitReplacement));
                 });
-            }
-            if (input.declaredUiStateIds &&
-                input.declaredUiStateIds.length > 0) {
-                const declared = new Set(input.declaredUiStateIds);
-                const undeclared = uiStateNames.filter((name) => !declared.has(name));
-                if (undeclared.length > 0) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-registry",
-                        error: `record_state_registry uiStateNames are not declared by the contract's authoritative UI-state table: ${undeclared.join(", ")}; use the declared ids (${input.declaredUiStateIds.join(", ")})`,
-                    });
+                if (conflicting) {
+                    // Two shards may honestly emit the same fact (e.g. both
+                    // derive the same frozen verification target). Identical
+                    // payloads are duplicates to skip; divergent payloads are
+                    // a real conflict the ladder must resolve.
+                    if (conflicting.payloadSha256 === record.payloadSha256) {
+                        continue;
+                    }
+                    const fromSameSourceShard = conflicting.requestId.startsWith(sourceShardPrefix);
+                    if (fromSameSourceShard) {
+                        throw new Error(`frontend plan shard fact merge conflict: ${identity} was already committed by another shard with a different payload`);
+                    }
+                    // Divergent payload from a different source attempt means a
+                    // ladder retry re-derived the coverage phase: the fresh
+                    // derivation supersedes the stored record.
+                    const storeWithRecords = session.store;
+                    storeWithRecords.records = storeWithRecords.records.filter((candidate) => candidate.eventId !== conflicting.eventId);
                 }
-                const missing = input.declaredUiStateIds.filter((name) => !uiStateNames.includes(name));
-                if (missing.length > 0) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-registry",
-                        error: `record_state_registry must include every state from the contract's authoritative UI-state table; missing: ${missing.join(", ")}`,
-                    });
+                const result = await adoptPlanFact(kind, requestId, fact);
+                if (!result.ok) {
+                    throw new Error(`frontend plan shard fact merge failed: ${result.error}`);
                 }
             }
-            // A correction is deterministic only when the new last-wins registry
-            // still contains every live name already committed by state-flow facts.
-            // This permits adding a missed concept, while preventing a registry edit
-            // from retroactively orphaning earlier slices.
-            const liveNames = collectCanonicalStateFlowNames(readCommittedEvents(store, attemptId));
-            const orphanedUiStates = [...liveNames.uiStateNames].filter((name) => !uiStateNames.includes(name));
-            const orphanedInteractions = [...liveNames.interactionNames].filter((name) => !interactionNames.includes(name));
-            if (orphanedUiStates.length > 0 || orphanedInteractions.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "state-registry",
-                    error: `record_state_registry cannot remove names still referenced by committed state-flow facts (uiStates: ${orphanedUiStates.join(", ") || "none"}; interactions: ${orphanedInteractions.join(", ") || "none"}); first correct/remove those state-flow entries, then re-record the full registry`,
-                });
-            }
-            const result = await adoptPlanFact("state-registry", `${attemptId}:record_state_registry:${randomUUID()}`, {
-                kind: "state-registry",
-                origin: "plan",
-                uiStateNames,
-                interactionNames,
-            });
-            return planToolReceipt(result);
-        },
-    });
-    const recordStateFlowTool = defineTool({
-        name: "record_state_flow",
-        label: "record_state_flow",
-        description: "Record UI states and interactions as an origin=plan state-flow fact. REQUIRES a committed record_state_registry vocabulary first, and every name here must be in that registry; uiState names must also be contract-declared authoritative ids when the contract declares them. To correct stale named entries from an earlier UX batch, include removeUiStateNames and/or removeInteractionNames. Example: {\"uiStates\": [{\"name\": \"<state>\", \"applicable\": true, \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}], \"interactions\": [{\"name\": \"<interaction>\", \"trigger\": \"<user event>\", \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}]}",
-        promptSnippet: "Record the plan state-flow fact.",
-        parameters: Type.Object({
-            uiStates: Type.Array(uiStateSchema),
-            interactions: Type.Array(interactionSchema),
-            removeUiStateNames: Type.Optional(stringArray),
-            removeInteractionNames: Type.Optional(stringArray),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const rawUiStates = Array.isArray(params?.uiStates)
-                ? params.uiStates
-                : [];
-            const rawInteractions = Array.isArray(params?.interactions)
-                ? params.interactions
-                : [];
-            const removeUiStateNames = stringList(params?.removeUiStateNames);
-            const removeInteractionNames = stringList(params?.removeInteractionNames);
-            const uiStates = [];
-            for (const rawState of rawUiStates) {
-                if (!isRecordObject(rawState)) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: "record_state_flow uiStates entries must be objects",
-                    });
-                }
-                const { reason, notApplicableReason, ...state } = rawState;
-                const canonicalReason = nonEmptyString(notApplicableReason);
-                const aliasReason = nonEmptyString(reason);
-                if (canonicalReason !== undefined &&
-                    aliasReason !== undefined &&
-                    canonicalReason !== aliasReason) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: "record_state_flow uiState has conflicting reason and notApplicableReason values",
-                    });
-                }
-                const resolvedReason = canonicalReason ?? aliasReason;
-                if (state.applicable === false && !resolvedReason) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: "record_state_flow requires non-empty notApplicableReason when uiState.applicable is false",
-                    });
-                }
-                uiStates.push({
-                    ...state,
-                    ...(resolvedReason
-                        ? { notApplicableReason: resolvedReason }
-                        : {}),
-                });
-            }
-            const interactions = [];
-            for (const rawInteraction of rawInteractions) {
-                if (!isRecordObject(rawInteraction)) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: "record_state_flow interactions entries must be objects",
-                    });
-                }
-                const { id, name, ...interaction } = rawInteraction;
-                const canonicalName = nonEmptyString(name);
-                const aliasName = nonEmptyString(id);
-                if (canonicalName !== undefined &&
-                    aliasName !== undefined &&
-                    canonicalName !== aliasName) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: "record_state_flow interaction has conflicting id and name values",
-                    });
-                }
-                const resolvedName = canonicalName ?? aliasName;
-                if (!resolvedName) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: "record_state_flow requires non-empty interaction.name (id is accepted only as a legacy alias)",
-                    });
-                }
-                // Interaction -> VT forward references are legal only against
-                // already-committed VT facts. In the segmented flow every VT
-                // commits in the coverage segment before state flows run, so a
-                // dangling reference here is a real defect (r20: *-BEHAVIOR
-                // refs reached the final review untraceable).
-                const interactionVtIds = stringList(interaction.verificationTargetIds);
-                const committedVtIds = new Set(readCommittedEvents(store, attemptId)
-                    .map((event) => event.fact)
-                    .filter((fact) => fact.kind === "plan-verification-target")
-                    .map((fact) => fact.entry
-                    ?.id)
-                    .filter((id) => typeof id === "string"));
-                const unknownVtIds = interactionVtIds.filter((id) => !committedVtIds.has(id));
-                if (unknownVtIds.length > 0) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: `record_state_flow interaction "${resolvedName}" references verification targets that are not recorded yet: ${unknownVtIds.join(", ")}; record them with record_plan_verification_target first, then re-record this state flow`,
-                    });
-                }
-                interactions.push({ ...interaction, name: resolvedName });
-            }
-            // UX vocabulary gate: every recorded state/interaction name must be
-            // declared in the committed global registry first. This keeps UX out
-            // of AC-number slicing — the model commits one compact vocabulary
-            // (record_state_registry), then fills behavior-domain details, and a
-            // later slice cannot silently rename an earlier concept (dogfood
-            // dag-1788504923861-0f7b17a9: 5 renames of "prioritize" + 7 of
-            // "focus queue" across AC chunks).
-            const states = uiStates
-                .map((state) => (typeof state?.name === "string" ? state.name : ""))
-                .filter(Boolean);
-            const committedRegistry = readCommittedEvents(store, attemptId)
-                .map((event) => event.fact)
-                .filter((fact) => isRecordObject(fact) && fact.kind === "state-registry")
-                .at(-1);
-            if (!committedRegistry) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "state-flow",
-                    error: "record_state_flow requires a committed UX registry first: call record_state_registry with the full uiStateNames/interactionNames vocabulary, then record state flows against it",
-                });
-            }
-            const registryUiStateNames = new Set(stringList(committedRegistry.uiStateNames));
-            const registryInteractionNames = new Set(stringList(committedRegistry.interactionNames));
-            const unknownStates = states.filter((name) => !registryUiStateNames.has(name));
-            if (unknownStates.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "state-flow",
-                    error: `record_state_flow uiState names not in the committed registry: ${unknownStates.join(", ")}; re-record record_state_registry with the complete vocabulary first (registered: ${[...registryUiStateNames].join(", ") || "(none)"})`,
-                });
-            }
-            const unknownInteractions = interactions
-                .map((interaction) => typeof interaction?.name === "string" ? interaction.name : "")
-                .filter((name) => name && !registryInteractionNames.has(name));
-            if (unknownInteractions.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "state-flow",
-                    error: `record_state_flow interaction names not in the committed registry: ${unknownInteractions.join(", ")}; re-record record_state_registry with the complete vocabulary first (registered: ${[...registryInteractionNames].join(", ") || "(none)"})`,
-                });
-            }
-            // Authoritative UI states: when the contract node declared the
-            // source's UI-state table, planner states must bind those ids — no
-            // invented variants (planner-empty/create-invalid/no-results/
-            // editing/focus-full/storage-unavailable, not "planner-list").
-            if (input.declaredUiStateIds &&
-                input.declaredUiStateIds.length > 0) {
-                const declared = new Set(input.declaredUiStateIds);
-                const undeclaredStates = states.filter((name) => !declared.has(name));
-                if (undeclaredStates.length > 0) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "state-flow",
-                        error: `record_state_flow uiState names are not declared by the contract's authoritative UI-state table: ${undeclaredStates.join(", ")}; use the declared ids (${input.declaredUiStateIds.join(", ")}), or record a design deviation if the source table is genuinely incomplete`,
-                    });
-                }
-            }
-            // Named entries are last-wins at assembly. A scoped correction may
-            // replace its own bindings, but must retain other scopes' coverage.
-            const scope = new Set(scopedRequirementIds());
-            const committed = readCommittedEvents(store, attemptId).map(event => event.fact);
-            const targetOwners = new Map();
-            for (const fact of committed) {
-                if (fact.kind === "plan-verification-target" && isRecordObject(fact.entry) && typeof fact.entry.id === "string") {
-                    targetOwners.set(fact.entry.id, stringList(fact.entry.requirementIds));
-                }
-            }
-            for (const [field, removals] of [["uiStates", removeUiStateNames], ["interactions", removeInteractionNames]]) {
-                const live = new Map();
-                for (const fact of committed) {
-                    if (fact.kind !== "state-flow")
-                        continue;
-                    for (const name of stringList(fact[field === "uiStates" ? "removeUiStateNames" : "removeInteractionNames"]))
-                        live.delete(name);
-                    for (const entry of Array.isArray(fact[field]) ? fact[field] : []) {
-                        if (isRecordObject(entry) && typeof entry.name === "string")
-                            live.set(entry.name, entry);
-                    }
-                }
-                const foreignBindings = (entry) => scope.size === 0 ? [] : stringList(entry.verificationTargetIds).filter(id => {
-                    const owners = targetOwners.get(id);
-                    return !owners?.length || owners.some(owner => !scope.has(owner));
-                });
-                for (const name of removals) {
-                    const previous = live.get(name);
-                    if (previous && foreignBindings(previous).length)
-                        return planToolReceipt({ ok: false, kind: "state-flow",
-                            error: `Cannot remove shared ${name} from this requirement scope; retain it and update its scoped bindings instead` });
-                }
-                for (const entry of field === "uiStates" ? uiStates : interactions) {
-                    const previous = live.get(String(entry.name));
-                    if (previous)
-                        entry.verificationTargetIds = [...new Set([...foreignBindings(previous), ...stringList(entry.verificationTargetIds)])];
-                }
-            }
-            const result = await adoptPlanFact("state-flow", `${attemptId}:record_state_flow:${randomUUID()}`, {
-                kind: "state-flow",
-                origin: "plan",
-                scopeRequirementIds: scopedRequirementIds(),
-                states,
-                uiStates,
-                interactions,
-                removeUiStateNames,
-                removeInteractionNames,
-            });
-            return planToolReceipt(result);
-        },
-    });
-    const recordDataFlowTool = defineTool({
-        name: "record_data_flow",
-        label: "record_data_flow",
-        description: "Record interaction/endpoint data flow as an origin=plan data-flow fact. Example: {\"interactions\": [\"<interaction name>\"], \"endpoints\": [\"GET <path>\"]}",
-        promptSnippet: "Record the plan data-flow fact.",
-        parameters: Type.Object({ interactions: stringArray, endpoints: stringArray, replace: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const previous = params.replace ? undefined : readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "data-flow").at(-1)?.fact;
-            const result = await adoptPlanFact("data-flow", `${attemptId}:record_data_flow:${randomUUID()}`, {
-                kind: "data-flow",
-                origin: "plan",
-                interactions: [...new Set([...stringList(previous?.interactions), ...stringList(params?.interactions)])],
-                endpoints: [...new Set([...stringList(previous?.endpoints), ...stringList(params?.endpoints)])],
-            });
-            return planToolReceipt(result);
-        },
-    });
-    const recordMockApiTool = defineTool({
-        name: "record_mock_api",
-        label: "record_mock_api",
-        description: "Record the Mock/API strategy as an origin=plan mock-api fact. Example: {\"mockApi\": {\"strategy\": \"not-needed\", \"activation\": \"n/a\", \"endpoints\": []}}",
-        promptSnippet: "Record the plan mock-api fact.",
-        parameters: Type.Object({ mockApi: mockApiSchema }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const mockApi = params?.mockApi ?? {
-                strategy: "not-needed",
-                activation: "",
-                endpoints: [],
-            };
-            const endpoints = stringList((Array.isArray(mockApi?.endpoints) ? mockApi.endpoints : []).map((endpoint) => `${typeof endpoint?.method === "string" ? endpoint.method : ""} ${typeof endpoint?.path === "string" ? endpoint.path : ""}`.trim()));
-            const result = await adoptPlanFact("mock-api", `${attemptId}:record_mock_api:${randomUUID()}`, {
-                kind: "mock-api",
-                origin: "plan",
-                strategy: typeof mockApi?.strategy === "string" ? mockApi.strategy : "",
-                endpoints,
-                mockApi,
-            });
-            return planToolReceipt(result);
-        },
-    });
-    const recordMockEndpointTool = defineTool({
-        name: "record_mock_endpoint", label: "record_mock_endpoint",
-        description: "Record one Mock/API endpoint. First record_mock_api with the policy and endpoints: []; then submit each endpoint separately. Never regenerate the whole endpoint collection. Use replace:true to revise an existing method/path, or replace:true plus remove:true to withdraw it.",
-        parameters: Type.Object({ endpoint: mockEndpointSchema, remove: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
-        async execute(_callId, params) {
-            if (!readCommittedEvents(store, attemptId).some(r => r.fact.kind === "mock-api"))
-                return planToolReceipt({ ok: false, kind: "mock-endpoint", code: "MOCK_POLICY_MISSING", error: "Record the mock policy before its endpoints" });
-            return planToolReceipt(await adoptPlanFact("mock-endpoint", `${attemptId}:endpoint:${randomUUID()}`, { kind: "mock-endpoint", origin: "plan", endpoint: params.endpoint, ...(params.remove ? { removed: true } : {}) }));
-        },
-    });
-    const recordDesignDeviationTool = defineTool({
-        name: "record_design_deviation",
-        label: "record_design_deviation",
-        description: "Record design evidence conflicts as an origin=plan design-deviation fact. Example: {\"designEvidence\": {\"source\": \"<source>\", \"paths\": [\"<file>\"], \"conflicts\": [\"<conflicting requirement id>\"]}}",
-        promptSnippet: "Record the plan design-deviation fact.",
-        parameters: Type.Object({ designEvidence: designEvidenceSchema }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const conflicts = stringList(params?.designEvidence?.conflicts);
-            const result = await adoptPlanFact("design-deviation", `${attemptId}:record_design_deviation:${randomUUID()}`, { kind: "design-deviation", origin: "plan", conflicts });
-            return planToolReceipt(result);
-        },
-    });
-    const recordDependencyTool = defineTool({
-        name: "record_dependency",
-        label: "record_dependency",
-        description: "Record the dependency policy as an origin=plan dependency fact. Example: {\"policy\": \"<dependency policy statement>\"}",
-        promptSnippet: "Record the plan dependency fact.",
-        parameters: Type.Object({ policy: Type.String({}) }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const result = await adoptPlanFact("dependency", `${attemptId}:record_dependency:${randomUUID()}`, {
-                kind: "dependency",
-                origin: "plan",
-                policy: typeof params?.policy === "string" ? params.policy : "",
-            });
-            return planToolReceipt(result);
-        },
-    });
-    // Incremental plan payload records (one entry per call) so requirements,
-    // verification targets, evidence gaps, and implementation steps never have
-    // to be emitted as one large array inside a single finalize_plan call —
-    // they aggregate from the ledger in commit order. Mirrors the contract
-    // node's record_requirement pattern to stay within any model output budget.
-    const recordPlanRequirementTool = defineTool({
-        name: "record_plan_requirement",
-        label: "record_plan_requirement",
-        description: "Commit one plan requirement entry (origin=plan plan-requirement fact). Call once per requirement. Verification targets are authoritative in record_plan_verification_target; omit verificationTargetIds here unless repairing legacy input. For a correction, re-submit the same id with replace=true; the ledger compiles the latest replacement. Entry carries id, implementationTargets, and optional expectedOutcome (omit it — the runtime derives the outcome text from the contract requirement). IMPORTANT: batch up to 4 record_* calls per assistant message; never batch more than 4 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"id\": \"<AC-XXX>\", \"implementationTargets\": [\"<deliverable file>\"]}}",
-        promptSnippet: "Commit 1-4 plan requirement entries (up to 4 per message).",
-        parameters: Type.Object({
-            entry: requirementSchema,
-            replace: Type.Optional(Type.Boolean()),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const rawEntry = params?.entry;
-            if (!isRecordObject(rawEntry)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-requirement",
-                    error: "record_plan_requirement requires a non-empty entry object",
-                });
-            }
-            let entry = rawEntry;
-            // An embedded evidenceGap with a blank description means "no gap":
-            // small-output models emit the slot defensively with description ""
-            // on every requirement. The canonical contract schema requires a
-            // non-empty gap description (min 1 char), so passing the empty slot
-            // through would deterministically fail the plan compile with
-            // invalid-output and burn every retry. Drop the empty slot — the
-            // field is optional and the runtime derives real blocking gaps when
-            // a requirement has no proof.
-            const rawGap = isRecordObject(entry.evidenceGap)
-                ? entry.evidenceGap
-                : undefined;
-            if (rawGap &&
-                typeof rawGap.description === "string" &&
-                rawGap.description.trim() === "") {
-                const { evidenceGap: _omittedGap, ...rest } = entry;
-                void _omittedGap;
-                entry = rest;
-            }
-            // Canonical-identity check: a requirement id outside the frozen
-            // canonical list (e.g. a BR-* business rule picked up from the PRD
-            // prose) would commit an immutable fact that finalize's
-            // canonical-coverage gate rejects with no in-node cure. Reject here
-            // and name the allowed ids.
-            const id = typeof entry.id === "string" ? entry.id : "";
-            if (activeRequirementScope.length && !activeRequirementScope.includes(id))
-                return planToolReceipt({ ok: false, kind: "plan-requirement", code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: `Requirement ${id} is outside this session` });
-            if (id &&
-                input.requirementIds &&
-                input.requirementIds.length > 0 &&
-                !input.requirementIds.includes(id)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-requirement",
-                    error: `record_plan_requirement id "${id}" is not a frozen canonical requirement; canonical ids are: ${input.requirementIds.join(", ")}`,
-                });
-            }
-            // A requirement id is a canonical identity: recording it twice would
-            // compile a duplicate requirements[] entry and fail design review.
-            // Reject duplicates by default; replace=true is the explicit in-node
-            // correction path and the compiler keeps the latest replacement.
-            if (id && params?.replace !== true) {
-                const existing = readCommittedEvents(store, attemptId).find((event) => {
-                    const fact = event.fact;
-                    if (!fact || fact.kind !== "plan-requirement")
-                        return false;
-                    const entryFact = fact.entry;
-                    return (typeof entryFact?.id === "string" &&
-                        entryFact.id === id);
-                });
-                if (existing) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "plan-requirement",
-                        error: `record_plan_requirement duplicate: requirement ${id} is already recorded; do not record the same requirement id twice`,
-                    });
-                }
-            }
-            if (id &&
-                activeRequirementScope.length > 0 &&
-                !activeRequirementScope.includes(id)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-requirement",
-                    error: `record_plan_requirement id "${id}" is outside this session's requirement scope [${activeRequirementScope.join(", ")}]`,
-                });
-            }
-            const result = await adoptPlanFact("plan-requirement", `${attemptId}:record_plan_requirement:${randomUUID()}`, {
-                kind: "plan-requirement",
-                origin: "plan",
-                entry,
-                ...(params?.replace === true ? { replaces: id } : {}),
-            });
-            return planToolReceipt(result);
-        },
-    });
-    const recordPlanGroupCoverageTool = defineTool({
-        name: "record_plan_group_coverage", label: "record_plan_group_coverage",
-        description: "Submit shared implementation/verification references for one declared execution group. Runtime expands to every canonical member and retains its full outcome and source bindings. A shared VT must actually verify each independent condition. Use per-requirement records for differences; never create UI for constraints or exclusions. replace:true explicitly revises the group.",
-        parameters: Type.Object({ id: Type.String({ minLength: 1 }), implementationTargets: stringArray, verificationTargetIds: Type.Optional(stringArray), replace: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
-        async execute(callId, params, signal, onUpdate, ctx) {
-            const group = executionGroups.find(g => g.id === params.id && g.kind !== "unclassified");
-            if (!group || (activeRequirementScope.length && group.requirementIds.some(id => !activeRequirementScope.includes(id))))
-                return planToolReceipt({ ok: false, kind: "plan-requirement", code: "EXECUTION_GROUP_SCOPE_INVALID", error: "A known complete group must be present in this session; submit individual member records when the group spans scopes" });
-            let last;
-            for (const id of group.requirementIds) {
-                const existing = readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "plan-requirement" && r.fact.entry?.id === id).at(-1)?.fact.entry;
-                if (existing && !params.replace) {
-                    if (JSON.stringify(existing.implementationTargets) !== JSON.stringify(params.implementationTargets))
-                        return planToolReceipt({ ok: false, kind: "plan-requirement", code: "FACT_IDENTITY_CONFLICT", error: `${id}: existing coverage differs; use replace:true to revise explicitly` });
-                    continue;
-                }
-                last = await recordPlanRequirementTool.execute(`${callId}:${id}`, { entry: { id, implementationTargets: params.implementationTargets, ...(params.verificationTargetIds ? { verificationTargetIds: params.verificationTargetIds } : {}) }, ...(params.replace ? { replace: true } : {}) }, signal, onUpdate, ctx);
-                if (!last.details?.ok)
-                    return last;
-            }
-            return planToolReceipt(await adoptPlanFact("plan-group-coverage", `${attemptId}:group:${randomUUID()}`, { kind: "plan-group-coverage", origin: "plan", id: group.id, requirementIds: group.requirementIds }));
-        },
-    });
-    const recordPlanVerificationTargetTool = defineTool({
-        name: "record_plan_verification_target",
-        label: "record_plan_verification_target",
-        description: "Commit one plan verification target entry (origin=plan plan-verification-target fact). Reference a frozen verification command by commandId (see the frozen command directory in your prompt: static commands are project-wide checks traced by file and command only; behavior commands bind an existing affected test file; preserve its test names). For behavior targets, call once per distinct behavior, not mechanically once per requirement: one target may cover multiple related requirementIds. For a correction, re-submit the same id with replace=true; the ledger compiles the latest replacement. A target id identifies a contract entry only; never require it in test names. Results bind by frozen command and test file. Entry carries id, commandId, file, requirementIds, and uiStates; optional scope (unit | component | integration) is display-only. Free-form symbol text is not accepted. IMPORTANT: batch up to 4 record_* calls per assistant message; never batch more than 4 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"id\": \"VT-DASHBOARD-SHELL\", \"commandId\": \"<frozen behavior command id>\", \"file\": \"<test file>\", \"requirementIds\": [\"AC-001\", \"AC-002\"], \"uiStates\": []}}" +
-            (input.canonicalVerificationTargetIds &&
-                input.canonicalVerificationTargetIds.length > 0
-                ? ` Frozen canonical behavior target ids (use exactly for behavior targets): ${input.canonicalVerificationTargetIds.join(", ")}.`
-                : ""),
-        promptSnippet: "Commit 1-4 plan verification target entries (up to 4 per message).",
-        parameters: Type.Object({
-            entry: verificationTargetSchema,
-            replace: Type.Optional(Type.Boolean()),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const rawEntry = params?.entry;
-            if (!isRecordObject(rawEntry)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: "record_plan_verification_target requires a non-empty entry object",
-                });
-            }
-            // Contract v2: the plan references a frozen command by commandId;
-            // mode and label are resolved by the runtime from the frozen
-            // command directory (run.json frontend-verify-shell bundle lanes).
-            // Reject unknown ids and behavior commands bound to non-test
-            // files here so the model fixes them in-node instead of the
-            // attempt dying at materialization or at the writer focused-check.
-            const verificationCommandId = typeof rawEntry.commandId === "string"
-                ? rawEntry.commandId.trim()
-                : "";
-            if (!verificationCommandId) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: `record_plan_verification_target entry.commandId is required (received ${JSON.stringify(rawEntry.commandId ?? null)}); pick one id from the frozen command directory in your prompt`,
-                });
-            }
-            const { deriveFrontendVerifyCommandDirectoryFromRun, isFrontendTestFilePath, } = await import("../workflows/dag/frontend-implementation-contract.js");
-            const verifyDirectory = await deriveFrontendVerifyCommandDirectoryFromRun(input.runDir);
-            if (verifyDirectory.length > 0) {
-                const directoryEntry = verifyDirectory.find((entry) => entry.commandId === verificationCommandId);
-                if (!directoryEntry) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "plan-verification-target",
-                        error: `record_plan_verification_target verification-target-unknown-command: unknown commandId "${verificationCommandId}"; available frozen commands: [${verifyDirectory.map((entry) => `${entry.commandId} (${entry.mode}: ${entry.label})`).join(", ")}]`,
-                    });
-                }
-                if (directoryEntry.mode === "behavior" &&
-                    typeof rawEntry.file === "string" &&
-                    !isFrontendTestFilePath(rawEntry.file)) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "plan-verification-target",
-                        error: `record_plan_verification_target verification-target-phase-mismatch: behavior command "${directoryEntry.label}" (${directoryEntry.commandId}) must bind a test file (__tests__/, tests?/, e2e/, cypress/, *.test.*, *.spec.*, *.cy.*); received file "${rawEntry.file}"`,
-                    });
-                }
-                // Canonical-identity check for behavior targets: the PRD freezes
-                // the exact behavior verification-target ids (e.g.
-                // VT-SMOKE-COUNTER-BEHAVIOR). A committed non-canonical id is
-                // immutable and design review rejects it as a
-                // contract-requirement gap, so reject invented ids here.
-                if (directoryEntry.mode === "behavior" &&
-                    input.canonicalVerificationTargetIds &&
-                    input.canonicalVerificationTargetIds.length > 0) {
-                    const canonicalTargetId = typeof rawEntry.id === "string" ? rawEntry.id.trim() : "";
-                    if (canonicalTargetId &&
-                        !input.canonicalVerificationTargetIds.includes(canonicalTargetId)) {
-                        return planToolReceipt({
-                            ok: false,
-                            kind: "plan-verification-target",
-                            error: `record_plan_verification_target id "${canonicalTargetId}" is not a frozen canonical behavior verification target; canonical ids are: ${input.canonicalVerificationTargetIds.join(", ")}`,
-                        });
-                    }
-                }
-            }
-            // Duplicate-id rejection: committed typed facts are immutable, so
-            // re-recording the same VT id would deadlock the compile by default.
-            // replace=true is the explicit in-node correction path.
-            const vtId = typeof rawEntry.id === "string" ? rawEntry.id : "";
-            if (vtId &&
-                params?.replace !== true &&
-                readCommittedEvents(store, attemptId).some((event) => {
-                    const fact = event.fact;
-                    if (!fact || fact.kind !== "plan-verification-target")
-                        return false;
-                    const entryFact = fact.entry;
-                    return entryFact?.id === vtId;
-                })) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: `record_plan_verification_target duplicate: verification target ${vtId} is already recorded; use replace=true for an in-node correction`,
-                });
-            }
-            // WriteSet containment at the boundary: a committed VT fact whose
-            // file is outside the task writeSet is immutable, and the finalize
-            // pre-validation would then fail the whole attempt with no in-node
-            // cure (r17 post-merge). Reject here with the allowed patterns.
-            if (typeof rawEntry.file === "string" &&
-                input.writeSetPatterns &&
-                input.writeSetPatterns.length > 0 &&
-                !input.writeSetPatterns.some((pattern) => pathMatchesPattern(rawEntry.file, pattern))) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: `record_plan_verification_target file is outside the writeSet patterns [${input.writeSetPatterns.join(", ")}]: ${rawEntry.file}; verification targets must point inside the task writeSet`,
-                });
-            }
-            // uiStates: [] means this verification target is intentionally not
-            // bound to a named UI state. Keep that canonical representation even
-            // when a model omits the optional tool-boundary field.
-            const entryWithoutSymbol = { ...rawEntry };
-            delete entryWithoutSymbol.symbol;
-            const entry = {
-                ...entryWithoutSymbol,
-                uiStates: stringList(rawEntry.uiStates),
-            };
-            // Cross-reference integrity at the boundary: the compile gate
-            // rejects verification targets referencing UI states or
-            // requirements that were never declared. Validate against the
-            // facts already committed in this attempt so the model fixes the
-            // reference in-node instead of burning the attempt at compile time
-            // (r7: one full attempt lost to a single unknown UI state name).
-            const committedEvents = readCommittedEvents(store, attemptId);
-            const declaredUiStateNames = collectCanonicalStateFlowNames(committedEvents).uiStateNames;
-            const unknownUiStates = entry.uiStates.filter((name) => !declaredUiStateNames.has(name));
-            if (unknownUiStates.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: `record_plan_verification_target references UI states that were never declared: ${unknownUiStates.join(", ")}; declare every referenced UI state with record_state_flow first, or pass uiStates: [] for intentionally unbound targets`,
-                });
-            }
-            const declaredRequirementIds = new Set(committedEvents.flatMap((event) => {
-                const fact = event.fact;
-                if (!fact || fact.kind !== "plan-requirement")
-                    return [];
-                const requirementEntry = fact.entry;
-                return typeof requirementEntry?.id === "string"
-                    ? [requirementEntry.id]
-                    : [];
-            }));
-            const unknownRequirementIds = stringList(rawEntry.requirementIds).filter((id) => !declaredRequirementIds.has(id));
-            const outOfScopeRequirementIds = stringList(rawEntry.requirementIds).filter((id) => activeRequirementScope.length > 0 &&
-                !activeRequirementScope.includes(id));
-            if (outOfScopeRequirementIds.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: `record_plan_verification_target references requirements outside this session's scope [${activeRequirementScope.join(", ")}]: ${outOfScopeRequirementIds.join(", ")}`,
-                });
-            }
-            if (unknownRequirementIds.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-verification-target",
-                    error: `record_plan_verification_target references unknown requirement ids: ${unknownRequirementIds.join(", ")}; record every referenced requirement with record_plan_requirement first`,
-                });
-            }
-            const result = await adoptPlanFact("plan-verification-target", `${attemptId}:record_plan_verification_target:${randomUUID()}`, {
-                kind: "plan-verification-target",
-                origin: "plan",
-                entry,
-                ...(params?.replace === true ? { replaces: vtId } : {}),
-            });
-            return planToolReceipt(result);
-        },
-    });
-    const recordPlanEvidenceGapTool = defineTool({
-        name: "record_plan_evidence_gap",
-        label: "record_plan_evidence_gap",
-        description: "Commit one plan evidence gap entry (origin=plan plan-evidence-gap fact). Call once per gap; entry carries requirementId, description, blocking. IMPORTANT: batch up to 4 record_* calls per assistant message; never batch more than 4 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"requirementId\": \"<AC-XXX>\", \"description\": \"<what evidence is missing and why>\", \"blocking\": false}}",
-        promptSnippet: "Commit 1-4 plan evidence gap entries (up to 4 per message).",
-        parameters: Type.Object({
-            entry: evidenceGapSchema,
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const rawEntry = params?.entry;
-            if (!isRecordObject(rawEntry)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-evidence-gap",
-                    error: "record_plan_evidence_gap requires a non-empty entry object",
-                });
-            }
-            const entry = rawEntry;
-            // A standalone evidence gap IS the gap statement: a blank description
-            // would fail the canonical contract schema (min 1 char) after the
-            // whole attempt finished. Reject at the boundary so the model writes
-            // a real description in-node instead of burning the attempt.
-            if (typeof entry.description === "string" &&
-                entry.description.trim() === "") {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-evidence-gap",
-                    error: "record_plan_evidence_gap requires a non-empty description describing the gap",
-                });
-            }
-            const requirementId = typeof entry.requirementId === "string"
-                ? entry.requirementId
-                : undefined;
-            if (requirementId &&
-                activeRequirementScope.length > 0 &&
-                !activeRequirementScope.includes(requirementId)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "plan-evidence-gap",
-                    error: `record_plan_evidence_gap requirementId "${requirementId}" is outside this session's requirement scope [${activeRequirementScope.join(", ")}]`,
-                });
-            }
-            const result = await adoptPlanFact("plan-evidence-gap", `${attemptId}:record_plan_evidence_gap:${randomUUID()}`, { kind: "plan-evidence-gap", origin: "plan", entry });
-            return planToolReceipt(result);
-        },
-    });
-    const finalizePlanTool = defineTool({
-        name: "finalize_plan",
-        label: "finalize_plan",
-        description: "Commit the finalize_plan terminal. Requirements, verification targets, and evidence gaps (optional) were already committed incrementally through record_plan_requirement / record_plan_verification_target / record_plan_evidence_gap; finalize_plan assembles them from the ledger together with these optional remaining fields, publishes the canonical editable patch on a target-surface fact, and commits the terminal. A successful terminal commit occurs exactly once. If validation fails, correct only the reported facts and retry finalize.",
-        promptSnippet: "Commit the finalize_plan terminal (ledger fields + optional residualRisks / realIntegrationGap).",
-        parameters: Type.Object({
-            residualRisks: optionalStringArray,
-            realIntegrationGap: optionalString,
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            try {
-                const committed = readCommittedEvents(store, attemptId);
-                // Source fidelity ledger (AC-005/AC-006): inherit the contract
-                // node's declared requirement→fragment provenance so the compiled
-                // canonical contract carries sourceFragmentIds/sourceRefs even
-                // when the plan did not re-declare them. The contract node is the
-                // sole synthesis point; the plan inherits by requirement id.
-                const contractInheritance = await loadContractRequirementInheritance(input.runDir);
-                const missingData = collectFrontendPlanPhaseMissingFacts({ phase: "global-mock-data", requirementIds: input.requirementIds ?? [...contractInheritance.keys()], committedFacts: committed }).filter(f => f.kind === "data-flow");
-                if (missingData.length)
-                    return planToolReceipt({ ok: false, kind: "finalize_plan", code: "PLAN_DATA_FLOW_INCOMPLETE", error: missingData.map(f => f.reason).join("; ") });
-                const fragment = assemblePlanPatchFromCommittedFacts(committed, contractInheritance) ?? {};
-                const patch = {
-                    ...fragment,
-                    ...(params?.residualRisks
-                        ? { residualRisks: params.residualRisks }
-                        : {}),
-                    ...(params?.realIntegrationGap
-                        ? { realIntegrationGap: params.realIntegrationGap }
-                        : {}),
-                };
-                const latestRegistry = [...committed]
-                    .reverse()
-                    .map((record) => record.fact)
-                    .find((fact) => isRecordObject(fact) && fact.kind === "state-registry");
-                if (latestRegistry) {
-                    const registryUiStates = new Set(stringList(latestRegistry.uiStateNames));
-                    const registryInteractions = new Set(stringList(latestRegistry.interactionNames));
-                    const live = collectCanonicalStateFlowNames(committed);
-                    const missingUiStates = [...registryUiStates].filter((name) => !live.uiStateNames.has(name));
-                    const missingInteractions = [...registryInteractions].filter((name) => !live.interactionNames.has(name));
-                    const undeclaredUiStates = [...live.uiStateNames].filter((name) => !registryUiStates.has(name));
-                    const undeclaredInteractions = [...live.interactionNames].filter((name) => !registryInteractions.has(name));
-                    if (missingUiStates.length > 0 ||
-                        missingInteractions.length > 0 ||
-                        undeclaredUiStates.length > 0 ||
-                        undeclaredInteractions.length > 0) {
-                        return planToolReceipt({
-                            ok: false,
-                            kind: "finalize_plan",
-                            error: `finalize_plan UX registry mismatch: every registered name must have one live state-flow entry and every live entry must be registered (missing uiStates: ${missingUiStates.join(", ") || "none"}; missing interactions: ${missingInteractions.join(", ") || "none"}; undeclared uiStates: ${undeclaredUiStates.join(", ") || "none"}; undeclared interactions: ${undeclaredInteractions.join(", ") || "none"})`,
-                        });
-                    }
-                }
-                // Front-load the node's compile + policy gates into the finalize
-                // receipt (same pipeline the design-policy shell and the node
-                // self-check run: merge the patch onto the runtime skeleton,
-                // then the full analyze). A failing gate used to burn an entire
-                // attempt per finding (r8/r9: ui-design-coverage, verification
-                // targets, UI-state shape, one attempt each); surfaced here the
-                // model fixes the facts and re-calls finalize_plan in-node.
-                if (input.skeleton && input.sourceBinding) {
-                    // Front-load the exact pipeline the design-policy shell and
-                    // the node self-check run (patch ⊕ skeleton -> analyze ->
-                    // policy pre-checks) into the finalize receipt. Findings
-                    // come back as fixable receipt errors instead of burning
-                    // an attempt per gate (r8/r9: coverage, verification
-                    // targets, UI-state shape each cost a full attempt).
-                    const { analyzeFrontendPlanPatchCandidate, applyFrontendContractMergePatch, FrontendContractFailure, PlanPolicyPrecheckFailure, serializeDeterministicJson, } = await import("../workflows/dag/frontend-implementation-contract.js");
-                    try {
-                        const merged = applyFrontendContractMergePatch(input.skeleton, patch);
-                        await analyzeFrontendPlanPatchCandidate({
-                            runDir: input.runDir,
-                            rawContractText: serializeDeterministicJson(merged),
-                            sourceBinding: input.sourceBinding,
-                        });
-                    }
-                    catch (error) {
-                        if (error instanceof PlanPolicyPrecheckFailure) {
-                            // Template the fix: every uncovered interaction / state
-                            // maps to a record_component_choice skeleton. Reuse is
-                            // never implied: the operator/model must fill an existing
-                            // evidencePath or switch the choice to decision=new with
-                            // the required frozen source citation.
-                            const suggestions = error.findings
-                                .filter((finding) => finding.code === "ui-design-coverage-missing" &&
-                                finding.path)
-                                .map((finding) => ({
-                                tool: "record_component_choice",
-                                args: {
-                                    choice: {
-                                        purpose: finding.path,
-                                        component: "<name the existing or new component>",
-                                        decision: "reuse-existing",
-                                        evidencePath: "<existing repo file that proves this reuse>",
-                                    },
-                                },
-                            }));
-                            const suggestionBlock = suggestions.length > 0
-                                ? ` Suggested record_* calls (copy, fill component, submit): ${JSON.stringify(suggestions)}`
-                                : "";
-                            return planToolReceipt({
-                                ok: false,
-                                kind: "finalize_plan",
-                                error: `finalize_plan pre-validation failed (fix the listed plan facts with record_* tools, then call finalize_plan again): ${error.message}${suggestionBlock}`,
-                            });
-                        }
-                        if (!(error instanceof FrontendContractFailure))
-                            throw error;
-                        return planToolReceipt({
-                            ok: false,
-                            kind: "finalize_plan",
-                            error: `finalize_plan pre-validation failed (fix the listed plan facts with record_* tools, then call finalize_plan again): ${error.message}`,
-                        });
-                    }
-                }
-                const patchResult = await adoptPlanFact("target-surface", `${attemptId}:finalize_plan:patch:${randomUUID()}`, { kind: "target-surface", origin: "plan", patch });
-                if (!patchResult.ok) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "finalize_plan",
-                        error: patchResult.error,
-                        code: patchResult.code,
-                    });
-                }
-                const terminal = await adoptPlanFact("finalize_plan", `${attemptId}:finalize_plan:terminal:${randomUUID()}`, { kind: "finalize_plan", origin: "plan", patch });
-                return planToolReceipt(terminal);
-            }
-            catch (error) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "finalize_plan",
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        },
-    });
-    const adoptStagedFactTool = defineTool({
-        name: "adopt_staged_fact",
-        label: "adopt_staged_fact",
-        description: "Explicitly adopt a quarantined fact from a prior attempt into the committed ledger (idempotent by requestId).",
-        promptSnippet: "Adopt a quarantined fact into the committed ledger.",
-        parameters: Type.Object({
-            requestId: Type.String({}),
-            eventId: Type.String({}),
-            expectedRevision: Type.Number({}),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            try {
-                const adopted = await adoptStagedFact({
-                    store,
-                    requestId: typeof params?.requestId === "string" ? params.requestId : "",
-                    attemptId,
-                    eventId: typeof params?.eventId === "string" ? params.eventId : "",
-                    expectedRevision: typeof params?.expectedRevision === "number"
-                        ? params.expectedRevision
-                        : store.revision,
-                });
-                return planToolReceipt({
-                    ok: true,
-                    kind: "adopt_staged_fact",
-                    eventId: adopted.eventId,
-                    revision: adopted.revision,
-                    error: "",
-                });
-            }
-            catch (error) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "adopt_staged_fact",
-                    error: error instanceof Error ? error.message : String(error),
-                    code: error?.code,
-                });
-            }
-        },
-    });
-    const readPlanFactsTool = defineTool({
-        name: "read_plan_facts",
-        label: "read_plan_facts",
-        description: "Read the LIVE committed plan ledger without repository access. Filter by kind and optional entryId or eventId. Use field (dot path, e.g. entry.requirementIds or uiStates) to page large arrays/strings. offset/limit paginate results; follow nextOffset until null before replacing any full-array fact. expectedRevision pins all pages to one ledger revision; restart if it changes. No writes.",
-        parameters: Type.Object({
-            kind: Type.String(), entryId: Type.Optional(Type.String()), eventId: Type.Optional(Type.String()),
-            field: Type.Optional(Type.String()), offset: Type.Optional(Type.Integer({ minimum: 0 })),
-            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
-            stringOffset: Type.Optional(Type.Integer({ minimum: 0 })),
-            expectedRevision: Type.Optional(Type.Integer({ minimum: 0 })),
-        }, { additionalProperties: false }),
-        async execute(_id, params) {
-            const reply = (details) => ({ content: [{ type: "text", text: JSON.stringify(details) }], details });
-            if (params.expectedRevision !== undefined && params.expectedRevision !== store.revision) {
-                return reply({ ok: false, revision: store.revision, error: "ledger revision changed; restart pagination" });
-            }
-            let records = readCommittedEvents(store, attemptId).filter(record => {
-                const fact = record.fact;
-                return fact.kind === params.kind && (!params.eventId || record.eventId === params.eventId) &&
-                    (!params.entryId || fact.entry?.id === params.entryId);
-            });
-            // Full-entry corrections and registries are last-wins. Other kinds
-            // remain an ordered event log (state removals must remain visible).
-            if (params.entryId || params.kind === "state-registry")
-                records = records.slice(-1);
-            let values = records.map(record => ({ eventId: record.eventId, ...record.fact }));
-            if (params.field) {
-                values = records.flatMap(record => {
-                    let value = record.fact;
-                    for (const key of params.field.split(".")) {
-                        if (!value || typeof value !== "object" || !Object.hasOwn(value, key))
-                            return [];
-                        value = value[key];
-                    }
-                    return Array.isArray(value) ? value : [value];
-                });
-            }
-            const offset = params.offset ?? 0;
-            if (params.stringOffset !== undefined) {
-                const value = values[offset];
-                if (typeof value !== "string")
-                    return reply({ ok: false, error: "stringOffset requires a string field item" });
-                // Unicode code points prevent a page boundary splitting a surrogate pair.
-                const characters = Array.from(value);
-                const chunk = characters.slice(params.stringOffset, params.stringOffset + 1000).join("");
-                const next = params.stringOffset + Array.from(chunk).length;
-                return reply({ ok: true, revision: store.revision, offset, stringOffset: params.stringOffset,
-                    chunk, totalCharacters: characters.length, nextStringOffset: next < characters.length ? next : null });
-            }
-            const items = [];
-            let bytes = 0;
-            for (const value of values.slice(offset, offset + (params.limit ?? 10))) {
-                const size = Buffer.byteLength(JSON.stringify(value));
-                if (bytes + size > 12_000)
-                    break;
-                bytes += size;
-                items.push(value);
-            }
-            if (!items.length && offset < values.length)
-                return reply({
-                    ok: false, revision: store.revision, total: values.length, offset,
-                    error: "item exceeds the page budget; select an eventId/entryId and a narrower field path; for a string item set stringOffset: 0 and follow nextStringOffset",
-                    fields: typeof values[offset] === "object" && values[offset] !== null ? Object.keys(values[offset]) : [],
-                });
-            return reply({ ok: true, revision: store.revision, total: values.length, offset, items,
-                nextOffset: offset + items.length < values.length ? offset + items.length : null });
-        },
-    });
-    const durable = await createDurableFrontendTools({
-        file: path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), attemptId, store: input.store,
-        setWorkingStore: next => { store = next; },
-        binding: { sourceBinding: input.sourceBinding, skeleton: input.skeleton, requirementIds: input.requirementIds, writeSet: input.writeSetPatterns, declaredUiStateIds: input.declaredUiStateIds, citations: input.componentNewSourceReferences, contractInheritance },
-        tools: [
-            recordRouteSelectionTool,
-            recordComponentChoiceTool,
-            recordStateRegistryTool,
-            recordStateFlowTool,
-            recordDataFlowTool,
-            recordMockApiTool,
-            recordMockEndpointTool,
-            recordDesignDeviationTool,
-            recordDependencyTool,
-            recordPlanRequirementTool,
-            recordPlanGroupCoverageTool,
-            recordPlanVerificationTargetTool,
-            recordPlanEvidenceGapTool,
-            adoptStagedFactTool,
-            finalizePlanTool,
-        ],
-    });
-    const durableFinalizePlanTool = durable.customTools.find((tool) => typeof tool === "object" && tool !== null && tool.name === "finalize_plan");
-    if (!durableFinalizePlanTool)
-        throw new Error("frontend plan durable finalize tool unavailable");
-    return {
-        customTools: [...durable.customTools, { ...readPlanFactsTool, execute: async (...args) => { await durable.flush(); return readPlanFactsTool.execute(...args); } }],
-        adoptCommittedFacts: async (records) => durable.commitExternal(async () => {
-            for (const record of records) {
-                if (record.phase !== "committed")
-                    continue;
-                const fact = record.fact;
-                if (!fact || typeof fact !== "object" || Array.isArray(fact))
-                    continue;
-                const kind = typeof fact.kind === "string"
-                    ? fact.kind
-                    : "plan-fact";
-                const entry = fact.entry;
-                const identity = (kind === "plan-requirement" || kind === "plan-verification-target") &&
-                    typeof entry?.id === "string"
-                    ? `${kind}:${entry.id}`
-                    : undefined;
-                const sourceShardPrefix = `${attemptId}:parallel-merge:${record.attemptId}:`;
-                const requestId = `${sourceShardPrefix}${record.eventId}`;
-                const committed = readCommittedEvents(store, attemptId);
-                const replay = committed.find((candidate) => candidate.requestId === requestId);
-                if (replay) {
-                    if (replay.payloadSha256 !== record.payloadSha256) {
-                        throw new Error(`frontend plan shard fact merge replay conflict: source event ${record.eventId} changed payload`);
-                    }
-                    continue;
-                }
-                const explicitReplacement = typeof fact.replaces === "string" &&
-                    fact.replaces === entry?.id;
-                const conflicting = committed.find((candidate) => {
-                    const candidateFact = candidate.fact;
-                    const candidateEntry = candidateFact.entry;
-                    const sameSourceShard = candidate.requestId.startsWith(sourceShardPrefix);
-                    return (candidateFact.kind === kind &&
-                        typeof candidateEntry?.id === "string" &&
-                        `${kind}:${candidateEntry.id}` === identity &&
-                        !(sameSourceShard && explicitReplacement));
-                });
-                if (conflicting) {
-                    // Two shards may honestly emit the same fact (e.g. both
-                    // derive the same frozen verification target). Identical
-                    // payloads are duplicates to skip; divergent payloads are
-                    // a real conflict the ladder must resolve.
-                    if (conflicting.payloadSha256 === record.payloadSha256) {
-                        continue;
-                    }
-                    const fromSameSourceShard = conflicting.requestId.startsWith(sourceShardPrefix);
-                    if (fromSameSourceShard) {
-                        throw new Error(`frontend plan shard fact merge conflict: ${identity} was already committed by another shard with a different payload`);
-                    }
-                    // Divergent payload from a different source attempt means a
-                    // ladder retry re-derived the coverage phase: the fresh
-                    // derivation supersedes the stored record.
-                    const storeWithRecords = store;
-                    storeWithRecords.records = storeWithRecords.records.filter((candidate) => candidate.eventId !== conflicting.eventId);
-                }
-                const result = await adoptPlanFact(kind, requestId, fact);
-                if (!result.ok) {
-                    throw new Error(`frontend plan shard fact merge failed: ${result.error}`);
-                }
-            }
-        }),
-        setActiveRequirementScope: (requirementIds) => {
-            activeRequirementScope = [
-                ...new Set(requirementIds.filter((id) => id.trim().length > 0)),
-            ];
+        }),
+        setActiveRequirementScope: (requirementIds) => {
+            session.activeRequirementScope = [
+                ...new Set(requirementIds.filter((id) => id.trim().length > 0)),
+            ];
         },
         flush: durable.flush,
-        finalizePlan: (params) => durableFinalizePlanTool.execute(`${attemptId}:auto-finalize-plan`, {
+        finalizePlan: (params) => durableFinalizePlanTool.execute(`${session.attemptId}:auto-finalize-plan`, {
             ...(params?.residualRisks
                 ? { residualRisks: [...params.residualRisks] }
                 : {}),
@@ -2804,10 +1224,10 @@ export async function createFrontendPlanLedgerTools(input) {
         // The wrapper passes this through to the typed tool; finalize itself
         // does not inspect the extension context.
         {}),
-        committedFactCount: () => readCommittedEvents(store, attemptId).length,
+        committedFactCount: () => readCommittedEvents(session.store, session.attemptId).length,
         committedRequirementIds: () => {
             const ids = new Set();
-            for (const event of readCommittedEvents(store, attemptId)) {
+            for (const event of readCommittedEvents(session.store, session.attemptId)) {
                 const fact = event.fact;
                 if (!fact || fact.kind !== "plan-requirement")
                     continue;
@@ -2817,62 +1237,12 @@ export async function createFrontendPlanLedgerTools(input) {
             }
             return ids;
         },
-        committedFacts: () => readCommittedEvents(store, attemptId),
+        committedFacts: () => readCommittedEvents(session.store, session.attemptId),
     };
 }
-/** Translate derived-patch validation findings into decision-channel
- * vocabulary. Each zod issue path names a COMPILED patch array, but the model
- * authored record_* facts — so quote the offending entry's identity and name
- * the tool that owns it (r14: "uiComponentChoices.0.specReference.section:
- * Required" is unactionable when the model has never heard of specReference). */
-export function translateDecisionPatchFindings(message, decision) {
-    const body = message.replace(/^invalid-output:\s*/, "");
-    return body
-        .split(/;\s*/)
-        .map(issue => {
-        const choice = issue.match(/uiComponentChoices\.(\d+)\.(.+)/);
-        if (choice) {
-            const row = decision.reuseDecisions[Number(choice[1])];
-            const base = row
-                ? `record_reuse_decision purpose "${row.purpose}" (component ${row.symbol}, decision ${row.decision}): ${issue}`
-                : `record_reuse_decision row ${choice[1]}: ${issue}`;
-            const field = choice[2];
-            return field?.startsWith("specReference")
-                ? `${base} — pass specSection (the AC id / task-source section it implements) on that entry, or use decision "reuse-existing"`
-                : base;
-        }
-        const focus = issue.match(/verificationTargets\.(\d+)\.(.+)/);
-        if (focus) {
-            const row = decision.verificationFocus[Number(focus[1])];
-            if (!row)
-                return `record_verification_focus row ${focus[1]}: ${issue}`;
-            return `record_verification_focus ${row.id}: ${issue} — behavior targets derive uiStates from record_state_ownership rows whose owner equals behaviorGroupId "${row.behaviorGroupId}"; record one for this group if missing`;
-        }
-        const state = issue.match(/uiStates\.(\d+)\.(.+)/);
-        if (state) {
-            const row = decision.stateOwnership[Number(state[1])];
-            return row
-                ? `record_state_ownership "${row.state}" (owner ${row.owner}): ${issue}`
-                : `record_state_ownership row ${state[1]}: ${issue}`;
-        }
-        const interaction = issue.match(/interactions\.(\d+)\.(.+)/);
-        if (interaction) {
-            const row = decision.dataFlows[Number(interaction[1])];
-            return row
-                ? `record_data_flow "${row.interaction}": ${issue}`
-                : `record_data_flow row ${interaction[1]}: ${issue}`;
-        }
-        const requirement = issue.match(/requirements\.(\d+)\.(.+)/);
-        if (requirement) {
-            return `record_module_placement row ${requirement[1]}: ${issue}`;
-        }
-        return issue;
-    })
-        .join("; ");
-}
 /** Read the recovery child's read-only parent decision snapshot (written by
  * the recovery continuation). Absent file → undefined (fresh plan). */
-export async function readParentDecisionSnapshot(runDir, nodeId) {
+export async function readParentDecisionSnapshot(runDir, nodeId, context) {
     const snapshotPath = path.join(runDir, nodeId, "parent-decision-snapshot.json");
     let raw;
     try {
@@ -2884,8 +1254,45 @@ export async function readParentDecisionSnapshot(runDir, nodeId) {
         throw error;
     }
     const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed.facts))
+    if (parsed.schemaVersion !== 1 || parsed.schemaId !== "frontend-plan-parent-decision-snapshot-v1" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(parsed.parentRunId) || !/^[a-f0-9]{64}$/.test(parsed.parentLedgerSha256) || !Array.isArray(parsed.facts) || parsed.facts.some(fact => !fact || typeof fact.kind !== "string" || !fact.entry || typeof fact.entry !== "object" || Array.isArray(fact.entry)))
         throw new Error(`parent decision snapshot malformed: ${snapshotPath}`);
+    delete parsed.resolvedParentRunDir;
+    if (context) {
+        const { locateDagRun, readDagRunState, readDagRunSpec } = await import("../workflows/dag/lifecycle.js");
+        const state = await readDagRunState(runDir);
+        if (state.frontendRecoveryState?.parentRunId !== parsed.parentRunId || state.frontendRecoveryState.resetRootNodeId !== "frontend-plan-pi")
+            throw new Error("parent decision snapshot recovery lineage mismatch");
+        const located = await locateDagRun(context.workspaceRoot, parsed.parentRunId);
+        if (!located)
+            throw new Error("parent decision snapshot source run unavailable");
+        const parentSpec = await readDagRunSpec(located.runDir);
+        const sourceHash = sha256OfCanonicalJson(context.sourceBinding ?? null);
+        if (parsed.sourceBindingSha256 !== sourceHash || sha256OfCanonicalJson(parentSpec.sourceBinding ?? null) !== sourceHash)
+            throw new Error("parent decision snapshot source binding mismatch");
+        const ledgerPath = path.join(located.runDir, "frontend-plan-pi", "plan-decision-facts.jsonl");
+        const rawLedger = await readFile(ledgerPath, "utf8");
+        if (createHash("sha256").update(rawLedger).digest("hex") !== parsed.parentLedgerSha256)
+            throw new Error("parent decision snapshot ledger hash mismatch");
+        const { readTypedEventStoreFromJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+        const { assembleDecisionContractFromFacts } = await import("../workflows/dag/frontend-plan-decision-contract.js");
+        const records = (await readTypedEventStoreFromJsonl(ledgerPath)).filter(record => record.phase === "committed");
+        if (records.some(record => record.payloadSha256 !== sha256OfCanonicalJson(record.fact)))
+            throw new Error("parent decision snapshot ledger payload hash mismatch");
+        const actual = assembleDecisionContractFromFacts(records.map(record => record.fact));
+        if (sha256OfCanonicalJson(assembleDecisionContractFromFacts(parsed.facts)) !== sha256OfCanonicalJson(actual))
+            throw new Error("parent decision snapshot facts differ from bound ledger");
+        const { readCurrentFrontendRepairFindings } = await import("../workflows/dag/rerun-feedback.js");
+        const feedback = await readCurrentFrontendRepairFindings(located.runDir);
+        const feedbackBinding = feedback ? { sourceNodeId: feedback.sourceNodeId, ledgerSha256: feedback.ledgerSha256, terminalEventId: feedback.terminalEventId } : undefined;
+        if (sha256OfCanonicalJson(parsed.feedbackBinding ?? null) !== sha256OfCanonicalJson(feedbackBinding ?? null) || sha256OfCanonicalJson(parsed.designFindings ?? []) !== sha256OfCanonicalJson(feedback?.verdict === "request" ? feedback.findings : []))
+            throw new Error("parent decision snapshot finding source mismatch");
+        if (parsed.parentCanonicalSha256) {
+            const canonical = await readFile(path.join(located.runDir, "contracts/frontend-implementation-contract.json"), "utf8");
+            if (createHash("sha256").update(canonical).digest("hex") !== parsed.parentCanonicalSha256)
+                throw new Error("parent canonical hash mismatch");
+        }
+        parsed.resolvedParentRunDir = located.runDir;
+    }
     return parsed;
 }
 const decisionKindToToolName = (kind) => `record_${kind.replaceAll("-", "_")}`;
@@ -2895,490 +1302,24 @@ const decisionKindToToolName = (kind) => `record_${kind.replaceAll("-", "_")}`;
  * stable per-fact callIds make retries replay receipts instead of duplicating. */
 export async function replayParentDecisionSnapshot(snapshot, tools) {
     const byName = new Map(tools.map((tool) => [tool.name, tool]));
-    for (const [index, fact] of snapshot.facts.entries()) {
-        const toolName = decisionKindToToolName(fact.kind);
-        const tool = byName.get(toolName);
-        if (!tool) {
-            throw new Error(`parent decision replay: no tool for fact kind "${fact.kind}"`);
-        }
-        const receipt = await tool.execute(`parent-replay:${index}`, {
-            entry: fact.entry,
-        });
-        if (receipt.details?.ok !== true) {
-            throw new Error(`parent decision replay failed for ${toolName} (identity ${JSON.stringify(fact.entry.purpose ??
-                fact.entry.state ??
-                fact.entry.interaction ??
-                fact.entry.id ??
-                fact.entry.boundary ??
-                "?")}): ${receipt.details?.error ?? "unknown error"}`);
-        }
-    }
-}
-export async function createFrontendPlanDecisionTools(input) {
-    const [{ Type }, { defineTool }, { assembleDecisionContractFromFacts, assembleExperimentPlanContract, buildFrontendPlanRelationshipPatch }] = await Promise.all([
-        import("typebox"),
-        import("@earendil-works/pi-coding-agent"),
-        import("../workflows/dag/frontend-plan-decision-contract.js"),
-    ]);
-    const { readCommittedEvents } = await import("../workflows/dag/frontend-typed-event-store.js");
-    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
-    const { createDurableFrontendTools } = await import("../workflows/dag/frontend-durable-tools.js");
-    let store = input.store;
-    const { attemptId, authority } = input;
-    const optionalStringArray = Type.Optional(Type.Array(Type.String({ minLength: 1 })));
-    const optionalString = Type.Optional(Type.String({ minLength: 1 }));
-    // In-session pre-validation of the derived relationship patch. The
-    // post-session bridge runs the identical analysis; running it first inside
-    // finalize_decision turns findings into a bounded in-session correction
-    // (fix facts, finalize again) instead of an attempt burn. Skipped when the
-    // caller does not supply the runtime skeleton/sourceBinding.
-    let requiredDeliverablesCache;
-    const prevalidateDerivedPatch = async () => {
-        if (!input.skeleton || !input.sourceBinding)
-            return { ok: true, canonicalSha256: "", canonical: {} };
-        const committed = readCommittedEvents(store, attemptId);
-        const decision = assembleDecisionContractFromFacts(committed.map(record => record.fact));
-        requiredDeliverablesCache ??= (async () => {
-            const map = new Map();
-            try {
-                const { readTypedEventStoreFromJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
-                const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
-                for (const record of [...contractRecords].reverse()) {
-                    const fact = record.fact;
-                    if (!fact || fact.origin !== "contract" || fact.kind !== "required-deliverables")
-                        continue;
-                    for (const item of Array.isArray(fact.items) ? fact.items : []) {
-                        if (!item || typeof item !== "object" || Array.isArray(item))
-                            continue;
-                        const requirementId = item.requirementId;
-                        const file = item.path;
-                        if (typeof requirementId !== "string" || typeof file !== "string")
-                            continue;
-                        const paths = map.get(requirementId) ?? [];
-                        paths.push(file);
-                        map.set(requirementId, paths);
-                    }
-                    break;
-                }
-            }
-            catch {
-                // Missing/unreadable contract ledger → no deliverable obligations.
-            }
-            return map;
-        })();
-        const concreteWriteSet = [
-            ...new Set([
-                ...decision.modulePlacements.flatMap(item => item.paths),
-                ...decision.verificationFocus.map(item => item.file),
-            ]),
-        ];
-        const { applyFrontendContractMergePatch, analyzeFrontendPlanPatchCandidate, FrontendContractFailure, PlanPolicyPrecheckFailure, serializeDeterministicJson, } = await import("../workflows/dag/frontend-implementation-contract.js");
-        try {
-            const patch = buildFrontendPlanRelationshipPatch({
-                decision,
-                authority,
-                concreteWriteSet,
-                requiredDeliverables: await requiredDeliverablesCache,
-            });
-            const merged = applyFrontendContractMergePatch(input.skeleton, patch);
-            const analysis = await analyzeFrontendPlanPatchCandidate({
-                runDir: input.runDir,
-                rawContractText: serializeDeterministicJson(merged),
-                sourceBinding: input.sourceBinding,
-            });
-            return {
-                ok: true,
-                canonicalSha256: createHash("sha256")
-                    .update(serializeDeterministicJson(analysis.canonical))
-                    .digest("hex"),
-                canonical: analysis.canonical,
-            };
-        }
-        catch (error) {
-            if (error instanceof PlanPolicyPrecheckFailure) {
-                // Template the fix: every uncovered interaction/state maps to a
-                // fill-in record_reuse_decision row (the decision channel's
-                // component-choice tool).
-                const suggestions = error.findings
-                    .filter(finding => finding.code === "ui-design-coverage-missing" && finding.path)
-                    .map(finding => ({
-                    tool: "record_reuse_decision",
-                    args: {
-                        entry: {
-                            symbol: "<name the existing or new component>",
-                            decision: "reuse-existing",
-                            evidence: ["<existing repo file that proves this reuse>"],
-                            purpose: finding.path,
-                        },
-                    },
-                }));
-                const suggestionBlock = suggestions.length > 0
-                    ? ` Suggested record_* calls (copy, fill component, submit): ${JSON.stringify(suggestions)}`
-                    : "";
-                return {
-                    ok: false,
-                    error: `finalize_decision pre-validation failed (fix the listed plan facts, then call finalize_decision again): ${error.message}${suggestionBlock}`,
-                };
-            }
-            // FrontendContractFailure messages carry zod issue paths and are
-            // translated into record_* vocabulary; the bridge compiler throws
-            // decision-state-unbindable / decision-styling-strategy-conflict
-            // diagnostics that are already model-fixable as written.
-            const message = error instanceof Error ? error.message : String(error);
-            const translated = error instanceof FrontendContractFailure
-                ? translateDecisionPatchFindings(message, decision)
-                : message;
-            return {
-                ok: false,
-                error: `finalize_decision pre-validation failed (fix the listed facts with the named record_* tools — resubmit a corrected row with the same identity and replace:true to replace it — then call finalize_decision again): ${translated}`,
-            };
-        }
-    };
-    const planToolReceipt = (details) => ({
-        content: [{ type: "text", text: JSON.stringify(details) }],
-        details,
-    });
-    async function adoptDecisionFact(kind, requestId, fact) {
-        try {
-            const staged = stageTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-            });
-            const committed = await adoptTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-                eventId: staged.eventId,
-                expectedRevision: store.revision,
-            });
-            return { ok: true, kind, eventId: committed.eventId, revision: committed.revision, error: "" };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                kind,
-                code: error?.code,
-                error: error instanceof Error ? error.message : String(error),
-            };
-        }
-    }
-    const record = (name, label, description, entrySchema, gate) => defineTool({
-        name,
-        label,
-        description,
-        promptSnippet: `Record ${label}.`,
-        parameters: Type.Object({ entry: entrySchema }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const entry = params?.entry;
-            const kind = name.replace("record_", "").replace(/_/g, "-");
-            if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-                return planToolReceipt({ ok: false, kind, error: `${name} requires a non-empty entry object` });
-            }
-            if (gate) {
-                const rejected = await gate(entry);
-                if (rejected)
-                    return rejected;
-            }
-            const result = await adoptDecisionFact(kind, `${attemptId}:${name}:${randomUUID()}`, { kind, origin: "plan", entry });
-            return planToolReceipt(result);
-        },
-    });
-    const recordModulePlacementTool = record("record_module_placement", "module placement", "Record one module placement: which behavior-group/module id maps to which concrete files. Example: {\"entry\": {\"id\": \"page\", \"paths\": [\"src/page.tsx\"]}}", Type.Object({ id: Type.String({ minLength: 1 }), paths: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }) }, { additionalProperties: false }));
-    const recordReuseDecisionTool = record("record_reuse_decision", "reuse decision", "Record one component decision: which component serves which UI state/interaction (purpose). decision \"reuse-existing\" = an existing repo component (evidence[0] = the repo file that proves it); \"specified\" = the frontend spec mandates it; \"new\" = the task source mandates a bounded addition — specified/new require specSection naming the spec/task-source declaration they implement (e.g. an AC id). Set stylingStrategy once (on the first call) when the task mandates a style contract. Resubmit the same purpose with replace:true to correct a row. Example: {\"entry\": {\"symbol\": \"Spinner\", \"decision\": \"reuse-existing\", \"evidence\": [\"src/ui/Spinner.tsx\"], \"purpose\": \"loading\"}} or {\"entry\": {\"symbol\": \"SmokeCounter\", \"decision\": \"new\", \"evidence\": [\"需求.md\"], \"purpose\": \"increment\", \"specSection\": \"AC-FE-002\", \"stylingStrategy\": \"compact, stable, animation-free single card\"}}", Type.Object({
-        symbol: Type.String({ minLength: 1 }),
-        decision: Type.Union([Type.Literal("specified"), Type.Literal("reuse-existing"), Type.Literal("new")]),
-        evidence: Type.Array(Type.String()),
-        specSection: Type.Optional(Type.String({ minLength: 1 })),
-        purpose: Type.String({ minLength: 1 }),
-        covers: optionalStringArray,
-        rationale: optionalString,
-        stylingStrategy: optionalString,
-    }, { additionalProperties: false }), async (entry) => {
-        // specified/new compile into a canonical specReference whose .section
-        // the contract schema mandates; without the section the row can only
-        // fail at finalize, so demand it here where the model can still act.
-        if (entry.decision === "specified") {
-            const evidenceList = Array.isArray(entry.evidence) ? entry.evidence : [];
-            const evidencePath = typeof evidenceList[0] === "string" ? evidenceList[0] : "";
-            const candidates = input.componentSpecCandidatePaths ?? [];
-            if (candidates.length === 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "reuse-decision",
-                    error: `record_reuse_decision specified-requires-spec-candidates: decision "specified" means a declared component spec mandates this choice, but this task declares no component spec candidates — use decision "new" (task-source-mandated addition, evidence[0] = the task-source file) or "reuse-existing"`,
-                });
-            }
-            if (evidencePath && !candidates.includes(evidencePath)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "reuse-decision",
-                    error: `record_reuse_decision specified-spec-reference-outside-candidates: evidence[0] "${evidencePath}" is not a declared component spec candidate; declared candidates: [${candidates.join(", ")}]`,
-                });
-            }
-        }
-        if ((entry.decision === "specified" || entry.decision === "new") &&
-            !(typeof entry.specSection === "string" && entry.specSection.trim())) {
-            return planToolReceipt({
-                ok: false,
-                kind: "reuse-decision",
-                error: `record_reuse_decision spec-section-required: decision "${entry.decision}" must name the spec/task-source declaration it implements via specSection (e.g. an AC id); use decision "reuse-existing" for existing repo conventions. Example: {"entry": {"symbol": "SmokeCounter", "decision": "new", "evidence": ["src/components/SmokeCounter.tsx"], "purpose": "render the counter card", "specSection": "AC-FE-001"}}`,
-            });
-        }
-        return undefined;
-    });
-    const recordStateOwnershipTool = record("record_state_ownership", "state ownership", "Record one UI state and its owner, applicability and expected behavior. owner must equal the behaviorGroupId of the record_verification_focus entries it supports; every behavior group referenced by a verification focus needs at least one state row or finalize fails. Resubmit the same state name with replace:true to correct a row. Example: {\"entry\": {\"state\": \"loading\", \"owner\": \"page\", \"applicable\": true, \"expectedBehavior\": \"render loading\"}}", Type.Object({
-        state: Type.String({ minLength: 1 }),
-        owner: Type.String({ minLength: 1 }),
-        applicable: Type.Boolean(),
-        expectedBehavior: optionalString,
-        notApplicableReason: optionalString,
-    }, { additionalProperties: false }));
-    const frozenInteractionIds = authority.interactionIds ?? [];
-    const recordDataFlowTool = record("record_data_flow", "data flow", "Record one interaction data flow: source behavior group, trigger and expected behavior. One row per interaction name; resubmit the same interaction name to replace it. When a frozen interaction id vocabulary is declared, the interaction name MUST be one of the declared ids — wrong-named records are rejected at submission and stale ones are retracted via retract_data_flow. Example: {\"entry\": {\"interaction\": \"load\", \"source\": \"page\", \"trigger\": \"submit query\", \"expectedBehavior\": \"show loading then results\"}}", Type.Object({
-        interaction: Type.String({ minLength: 1 }),
-        source: Type.String({ minLength: 1 }),
-        trigger: Type.String({ minLength: 1 }),
-        expectedBehavior: Type.String({ minLength: 1 }),
-    }, { additionalProperties: false }), frozenInteractionIds.length > 0
-        ? async (entry) => {
-            const name = typeof entry.interaction === "string" ? entry.interaction : "";
-            if (name && !frozenInteractionIds.includes(name)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "data-flow",
-                    code: "INTERACTION_ID_NOT_DECLARED",
-                    error: `interaction "${name}" is not in the frozen vocabulary; allowed: [${frozenInteractionIds.join(", ")}]. Submit the declared id. To remove an already-recorded wrong interaction, call retract_data_flow with {"interaction": "${name}"}.`,
-                });
-            }
-            return undefined;
-        }
-        : undefined);
-    const retractDataFlowTool = defineTool({
-        name: "retract_data_flow",
-        label: "retract data flow",
-        description: "Retract a previously recorded interaction data flow (e.g. one recorded under a wrong interaction id). The retracted record and every fact keyed to that interaction name stop participating in the compiled plan. Declared vocabulary ids cannot be retracted. Example: {\"interaction\": \"increment-counter\", \"reason\": \"recorded under a wrong id\"}",
-        promptSnippet: "Retract one interaction data flow by interaction name.",
-        parameters: Type.Object({
-            interaction: Type.String({ minLength: 1 }),
-            reason: Type.Optional(Type.String({ minLength: 1 })),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const interaction = typeof params?.interaction === "string" ? params.interaction : "";
-            if (!interaction) {
-                return planToolReceipt({ ok: false, kind: "data-flow", error: "retract_data_flow requires a non-empty interaction" });
-            }
-            if (frozenInteractionIds.includes(interaction)) {
-                return planToolReceipt({ ok: false, kind: "data-flow", error: `interaction "${interaction}" is a declared vocabulary id and cannot be retracted` });
-            }
-            const result = await adoptDecisionFact("data-flow", `${attemptId}:retract_data_flow:${randomUUID()}`, { kind: "data-flow", origin: "plan", entry: { interaction, retracted: true, ...(typeof params?.reason === "string" ? { reason: params.reason } : {}) } });
-            return planToolReceipt(result);
-        },
-    });
-    const recordApiMockBoundaryTool = record("record_api_mock_boundary", "API/Mock boundary", "Record one API boundary and its mode (real/mock/not-needed) with evidence. The boundary is the stable identity: resubmit the same boundary with replace:true to change its mode (e.g. mock→real); the old decision is replaced, not appended. Real/mock endpoints require fixture (the test fixture path) and consumer (the implementation file that calls the API) — design policy rejects endpoints without them. Example: {\"entry\": {\"boundary\": \"GET /items\", \"mode\": \"mock\", \"evidence\": \"fixture only\", \"fixture\": \"test/fixtures/items.ts\", \"consumer\": \"src/page.tsx\"}}", Type.Object({
-        boundary: Type.String({ minLength: 1 }),
-        mode: Type.Union([Type.Literal("real"), Type.Literal("mock"), Type.Literal("not-needed")]),
-        evidence: Type.String({ minLength: 1 }),
-        fixture: optionalString,
-        consumer: optionalString,
-    }, { additionalProperties: false }), async (entry) => {
-        // Design policy hard-requires fixture + consumer on every derived
-        // endpoint (non-not-needed strategies); demand them here where the
-        // model can still act instead of failing the compile post-session.
-        if ((entry.mode === "real" || entry.mode === "mock") &&
-            (!(typeof entry.fixture === "string" && entry.fixture.trim()) ||
-                !(typeof entry.consumer === "string" && entry.consumer.trim()))) {
-            return planToolReceipt({
-                ok: false,
-                kind: "api-mock-boundary",
-                error: `record_api_mock_boundary fixture-and-consumer-required: ${entry.mode} boundary "${entry.boundary}" needs fixture (the test fixture path) and consumer (the implementation file that calls the API). Example: {"entry": {"boundary": "${entry.boundary}", "mode": "${entry.mode}", "evidence": "<why>", "fixture": "test/fixtures/items.ts", "consumer": "src/page.tsx"}}`,
-            });
-        }
-        return undefined;
-    });
-    const recordVerificationFocusTool = record("record_verification_focus", "verification focus", "Record one behavior-group verification focus: which test file/command proves which behavior group at what evidence level. Every behaviorGroupId must have at least one record_state_ownership row whose owner equals it — declare one UI state per behavior group before finalizing. Example: {\"entry\": {\"id\": \"VT-1\", \"behaviorGroupId\": \"page\", \"file\": \"test/page.test.tsx\", \"commandId\": \"test\", \"evidenceLevel\": \"mounted\"}}", Type.Object({
-        id: Type.String({ minLength: 1 }),
-        behaviorGroupId: Type.String({ minLength: 1 }),
-        file: Type.String({ minLength: 1 }),
-        commandId: Type.String({ minLength: 1 }),
-        evidenceLevel: Type.Union([Type.Literal("unit"), Type.Literal("mounted"), Type.Literal("real-integration")]),
-        boundary: optionalString,
-    }, { additionalProperties: false }), async (entry) => {
-        // Mirror the relationship record_plan_verification_target boundary so
-        // protocol errors surface in-node (bounded correction) instead of
-        // burning attempts on an immutable committed fact that finalize rejects.
-        // Duplicate/identity enforcement lives in the durable wrapper (FACT_IDENTITY_CONFLICT
-        // unless replace:true) and the compile collapses same-id records to the
-        // latest replacement, so no duplicate gate is needed here.
-        const verificationCommandId = typeof entry.commandId === "string" ? entry.commandId.trim() : "";
-        if (!verificationCommandId) {
-            return planToolReceipt({
-                ok: false,
-                kind: "verification-focus",
-                error: `record_verification_focus entry.commandId is required (received ${JSON.stringify(entry.commandId ?? null)}); pick one id from the frozen command directory in your prompt`,
-            });
-        }
-        const { deriveFrontendVerifyCommandDirectoryFromRun, isFrontendTestFilePath } = await import("../workflows/dag/frontend-implementation-contract.js");
-        const verifyDirectory = await deriveFrontendVerifyCommandDirectoryFromRun(input.runDir);
-        if (verifyDirectory.length > 0) {
-            const directoryEntry = verifyDirectory.find((candidate) => candidate.commandId === verificationCommandId);
-            if (!directoryEntry) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "verification-focus",
-                    error: `record_verification_focus verification-target-unknown-command: unknown commandId "${verificationCommandId}"; available frozen commands: [${verifyDirectory.map((candidate) => `${candidate.commandId} (${candidate.mode}: ${candidate.label})`).join(", ")}]`,
-                });
-            }
-            if (directoryEntry.mode === "behavior" &&
-                typeof entry.file === "string" &&
-                !isFrontendTestFilePath(entry.file)) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "verification-focus",
-                    error: `record_verification_focus verification-target-phase-mismatch: behavior command "${directoryEntry.label}" (${directoryEntry.commandId}) must bind a test file (__tests__/, tests?/, e2e/, cypress/, *.test.*, *.spec.*, *.cy.*); received file "${entry.file}"`,
-                });
-            }
+    for (const [index, fact] of snapshot.facts.entries()) {
+        const toolName = decisionKindToToolName(fact.kind);
+        const tool = byName.get(toolName);
+        if (!tool) {
+            throw new Error(`parent decision replay: no tool for fact kind "${fact.kind}"`);
         }
-        // A behavior verification target derives its contract uiStates solely
-        // from the committed state-ownership rows whose owner equals its
-        // behaviorGroupId, and the relationship patch rejects a behavior
-        // target with empty uiStates whenever the plan declares any state or
-        // interaction. That rejection currently surfaces only in the
-        // post-session bridge and burns the whole attempt, so enforce the
-        // pairing here as a bounded in-session correction. A ledger with no
-        // ownership and no data-flow facts stays exempt (pure-logic plan),
-        // mirroring the contract-level exemption.
-        const committedLedger = readCommittedEvents(store, attemptId);
-        const ownershipRows = committedLedger.filter((event) => event.fact.kind === "state-ownership");
-        const hasInteractionFacts = committedLedger.some((event) => event.fact.kind === "data-flow");
-        if ((ownershipRows.length > 0 || hasInteractionFacts) &&
-            !ownershipRows.some((event) => event.fact.entry?.owner ===
-                entry.behaviorGroupId)) {
-            return planToolReceipt({
-                ok: false,
-                kind: "verification-focus",
-                error: `record_verification_focus undeclared-behavior-group-state: behavior group "${entry.behaviorGroupId}" (verification target ${entry.id}) has no record_state_ownership row; finalize derives each behavior target's UI states from ownership rows whose owner equals the behaviorGroupId, so record at least one for this group: {"state": "<name>", "owner": "${entry.behaviorGroupId}", "applicable": true, "expectedBehavior": "<what the state does>"}`,
-            });
+        const receipt = await tool.execute(`parent-replay:${index}`, {
+            entry: fact.entry,
+        });
+        if (receipt.details?.ok !== true) {
+            throw new Error(`parent decision replay failed for ${toolName} (identity ${JSON.stringify(fact.entry.purpose ??
+                fact.entry.state ??
+                fact.entry.interaction ??
+                fact.entry.id ??
+                fact.entry.boundary ??
+                "?")}): ${receipt.details?.error ?? "unknown error"}`);
         }
-        return undefined;
-    });
-    const recordDependencyTool = record("record_dependency", "dependency", "Record one dependency name. Example: {\"entry\": {\"name\": \"none\"}}", Type.Object({ name: Type.String({ minLength: 1 }) }, { additionalProperties: false }));
-    const finalizeDecisionTool = defineTool({
-        name: "finalize_decision",
-        label: "finalize_decision",
-        description: "Compile the committed decision facts into a decision contract, pre-validate the derived canonical contract, and commit the terminal. Fails closed on any safety finding or validation finding; correct the reported record_* facts and call finalize_decision again.",
-        promptSnippet: "Compile and finalize the committed decision facts.",
-        parameters: Type.Object({}, { additionalProperties: false }),
-        async execute(_toolCallId) {
-            const committed = readCommittedEvents(store, attemptId);
-            const decision = assembleDecisionContractFromFacts(committed.map(record => record.fact));
-            const expectedWriteSet = [
-                ...decision.modulePlacements.flatMap(item => item.paths),
-                ...decision.verificationFocus.map(item => item.file),
-            ];
-            const derived = assembleExperimentPlanContract({
-                decision,
-                authority,
-                concreteWriteSet: expectedWriteSet,
-            });
-            if (derived.findings.length > 0) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "finalize_decision",
-                    code: "DECISION_SAFETY_FINDINGS",
-                    error: `decision safety projection failed: ${derived.findings.join("; ")}`,
-                });
-            }
-            const prevalidation = await prevalidateDerivedPatch();
-            if (!prevalidation.ok) {
-                return planToolReceipt({
-                    ok: false,
-                    kind: "finalize_decision",
-                    code: "DECISION_PREVALIDATION_FAILED",
-                    error: prevalidation.error,
-                });
-            }
-            // Recovery-mode guard: a repair child that finalizes a plan identical
-            // to its parent's has not performed the repair the findings demand —
-            // the identical plan is exactly what admission rejected. Both hashes
-            // use the same deterministic serializer over the canonical contract,
-            // so only a real semantic change passes.
-            // Recovery-mode guard: a repair child must demonstrably close the
-            // parent findings before the run re-enters design review.
-            if (input.parentDecisionSnapshot) {
-                const { readParentCanonical, parentCanonicalContentSha256 } = await import("../workflows/dag/frontend-implementation-contract.js");
-                const { extractRepairAssertions, evaluateRepairClosure, decisionIdentitySha256 } = await import("../workflows/dag/frontend-plan-decision-contract.js");
-                const parentRunDir = path.join(input.runDir, "..", input.parentDecisionSnapshot.parentRunId);
-                const parentCanonical = await readParentCanonical(parentRunDir);
-                // 1. identical-plan guard. Decisions, not prose: a rationale-only
-                // rewrite is not a repair (smoke r27 cleared a raw byte-hash guard
-                // by editing two rationale strings and changing nothing else). The
-                // byte hash stays as the fallback when the parent canonical cannot
-                // be read.
-                const parentSha = await parentCanonicalContentSha256(parentRunDir);
-                const parentDecisions = parentCanonical
-                    ? decisionIdentitySha256(parentCanonical)
-                    : undefined;
-                const childDecisions = decisionIdentitySha256(prevalidation.canonical);
-                if (parentDecisions
-                    ? parentDecisions === childDecisions
-                    : parentSha !== undefined && parentSha === prevalidation.canonicalSha256) {
-                    return planToolReceipt({
-                        ok: false,
-                        kind: "finalize_decision",
-                        code: "DECISION_REPAIR_NO_CHANGE",
-                        error: "recovery finalize blocked: every structured decision row is identical to the parent run's (rationale-only edits do not count as a repair), but the review findings require changes. Correct the flagged rows (same identity, replace:true), then call finalize_decision again.",
-                    });
-                }
-                // 2. per-finding closure: every deterministic assertion extracted
-                // from the parent findings must hold on the child canonical.
-                const findings = input.parentDecisionSnapshot.designFindings ?? [];
-                if (parentCanonical && findings.length > 0) {
-                    const assertions = extractRepairAssertions(findings, parentCanonical);
-                    const closure = evaluateRepairClosure(assertions, prevalidation.canonical, parentCanonical);
-                    if (!closure.closed) {
-                        return planToolReceipt({
-                            ok: false,
-                            kind: "finalize_decision",
-                            code: "DECISION_REPAIR_NOT_CLOSED",
-                            error: `recovery finalize blocked: ${closure.unmet.length} finding(s) are still not closed — ${closure.unmet.join("; ")}. Correct the flagged rows (same identity, replace:true), then call finalize_decision again.`,
-                        });
-                    }
-                }
-            }
-            const result = await adoptDecisionFact("finalize_decision", `${attemptId}:finalize_decision:${randomUUID()}`, { kind: "finalize_decision", origin: "plan", findings: [] });
-            return planToolReceipt(result);
-        },
-    });
-    const durable = await createDurableFrontendTools({
-        file: path.join(input.runDir, input.nodeId, "plan-decision-facts.jsonl"),
-        attemptId,
-        store: input.store,
-        setWorkingStore: next => { store = next; },
-        binding: { authority },
-        tools: [
-            recordModulePlacementTool,
-            recordReuseDecisionTool,
-            recordStateOwnershipTool,
-            recordDataFlowTool,
-            retractDataFlowTool,
-            recordApiMockBoundaryTool,
-            recordVerificationFocusTool,
-            recordDependencyTool,
-            finalizeDecisionTool,
-        ],
-    });
-    const durableFinalizeDecisionTool = durable.customTools.find((tool) => typeof tool === "object" && tool !== null && tool.name === "finalize_decision");
-    if (!durableFinalizeDecisionTool)
-        throw new Error("frontend plan decision durable finalize tool unavailable");
-    return {
-        customTools: durable.customTools,
-        flush: durable.flush,
-        committedFacts: () => readCommittedEvents(store, attemptId),
-        finalizeDecision: () => durableFinalizeDecisionTool.execute(`${attemptId}:auto-finalize-decision`, {}, undefined, undefined, {}),
-    };
+    }
 }
 /**
  * Decision → relationship bridge: after a successful decision `finalize`
@@ -3396,606 +1337,97 @@ export async function createFrontendPlanDecisionTools(input) {
  * the exact validation the relationship finalize receipt runs (merge onto the
  * runtime skeleton + analyzeFrontendPlanPatchCandidate). When the derived
  * canonical fails, this returns a fixable error and the executor turns it into
- * an invalid-output so the node retry ladder restarts the session with the
- * diagnostics instead of writing a ledger that R1 would reject.
- */
-export async function bridgeFrontendPlanDecisionToRelationshipLedger(input) {
-    const { assembleDecisionContractFromFacts, buildFrontendPlanRelationshipPatch, } = await import("../workflows/dag/frontend-plan-decision-contract.js");
-    const committed = input.facts
-        .filter(record => record.phase === "committed")
-        .map(record => record.fact);
-    const decision = assembleDecisionContractFromFacts(committed);
-    const concreteWriteSet = [
-        ...new Set([
-            ...decision.modulePlacements.flatMap(item => item.paths),
-            ...decision.verificationFocus.map(item => item.file),
-        ]),
-    ];
-    // Contract-declared deliverable obligations (the same ledger the analyzer
-    // extracts `requiredDeliverables` from): bind each path to its requirement
-    // so the derived canonical contract plans every contract-mandated file.
-    const requiredDeliverables = new Map();
-    try {
-        const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
-        for (const record of [...contractRecords].reverse()) {
-            const fact = record.fact;
-            if (!fact || fact.origin !== "contract" || fact.kind !== "required-deliverables")
-                continue;
-            for (const item of Array.isArray(fact.items) ? fact.items : []) {
-                if (!item || typeof item !== "object" || Array.isArray(item))
-                    continue;
-                const requirementId = item.requirementId;
-                const file = item.path;
-                if (typeof requirementId !== "string" || typeof file !== "string")
-                    continue;
-                const paths = requiredDeliverables.get(requirementId) ?? [];
-                paths.push(file);
-                requiredDeliverables.set(requirementId, paths);
-            }
-            break;
-        }
-    }
-    catch {
-        // Missing/unreadable contract ledger → no deliverable obligations to merge.
-    }
-    if (!input.skeleton || !input.sourceBinding) {
-        return { ok: false, error: "frontend decision bridge requires the runtime skeleton and sourceBinding" };
-    }
-    let patch;
-    try {
-        const { analyzeFrontendPlanPatchCandidate, applyFrontendContractMergePatch, serializeDeterministicJson, } = await import("../workflows/dag/frontend-implementation-contract.js");
-        patch = buildFrontendPlanRelationshipPatch({
-            decision,
-            authority: input.authority,
-            concreteWriteSet,
-            requiredDeliverables,
-        });
-        const merged = applyFrontendContractMergePatch(input.skeleton, patch);
-        await analyzeFrontendPlanPatchCandidate({
-            runDir: input.runDir,
-            rawContractText: serializeDeterministicJson(merged),
-            sourceBinding: input.sourceBinding,
-        });
-    }
-    catch (error) {
-        const raw = error instanceof Error ? error.message : String(error);
-        return {
-            ok: false,
-            // This path should be rare now that finalize_decision pre-validates
-            // the same patch in-session; keep the retry-prompt diagnostics in
-            // decision-channel vocabulary regardless.
-            error: `frontend decision → relationship patch failed pre-validation (correct the reported decision facts, then the retry ladder restarts the session): ${translateDecisionPatchFindings(raw, decision)}`,
-        };
-    }
-    const { createTypedEventStore, stageTypedEventRecord, commitTypedEventRecord, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
-    const file = path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl");
-    const store = createTypedEventStore();
-    const adopt = (kind, patchValue, revision) => {
-        const eventId = `decision-bridge:${input.attemptId}:${kind}`;
-        const fact = { kind, origin: "plan", patch: patchValue };
-        stageTypedEventRecord(store, {
-            eventId,
-            requestId: eventId,
-            attemptId: input.attemptId,
-            fact,
-        });
-        return commitTypedEventRecord(store, eventId, revision);
-    };
-    adopt("target-surface", patch, 1);
-    adopt("finalize_plan", patch, 2);
-    // The ledger is derived wholesale from the committed decision facts, so a
-    // re-run rewrites it atomically (no incremental append semantics needed).
-    await writeTypedEventStoreJsonl(file, store.records.filter(record => record.phase === "committed"));
-    return { ok: true, patch };
-}
-function isRecordObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** A contract fact is source-mapped when it carries a non-empty `sourceSpan`
- * (object or string), a non-empty `sourceRefs` array, or a non-empty `source`
- * string. Anything else is an unmapped source segment (AC-001). */
-function contractFactSourceSpan(fact) {
-    if (isRecordObject(fact.sourceSpan) || typeof fact.sourceSpan === "string") {
-        return fact.sourceSpan;
-    }
-    if (Array.isArray(fact.sourceRefs) && fact.sourceRefs.length > 0) {
-        return fact.sourceRefs;
-    }
-    if (Array.isArray(fact.sourceFragmentIds) &&
-        fact.sourceFragmentIds.some((value) => typeof value === "string" && value.trim().length > 0)) {
-        return fact.sourceFragmentIds;
-    }
-    if (typeof fact.source === "string" && fact.source.trim().length > 0) {
-        return fact.source;
-    }
-    return undefined;
-}
-/**
- * A+B (AC-001): deterministically assemble the read-only `frontend-task-contract-vNext`
- * audit artifact from committed contract facts. It never rewrites the original
- * task source: unmapped requirement/constraint segments are listed explicitly
- * so Plan/Implement/Review keep binding to the raw source, not the model's
- * summarized contract. The blocked disposition is projected through the frozen
- * `mapContractBlockedOwner` mapping (AC-002).
- */
-export function buildFrontendTaskContractVNext(records) {
-    const facts = records
-        .filter((record) => record.phase === "committed")
-        .map((record) => record.fact)
-        .filter(isRecordObject);
-    const finalized = facts.find((fact) => fact.kind === "contract-finalized");
-    const disposition = typeof finalized?.disposition === "string" ? finalized.disposition : null;
-    const blockingOwner = typeof finalized?.blockingOwner === "string"
-        ? finalized.blockingOwner
-        : null;
-    const projected = mapContractBlockedOwner({
-        disposition: disposition ?? "",
-        blockingOwner: blockingOwner ?? undefined,
-    });
-    const byKind = (kind) => facts.filter((fact) => fact.kind === kind);
-    const requirements = byKind("requirement");
-    const unmappedSourceSegments = requirements
-        .filter((fact) => contractFactSourceSpan(fact) === undefined)
-        .map((fact) => ({
-        kind: "requirement",
-        id: typeof fact.id === "string"
-            ? fact.id
-            : typeof fact.text === "string"
-                ? fact.text
-                : undefined,
-    }))
-        .filter((segment) => segment.id !== undefined);
-    return {
-        schemaVersion: 1,
-        schemaId: "frontend-task-contract-vNext",
-        disposition,
-        blockingOwner,
-        blockedOwner: projected === "not-blocked" ? null : projected,
-        requirements,
-        constraints: byKind("constraint"),
-        evidenceExpectations: byKind("evidence-expectation"),
-        deliverableDeclarations: byKind("required-deliverables").at(-1)?.items ?? [],
-        handoffIntents: byKind("handoff-intent"),
-        openQuestions: byKind("open-question"),
-        splitProposals: byKind("split-proposal"),
-        unmappedSourceSegments,
-    };
-}
-/**
- * A+B: `frontend-contract-pi` incremental contract tools. The `record_*` tools
- * commit origin=contract facts and `finalize_contract` commits the terminal
- * disposition (ready | ready-with-assumptions | blocked + blockingOwner).
- */
-export async function createFrontendContractTools(input) {
-    const [{ Type }, { defineTool }] = await Promise.all([
-        import("typebox"),
-        import("@earendil-works/pi-coding-agent"),
-    ]);
-    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
-    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
-    let store = input.store;
-    const attemptId = input.attemptId;
-    let activeScope = null;
-    const committedRequirementIds = () => new Set(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "requirement").map(r => String(r.fact.id)));
-    const completedScopeRequirementIds = () => new Set(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "contract-scope-completed").flatMap(r => Array.isArray(r.fact.requirementIds) ? r.fact.requirementIds.filter((id) => typeof id === "string") : []));
-    const receipt = (details) => ({
-        content: [{ type: "text", text: JSON.stringify(details) }],
-        details,
-    });
-    async function adoptContractFact(kind, fact) {
-        try {
-            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
-            const staged = stageTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-            });
-            const committed = await adoptTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-                eventId: staged.eventId,
-                expectedRevision: store.revision,
-            });
-            return {
-                ok: true,
-                kind,
-                eventId: committed.eventId,
-                revision: committed.revision,
-                error: "",
-            };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                kind,
-                code: error?.code,
-                error: error instanceof Error ? error.message : String(error),
-            };
-        }
-    }
-    const recordKinds = {
-        record_constraint: "constraint",
-        record_handoff_intent: "handoff-intent",
-        record_open_question: "open-question",
-        record_split_proposal: "split-proposal",
-    };
-    const recordTools = Object.entries(recordKinds).map(([name, kind]) => defineTool({
-        name,
-        label: name,
-        description: `Commit an origin=contract ${kind} fact. IMPORTANT: submit incrementally — batch up to 5 record_* calls per message, starting from the FIRST message; never attempt to emit the whole contract in one response (a single large dump will be truncated and rejected). Every message must make progress by committing at least one record_* fact.`,
-        promptSnippet: `Commit 1-5 origin=contract ${kind} facts (up to 5 per message).`,
-        parameters: Type.Object({
-            text: Type.String({ minLength: 1 }),
-            requirementIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-            sourceFragmentIds: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-            ...(kind === "constraint" ? { category: Type.Optional(Type.Enum({ constraint: "constraint", "non-goal": "non-goal", risk: "risk" })) } : {}),
-            ...(kind === "handoff-intent" ? { taskKind: Type.Literal("frontend-test"), blocking: Type.Optional(Type.Boolean()) } : {}),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const data = params;
-            if (!data.text?.trim())
-                return receipt({ ok: false, code: "TOOL_SCHEMA_INVALID", error: `${name}: text must be non-empty` });
-            const knownFragments = new Set([...(input.canonicalRequirements?.values() ?? [])].flatMap(r => r.sourceFragmentIds));
-            if (data.requirementIds?.some(id => !input.canonicalRequirements?.has(id)) || data.sourceFragmentIds?.some(id => !knownFragments.has(id)))
-                return receipt({ ok: false, code: "CONTRACT_REFERENCE_UNKNOWN", error: `${name}: reference is outside the frozen source inventory` });
-            const result = await adoptContractFact(kind, {
-                ...(params ?? {}),
-                kind,
-                origin: "contract",
-            });
-            return receipt(result);
-        },
-    }));
-    // record_requirement is runtime-owned by design: the requirement TEXT and
-    // sourceFragmentIds come from the frozen source-fidelity ledger, never from
-    // model-authored prose. The model only names the canonical id it confirms.
-    // This closes the free-shape hole (additionalProperties:true accepted
-    // `statement` rewrites and JSON-stringified `sourceFragmentIds` arrays,
-    // which then reached the planner as empty text + dead fragment bindings).
-    const recordRequirementTool = defineTool({
-        name: "record_requirement",
-        label: "record_requirement",
-        description: 'Confirm one canonical ledger requirement (origin=contract requirement fact). Pass the canonical id and optional execution:{groupId,kind,summary} only. Reuse a group only when its behavior and all permission/threshold/error conditions agree; retain separate groups for differences. Constraints/exclusions do not require invented UI. The canonical id is listed in the <frontend_contract_input> inventory, e.g. {"id": "AC-001"} — the runtime commits the authoritative text and sourceFragmentIds from the frozen ledger. Never pass text/statement/sourceFragmentIds yourself: free-form rewrites and JSON-stringified fragment arrays are rejected. IMPORTANT: batch up to 5 record_* calls per message, starting from the FIRST message.',
-        promptSnippet: "Confirm 1-5 canonical requirements by id (up to 5 per message).",
-        parameters: Type.Object({ id: Type.String({ description: "Canonical ledger requirement id (e.g. AC-001)" }), execution: Type.Optional(Type.Object({ groupId: Type.String({ minLength: 1 }), kind: Type.Union([Type.Literal("behavior"), Type.Literal("constraint"), Type.Literal("exclusion")]), summary: Type.String({ minLength: 1 }) }, { additionalProperties: false })) }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const id = typeof params?.id === "string" ? params.id.trim() : "";
-            if (!id) {
-                return receipt({
-                    ok: false,
-                    kind: "requirement",
-                    error: "record_requirement requires the canonical requirement id",
-                });
-            }
-            if (activeScope && !activeScope.has(id))
-                return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: `requirement ${id} is outside the complete input scope of this session` });
-            const canonical = input.canonicalRequirements?.get(id);
-            if (!canonical) {
-                const known = [...(input.canonicalRequirements?.keys() ?? [])];
-                return receipt({
-                    ok: false,
-                    kind: "requirement",
-                    error: `record_requirement id "${id}" is not a canonical ledger requirement; canonical ids are: ${known.join(", ") || "(none)"}`,
-                });
-            }
-            if (params.execution) {
-                try {
-                    collectFrontendExecutionGroups([...readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "requirement" && r.fact.id !== id).map(r => ({ id: String(r.fact.id), execution: r.fact.execution })), { id, execution: params.execution }]);
-                }
-                catch (error) {
-                    return receipt({ ok: false, code: "EXECUTION_GROUP_CONFLICT", error: String(error) });
-                }
-            }
-            const result = await adoptContractFact("requirement", {
-                kind: "requirement",
-                origin: "contract",
-                disposition: "explicit",
-                id,
-                text: canonical.text,
-                sourceFragmentIds: canonical.sourceFragmentIds,
-                ...(params.execution ? { execution: params.execution } : {}),
-            });
-            return receipt(result);
-        },
-    });
-    // Requirement identity/text/source are runtime-owned and seeded before the
-    // model starts. Execution grouping is still a model decision, so expose it
-    // as a small typed update instead of forcing the model to re-submit the same
-    // requirement just to attach execution metadata.
-    const recordRequirementExecutionTool = defineTool({
-        name: "record_requirement_execution",
-        label: "record_requirement_execution",
-        description: "Attach execution ownership to already-confirmed canonical requirements.",
-        promptSnippet: "Record execution group metadata for confirmed requirements.",
-        parameters: Type.Object({
-            requirementIds: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, uniqueItems: true }),
-            execution: Type.Object({
-                groupId: Type.String({ minLength: 1 }),
-                kind: Type.Union([Type.Literal("behavior"), Type.Literal("constraint"), Type.Literal("exclusion")]),
-                summary: Type.String({ minLength: 1 }),
-            }, { additionalProperties: false }),
-        }, { additionalProperties: false }),
-        async execute(callId, params) {
-            const ids = params.requirementIds;
-            if (activeScope && ids.some((id) => !activeScope?.has(id)))
-                return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "execution metadata references a requirement outside the active contract scope" });
-            const canonical = input.canonicalRequirements;
-            const unknown = ids.filter((id) => !canonical?.has(id));
-            if (unknown.length > 0)
-                return receipt({ ok: false, code: "CONTRACT_REFERENCE_UNKNOWN", error: `record_requirement_execution references unknown canonical requirements: ${unknown.join(", ")}` });
-            const execution = frontendExecutionSchema.parse(params.execution);
-            const existing = readCommittedEvents(store, attemptId)
-                .filter((record) => record.fact.kind === "requirement")
-                .map((record) => ({ id: String(record.fact.id), execution: record.fact.execution }))
-                .filter((unit) => !ids.includes(unit.id));
-            try {
-                collectFrontendExecutionGroups([...existing, ...ids.map((id) => ({ id, execution }))]);
-            }
-            catch (error) {
-                return receipt({ ok: false, code: "EXECUTION_GROUP_CONFLICT", error: error instanceof Error ? error.message : String(error) });
-            }
-            let result = { ok: true };
-            for (const id of ids) {
-                const requirement = canonical.get(id);
-                result = await adoptContractFact("requirement", { kind: "requirement", origin: "contract", disposition: "explicit", id, text: requirement.text, sourceFragmentIds: requirement.sourceFragmentIds, execution });
-                if (result.ok !== true)
-                    return receipt(result);
-            }
-            return receipt({ ...result, requestId: callId });
-        },
-    });
-    // Authoritative UI state declarations: the contract node extracts the
-    // PRD/reference UI-state table into structured facts so the planner binds
-    // uiStates to declared ids instead of inventing names (dogfood
-    // dag-1788504923861-0f7b17a9: 10 invented list-visibility variants, 0 of
-    // the 7 PRD states).
-    const recordUiStateTool = defineTool({
-        name: "record_ui_state",
-        label: "record_ui_state",
-        description: 'Declare ONE authoritative UI state extracted from the task source\'s UI-state table (origin=contract ui-state-declaration fact). Call once per declared state, exactly as the source names it: {"id": "<state id from the source table>", "trigger": "<when this state applies>", "observableOutcome": "<what the user can observe>"}. The planner must bind these ids later; do not rename or invent states.',
-        promptSnippet: "Declare 1-5 authoritative UI states (up to 5 per message).",
-        parameters: Type.Object({
-            id: Type.String({ description: "UI state id exactly as the source table declares it" }),
-            trigger: Type.String({ description: "When this state applies" }),
-            observableOutcome: Type.String({ description: "Observable result for the user" }),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const id = typeof params?.id === "string" ? params.id.trim() : "";
-            const trigger = typeof params?.trigger === "string" ? params.trigger.trim() : "";
-            const observableOutcome = typeof params?.observableOutcome === "string"
-                ? params.observableOutcome.trim()
-                : "";
-            if (!id || !trigger || !observableOutcome) {
-                return receipt({
-                    ok: false,
-                    kind: "ui-state-declaration",
-                    error: "record_ui_state requires non-empty id, trigger, and observableOutcome",
-                });
-            }
-            const result = await adoptContractFact("ui-state-declaration", {
-                kind: "ui-state-declaration",
-                origin: "contract",
-                id,
-                trigger,
-                observableOutcome,
-            });
-            return receipt(result);
-        },
-    });
-    const evidenceStatus = Type.Enum({
-        required: "required", optional: "optional", "not-applicable": "not-applicable",
-    });
-    const recordEvidenceExpectationTool = defineTool({
-        name: "record_evidence_expectation",
-        label: "record_evidence_expectation",
-        description: 'Record evidence requirements as {requirementId:"<canonical id>",evidence:{static:"required|optional|not-applicable",behavior:"required|optional|not-applicable",mock:"required|optional|not-applicable","real-integration":"required|optional|not-applicable"}}. Declare at least one lane; later calls replace only the lanes they name.',
-        parameters: Type.Object({
-            requirementId: Type.String(),
-            evidence: Type.Object({
-                static: Type.Optional(evidenceStatus),
-                behavior: Type.Optional(evidenceStatus),
-                mock: Type.Optional(evidenceStatus),
-                "real-integration": Type.Optional(evidenceStatus),
-            }, { additionalProperties: false }),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            try {
-                const fact = frontendEvidenceExpectationSchema.parse(params);
-                if (!input.canonicalRequirements?.has(fact.requirementId)) {
-                    throw new Error(`unknown canonical requirement ${fact.requirementId}`);
-                }
-                return receipt(await adoptContractFact("evidence-expectation", {
-                    kind: "evidence-expectation", origin: "contract", ...fact,
-                }));
-            }
-            catch (error) {
-                return receipt({
-                    ok: false, kind: "evidence-expectation",
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        },
-    });
-    const recordRequiredDeliverablesTool = defineTool({
-        name: "record_required_deliverables",
-        label: "record_required_deliverables",
-        description: 'Declare the complete source-required file deliverables as {items:[{path,requirementId,sourceFragmentId}]}. Interpret obligations from the original source, including lists/tables: permissions (allowedPaths/only allowed to modify), prohibitions, examples and read-only references are NOT delivery obligations. Each path must appear exactly in its frozen requirement-bound source fragment. Submit {items:[]} explicitly if no files are mandatory. Each call appends complete source-bound items; replace:true explicitly replaces the inventory. Required before finalize_contract ready.',
-        parameters: Type.Object({ replace: Type.Optional(Type.Boolean()), items: Type.Array(Type.Object({
-                path: Type.String(), requirementId: Type.String(), sourceFragmentId: Type.String(),
-            }, { additionalProperties: false })) }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            try {
-                const declaration = validateFrontendRequiredDeliverables({ items: params.items }, input.canonicalRequirements ?? new Map());
-                const previous = params.replace ? [] : readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "required-deliverables").at(-1)?.fact.items;
-                const items = [...new Map([...(Array.isArray(previous) ? previous : []), ...declaration.items].map(item => [JSON.stringify(item), item])).values()];
-                return receipt(await adoptContractFact("required-deliverables", {
-                    kind: "required-deliverables", origin: "contract", items,
-                }));
-            }
-            catch (error) {
-                return receipt({
-                    ok: false, kind: "required-deliverables",
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        },
-    });
-    // OpenSpec selection committed as individual typed facts (one path per
-    // call) so a large candidate set never exceeds a single model output
-    // budget: each tool call carries exactly one {path, disposition,
-    // rationale} row and the ledger accumulates them across calls. Only
-    // positive classifications (required | relevant) are legal; unmentioned
-    // candidates default to irrelevant at the prewrite gate.
-    const recordOpenspecSelectionTool = defineTool({
-        name: "record_openspec_selection",
-        label: "record_openspec_selection",
-        description: "Commit one OpenSpec candidate classification (origin=contract openspec-selection fact). Call once per path you actually use or consult: required (must be read and cited) or relevant (informs planning). Never call it for irrelevant candidates — unmentioned candidates default to irrelevant. You may call it many times; one row per call.",
-        promptSnippet: "Commit one OpenSpec candidate classification (required | relevant); one path per call; skip irrelevant candidates.",
-        parameters: Type.Object({
-            path: Type.String({
-                description: "Repo-relative candidate spec path, e.g. openspec/project-specs/ui/ucp-components-md/AdvancedSearch.md",
-            }),
-            disposition: Type.Enum({
-                required: "required",
-                relevant: "relevant",
-            }),
-            rationale: Type.String({}),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const path = typeof params?.path === "string" ? params.path : "";
-            const disposition = params?.disposition;
-            const rationale = typeof params?.rationale === "string" ? params.rationale : "";
-            if (!path || !disposition || !rationale.trim()) {
-                return receipt({
-                    ok: false,
-                    kind: "openspec-selection",
-                    error: "record_openspec_selection requires non-empty path, disposition (required|relevant), and rationale",
-                });
-            }
-            const result = await adoptContractFact("openspec-selection", {
-                kind: "openspec-selection",
-                origin: "contract",
-                path,
-                disposition,
-                rationale,
-            });
-            return receipt(result);
-        },
-    });
-    const finalizeContractTool = defineTool({
-        name: "finalize_contract",
-        label: "finalize_contract",
-        description: "Commit the contract-finalized terminal fact with a disposition of ready | ready-with-assumptions | blocked (blocked requires blockingOwner). A successful terminal commit occurs exactly once. If validation fails, correct only the reported facts and retry finalize.",
-        promptSnippet: "Commit the contract-finalized terminal (disposition + optional blockingOwner).",
-        parameters: Type.Object({
-            disposition: Type.Enum({
-                ready: "ready",
-                "ready-with-assumptions": "ready-with-assumptions",
-                blocked: "blocked",
-            }),
-            blockingOwner: Type.Optional(Type.Enum({
-                "blocked-human": "blocked-human",
-                "blocked-external": "blocked-external",
-            })),
-            assumptions: Type.Optional(Type.Array(Type.String({}))),
-            summary: Type.Optional(Type.String({})),
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const disposition = params?.disposition;
-            const blockingOwner = params?.blockingOwner;
-            if (disposition === "blocked" && !blockingOwner) {
-                return receipt({
-                    ok: false,
-                    kind: "finalize_contract",
-                    error: "blocked disposition requires blockingOwner (blocked-human | blocked-external)",
-                });
-            }
-            if (disposition !== "blocked" && input.canonicalRequirements?.size &&
-                !readCommittedEvents(store, attemptId).some((record) => record.fact.kind === "required-deliverables")) {
-                return receipt({
-                    ok: false, kind: "finalize_contract",
-                    error: "call record_required_deliverables with the complete source-bound inventory (or items:[] when none) before finalizing",
-                });
-            }
-            const missing = [...(input.canonicalRequirements?.keys() ?? [])].filter(id => !committedRequirementIds().has(id) || (activeScope !== null && !completedScopeRequirementIds().has(id)));
-            if (disposition !== "blocked" && missing.length)
-                return receipt({ ok: false, code: "CONTRACT_REQUIREMENT_COVERAGE_MISSING", error: `Confirm all complete source obligations before finalizing: ${missing.join(", ")}` });
-            const blockedOwner = mapContractBlockedOwner({
-                disposition: disposition ?? "",
-                blockingOwner,
-            });
-            const result = await adoptContractFact("contract-finalized", {
-                kind: "contract-finalized",
-                origin: "contract",
-                disposition,
-                ...(blockingOwner ? { blockingOwner } : {}),
-                ...(blockedOwner !== "not-blocked" ? { blockedOwner } : {}),
-                ...(Array.isArray(params?.assumptions)
-                    ? { assumptions: params.assumptions }
-                    : {}),
-                ...(typeof params?.summary === "string"
-                    ? { summary: params.summary }
-                    : {}),
-            });
-            return receipt(result);
-        },
-    });
-    const completeScopeTool = defineTool({
-        name: "complete_contract_scope", label: "complete_contract_scope",
-        description: "After recording all requirements AND their evidence, constraints, questions and deliverables for this session, mark the scope complete. Confirming an ID alone does not complete its analysis. Do this before finalize_contract.",
-        parameters: Type.Object({ requirementIds: Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }) }, { additionalProperties: false }),
-        async execute(_id, params) {
-            const ids = params.requirementIds;
-            if (activeScope === null || ids.length !== activeScope.size || ids.some(id => !activeScope?.has(id) || !committedRequirementIds().has(id)))
-                return receipt({ ok: false, code: "CONTRACT_SCOPE_INCOMPLETE", error: "Complete exactly the active scope after confirming all its obligations" });
-            return receipt(await adoptContractFact("contract-scope-completed", { kind: "contract-scope-completed", origin: "contract", requirementIds: ids }));
-        },
-    });
-    const durable = await createDurableFrontendTools({
-        file: path.join(input.runDir, input.nodeId, "contract-typed-facts.jsonl"), attemptId, store: input.store,
-        setWorkingStore: next => { store = next; }, binding: { canonicalRequirements: input.canonicalRequirements, sourceDigest: input.sourceDigest },
-        tools: [
-            ...recordTools,
-            recordRequirementTool,
-            recordRequirementExecutionTool,
-            recordEvidenceExpectationTool,
-            recordUiStateTool,
-            recordRequiredDeliverablesTool,
-            recordOpenspecSelectionTool,
-            completeScopeTool,
-            finalizeContractTool,
-        ],
-    });
-    const durableRecordRequirementTool = durable.customTools.find((tool) => typeof tool === "object" && tool !== null && tool.name === "record_requirement");
-    if (!durableRecordRequirementTool)
-        throw new Error("frontend contract durable requirement tool unavailable");
-    return {
-        customTools: durable.customTools,
-        inputRequirements: () => [...(input.canonicalRequirements ?? [])].map(([id, value]) => ({ id, text: value.text, sourceFragmentIds: [...value.sourceFragmentIds] })),
-        seedCanonicalRequirements: async () => {
-            for (const id of input.canonicalRequirements?.keys() ?? []) {
-                if (committedRequirementIds().has(id))
+ * an invalid-output so the node retry ladder restarts the session with the
+ * diagnostics instead of writing a ledger that R1 would reject.
+ */
+export async function bridgeFrontendPlanDecisionToRelationshipLedger(input) {
+    const { assembleDecisionContractFromFacts, buildFrontendPlanRelationshipPatch, } = await import("../workflows/dag/frontend-plan-decision-contract.js");
+    const committed = input.facts
+        .filter(record => record.phase === "committed")
+        .map(record => record.fact);
+    const decision = assembleDecisionContractFromFacts(committed);
+    const concreteWriteSet = [
+        ...new Set([
+            ...decision.modulePlacements.flatMap(item => item.paths),
+            ...decision.verificationFocus.map(item => item.file),
+        ]),
+    ];
+    // Contract-declared deliverable obligations (the same ledger the analyzer
+    // extracts `requiredDeliverables` from): bind each path to its requirement
+    // so the derived canonical contract plans every contract-mandated file.
+    const requiredDeliverables = new Map();
+    try {
+        const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
+        for (const record of [...contractRecords].reverse()) {
+            const fact = record.fact;
+            if (!fact || fact.origin !== "contract" || fact.kind !== "required-deliverables")
+                continue;
+            for (const item of Array.isArray(fact.items) ? fact.items : []) {
+                if (!item || typeof item !== "object" || Array.isArray(item))
                     continue;
-                const receipt = await durableRecordRequirementTool.execute(`${attemptId}:seed-requirement:${id}`, { id }, undefined, undefined, {});
-                if (receipt.details?.ok !== true) {
-                    throw new Error(`runtime requirement seed rejected for ${id}`);
-                }
+                const requirementId = item.requirementId;
+                const file = item.path;
+                if (typeof requirementId !== "string" || typeof file !== "string")
+                    continue;
+                const paths = requiredDeliverables.get(requirementId) ?? [];
+                paths.push(file);
+                requiredDeliverables.set(requirementId, paths);
             }
-            await durable.flush();
-        },
-        completedScopeRequirementIds,
-        setActiveRequirementScope: ids => { activeScope = ids === null ? null : new Set(ids); },
-        committedRequirementIds,
-        committedFacts: () => readCommittedEvents(input.store, attemptId),
-        flush: async () => {
-            await durable.flush();
-            const committed = readCommittedEvents(input.store, attemptId);
-            await writeJsonAtomic(path.join(input.runDir, input.nodeId, "frontend-task-contract-vNext.json"), buildFrontendTaskContractVNext(committed));
-        },
+            break;
+        }
+    }
+    catch {
+        // Missing/unreadable contract ledger → no deliverable obligations to merge.
+    }
+    if (!input.skeleton || !input.sourceBinding) {
+        return { ok: false, error: "frontend decision bridge requires the runtime skeleton and sourceBinding" };
+    }
+    let patch;
+    try {
+        const { analyzeFrontendPlanPatchCandidate, applyFrontendContractMergePatch, serializeDeterministicJson, } = await import("../workflows/dag/frontend-implementation-contract.js");
+        patch = buildFrontendPlanRelationshipPatch({
+            decision,
+            authority: input.authority,
+            concreteWriteSet,
+            requiredDeliverables,
+        });
+        const merged = applyFrontendContractMergePatch(input.skeleton, patch);
+        await analyzeFrontendPlanPatchCandidate({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+    }
+    catch (error) {
+        const raw = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            // This path should be rare now that finalize_decision pre-validates
+            // the same patch in-session; keep the retry-prompt diagnostics in
+            // decision-channel vocabulary regardless.
+            error: `frontend decision → relationship patch failed pre-validation (correct the reported decision facts, then the retry ladder restarts the session): ${translateDecisionPatchFindings(raw, decision)}`,
+        };
+    }
+    const { createTypedEventStore, stageTypedEventRecord, commitTypedEventRecord, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const file = path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl");
+    const store = createTypedEventStore();
+    const adopt = (kind, patchValue, revision) => {
+        const eventId = `decision-bridge:${input.attemptId}:${kind}`;
+        const fact = { kind, origin: "plan", patch: patchValue };
+        stageTypedEventRecord(store, {
+            eventId,
+            requestId: eventId,
+            attemptId: input.attemptId,
+            fact,
+        });
+        return commitTypedEventRecord(store, eventId, revision);
     };
+    adopt("target-surface", patch, 1);
+    adopt("finalize_plan", patch, 2);
+    // The ledger is derived wholesale from the committed decision facts, so a
+    // re-run rewrites it atomically (no incremental append semantics needed).
+    await writeTypedEventStoreJsonl(file, store.records.filter(record => record.phase === "committed"));
+    return { ok: true, patch };
 }
 async function resolveFrontendScoutSourceDeclaredPaths(input) {
     const binding = input.spec.sourceBinding;
@@ -4032,270 +1464,6 @@ async function resolveFrontendScoutSourceDeclaredPaths(input) {
     }
     return [...declared].sort();
 }
-/**
- * A+B: `frontend-scout-pi` incremental evidence tools (origin=scout). Runtime
- * enriches committed target-surface / design-evidence facts with hash/section/
- * freshness from real read events; the tool itself never trusts model self-report.
- */
-export async function createFrontendScoutEvidenceTools(input) {
-    const [{ Type }, { defineTool }] = await Promise.all([
-        import("typebox"),
-        import("@earendil-works/pi-coding-agent"),
-    ]);
-    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
-    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
-    let store = input.store;
-    const attemptId = input.attemptId;
-    const stringArray = Type.Array(Type.String({}));
-    const optionalString = Type.Optional(Type.String({}));
-    const scoutCompleteness = Type.Union([
-        Type.Literal("complete"),
-        Type.Literal("blocked"),
-    ]);
-    const receipt = (details) => ({
-        content: [{ type: "text", text: JSON.stringify(details) }],
-        details,
-    });
-    const sourceDeclaredPaths = (input.sourceDeclaredPaths ?? []).map((value) => value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, ""));
-    const hasSourceDeclarations = input.sourceDeclaredPaths !== undefined;
-    let activeScope;
-    const scopeIdentity = (ids) => createHash("sha256").update(JSON.stringify([...ids].sort())).digest("hex");
-    const latestScopes = () => {
-        const byRequirement = new Map();
-        for (const record of readCommittedEvents(store, attemptId))
-            if (record.fact.kind === "scout-scope" && Array.isArray(record.fact.requirementIds)) {
-                for (const id of record.fact.requirementIds)
-                    if (typeof id === "string")
-                        byRequirement.set(id, record.fact);
-            }
-        return byRequirement;
-    };
-    const isSourceDeclared = (candidate) => {
-        const normalized = candidate.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
-        return sourceDeclaredPaths.some((declared) => declared === normalized || declared.startsWith(`${normalized}/`));
-    };
-    // A+B (AC-003): runtime enriches declared scout paths with hash/freshness
-    // from the real filesystem. The model's self-reported path list is never
-    // trusted for content identity; a missing file fails closed to fresh=false
-    // with a zero hash instead of inventing content.
-    const enrichScoutPathEvidence = async (paths) => {
-        if (!input.workspaceRoot)
-            return [];
-        const workspaceRoot = path.resolve(input.workspaceRoot);
-        const evidence = [];
-        for (const relative of new Set(paths)) {
-            const absolute = path.resolve(workspaceRoot, relative);
-            if (absolute !== workspaceRoot &&
-                !absolute.startsWith(`${workspaceRoot}${path.sep}`)) {
-                evidence.push({ path: relative, sha256: "0".repeat(64), fresh: false, sourceDeclared: isSourceDeclared(relative) });
-                continue;
-            }
-            try {
-                // Directories are legitimate named targets (greenfield smoke: the
-                // page directory exists while the files inside it are to be
-                // created). readFile on a directory throws EISDIR, which used to
-                // mark every directory path fresh=false and structurally fail the
-                // freshness gate for create-new surfaces. stat() first: a directory
-                // counts as fresh existence evidence; its content hash is a stable
-                // directory marker since there is no single file content to hash.
-                const info = await stat(absolute);
-                if (info.isDirectory()) {
-                    evidence.push({
-                        path: relative,
-                        sha256: createHash("sha256").update(`directory:${relative}`).digest("hex"),
-                        fresh: true,
-                        sourceDeclared: isSourceDeclared(relative),
-                    });
-                    continue;
-                }
-                const bytes = await readFile(absolute);
-                evidence.push({
-                    path: relative,
-                    sha256: createHash("sha256").update(bytes).digest("hex"),
-                    fresh: true,
-                    sourceDeclared: isSourceDeclared(relative),
-                });
-            }
-            catch {
-                evidence.push({ path: relative, sha256: "0".repeat(64), fresh: false, sourceDeclared: isSourceDeclared(relative) });
-            }
-        }
-        return evidence;
-    };
-    async function adoptScoutFact(kind, fact) {
-        try {
-            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
-            const staged = stageTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-            });
-            const committed = await adoptTypedEventFact({
-                store,
-                requestId,
-                attemptId,
-                fact: fact,
-                eventId: staged.eventId,
-                expectedRevision: store.revision,
-            });
-            return {
-                ok: true,
-                kind,
-                eventId: committed.eventId,
-                revision: committed.revision,
-                error: "",
-            };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                kind,
-                code: error?.code,
-                error: error instanceof Error ? error.message : String(error),
-            };
-        }
-    }
-    const recordTargetSurfaceTool = defineTool({
-        name: "record_target_surface",
-        label: "record_target_surface",
-        description: "Commit an origin=scout target-surface fact with complete/blocked discovery status. A complete surface needs a proven target path and no unresolved paths; blocked surfaces name the unresolved paths instead of guessing. Example: {\"completeness\": \"complete\", \"entrypoint\": \"<file>\", \"implementationPaths\": [\"<dir or file>\"], \"testPaths\": [\"<file>\"], \"allowedPathConflicts\": [], \"unresolvedPaths\": []}",
-        promptSnippet: "Commit an origin=scout target-surface fact.",
-        parameters: Type.Object({
-            scopeId: Type.Optional(Type.String({ minLength: 1 })),
-            completeness: scoutCompleteness,
-            entrypoint: optionalString,
-            routeOrMount: optionalString,
-            implementationPaths: stringArray,
-            proposedPaths: Type.Optional(stringArray),
-            testPaths: stringArray,
-            dataSource: optionalString,
-            allowedPathConflicts: stringArray,
-            unresolvedPaths: stringArray,
-        }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            if (input.requirementIds && (!activeScope?.length || params.scopeId !== scopeIdentity(activeScope)))
-                return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "Use exactly the runtime Scout scopeId; discovery may complete only the supplied obligations" });
-            const implementationPaths = params?.implementationPaths ?? [];
-            const proposedPaths = params?.proposedPaths ?? [];
-            const testPaths = params?.testPaths ?? [];
-            const pathEvidence = await enrichScoutPathEvidence([
-                ...(params?.entrypoint ? [params.entrypoint] : []),
-                ...implementationPaths,
-                ...testPaths,
-            ]);
-            for (const proposedPath of proposedPaths) {
-                if (!pathEvidence.some((item) => item.path === proposedPath)) {
-                    pathEvidence.push({ path: proposedPath, sha256: "0".repeat(64), fresh: false, sourceDeclared: false, proposed: true });
-                }
-            }
-            const surface = {
-                kind: "target-surface",
-                origin: "scout",
-                completeness: params?.completeness ?? "blocked",
-                entrypoint: params?.entrypoint ?? "",
-                routeOrMount: params?.routeOrMount ?? "",
-                implementationPaths,
-                ...(proposedPaths.length > 0 ? { proposedPaths } : {}),
-                testPaths,
-                dataSource: params?.dataSource ?? "",
-                allowedPathConflicts: params?.allowedPathConflicts ?? [],
-                unresolvedPaths: params?.unresolvedPaths ?? [],
-                ...(hasSourceDeclarations ? { sourceDeclaredPaths } : {}),
-                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
-            };
-            if (activeScope) {
-                const { readCompleteScoutTargetSurface } = await import("../workflows/dag/frontend-committed-facts.js");
-                if (surface.completeness === "complete") {
-                    const check = readCompleteScoutTargetSurface([{ phase: "committed", fact: surface }]);
-                    if (!check.ok)
-                        return receipt({ ok: false, code: "SCOUT_SCOPE_INCOMPLETE", error: check.reason });
-                }
-                const saved = await adoptScoutFact("scout-scope", { kind: "scout-scope", origin: "scout", id: params.scopeId, requirementIds: activeScope, surface });
-                if (!saved.ok)
-                    return receipt(saved);
-                const current = latestScopes();
-                if (input.requirementIds?.every(id => current.get(id)?.surface?.completeness === "complete")) {
-                    const surfaces = [...new Set(input.requirementIds.map(id => current.get(id)))].map(f => f.surface);
-                    const union = (key) => [...new Set(surfaces.flatMap(s => Array.isArray(s[key]) ? s[key] : []))];
-                    const entries = [...new Set(surfaces.map(s => String(s.entrypoint ?? "")).filter(Boolean))];
-                    return receipt(await adoptScoutFact("target-surface", { kind: "target-surface", origin: "scout", completeness: "complete", entrypoint: entries[0] ?? "", implementationPaths: [...new Set([...entries, ...union("implementationPaths")])], proposedPaths: union("proposedPaths"), testPaths: union("testPaths"), allowedPathConflicts: union("allowedPathConflicts"), unresolvedPaths: union("unresolvedPaths"), routeOrMount: [...new Set(surfaces.map(s => s.routeOrMount).filter(Boolean))].join("\n"), dataSource: [...new Set(surfaces.map(s => s.dataSource).filter(Boolean))].join("\n"), pathEvidence: surfaces.flatMap(s => s.pathEvidence ?? []), ...(hasSourceDeclarations ? { sourceDeclaredPaths } : {}) }));
-                }
-                return receipt(saved);
-            }
-            const result = await adoptScoutFact("target-surface", surface);
-            return receipt(result);
-        },
-    });
-    const recordDesignEvidenceTool = defineTool({
-        name: "record_design_evidence",
-        label: "record_design_evidence",
-        description: "Commit an origin=scout design-evidence fact (source, paths, conflicts). Example: {\"source\": \"<source>\", \"paths\": [\"<file>\"], \"conflicts\": []}",
-        promptSnippet: "Commit an origin=scout design-evidence fact.",
-        parameters: Type.Object({ source: Type.String({}), paths: stringArray, conflicts: stringArray }, { additionalProperties: false }),
-        async execute(_toolCallId, params) {
-            const paths = params?.paths ?? [];
-            const pathEvidence = await enrichScoutPathEvidence(paths);
-            const result = await adoptScoutFact("design-evidence", {
-                kind: "design-evidence",
-                origin: "scout",
-                source: params?.source ?? "",
-                paths,
-                conflicts: params?.conflicts ?? [],
-                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
-            });
-            return receipt(result);
-        },
-    });
-    const durable = await createDurableFrontendTools({
-        file: path.join(input.runDir, input.nodeId, "scout-typed-facts.jsonl"), attemptId, store: input.store,
-        setWorkingStore: next => { store = next; }, binding: { requirementIds: input.requirementIds, sourceDeclaredPaths: input.sourceDeclaredPaths, sourceDigest: input.sourceDigest, workspaceRoot: input.workspaceRoot },
-        tools: [recordTargetSurfaceTool, recordDesignEvidenceTool],
-        validateRestored: async (records) => {
-            if (!input.workspaceRoot)
-                return;
-            for (const record of records) {
-                const evidence = record.fact.kind === "scout-scope" ? record.fact.surface?.pathEvidence : record.fact.pathEvidence;
-                if (!Array.isArray(evidence))
-                    continue;
-                for (const previous of evidence) {
-                    if (!isRecordObject(previous) || typeof previous.path !== "string")
-                        throw Error("scout path evidence is malformed");
-                    const current = (await enrichScoutPathEvidence([previous.path]))[0];
-                    if (!current || current.sha256 !== previous.sha256 || current.fresh !== previous.fresh)
-                        throw Error(`scout evidence drift: ${previous.path}; refresh Scout before reusing facts`);
-                }
-            }
-        },
-    });
-    return {
-        ...durable,
-        adoptCommittedFacts: async (records) => durable.commitExternal(async () => {
-            for (const record of records) {
-                if (record.phase !== "committed")
-                    continue;
-                const fact = record.fact;
-                if (!fact || typeof fact !== "object" || Array.isArray(fact))
-                    continue;
-                const result = await adoptScoutFact(typeof fact.kind === "string"
-                    ? fact.kind
-                    : "scout-fact", fact);
-                if (!result.ok) {
-                    throw new Error(`frontend scout shard fact merge failed: ${result.error}`);
-                }
-            }
-        }),
-        setActiveScope: ids => {
-            if (!ids.length || ids.some(id => !input.requirementIds?.includes(id)))
-                throw Error("FRONTEND_INPUT_SCOPE_VIOLATION");
-            activeScope = [...new Set(ids)];
-            return scopeIdentity(activeScope);
-        },
-        completedRequirementIds: () => new Set([...latestScopes()].filter(([, fact]) => fact.surface?.completeness === "complete").map(([id]) => id)),
-        completedScopeFacts: () => [...new Set(latestScopes().values())].filter(f => f.surface?.completeness === "complete"),
-        committedFacts: () => readCommittedEvents(store, attemptId),
-    };
-}
 export function buildDagPiUserMessage(task, persona, step) {
     const role = task.role ?? "unspecified";
     const writePolicy = task.writePolicy ?? "read-only (default)";
@@ -4355,27 +1523,6 @@ export function buildDagPiUserMessage(task, persona, step) {
         "Do not wrap the output in code fences and do not add conversational preamble.",
     ].join(" ");
 }
-export function resolveDagPiModelConfig(modelReference, options) {
-    const separatorIndex = modelReference.indexOf("/");
-    const qualified = separatorIndex >= 0;
-    const provider = qualified
-        ? modelReference.slice(0, separatorIndex)
-        : (DAG_PI_MODEL_PROVIDERS[modelReference] ?? DEFAULT_DAG_PI_PROVIDER);
-    const model = qualified
-        ? modelReference.slice(separatorIndex + 1)
-        : modelReference;
-    if (!provider || !model) {
-        throw new Error(`invalid DAG Pi model reference "${modelReference}": expected non-empty provider/model`);
-    }
-    const explicitThinking = options?.thinking?.trim();
-    const thinking = explicitThinking ??
-        (provider === "wizard-local" && model === "gpt-5.5" ? "low" : undefined);
-    return {
-        provider,
-        model,
-        ...(thinking ? { thinking } : {}),
-    };
-}
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
 export function buildPiPromptRedactedMarkdown(prompt) {
@@ -4660,184 +1807,6 @@ const FRONTEND_PLAN_SEGMENTS = [
         ].join(" "),
     },
 ];
-function committedFactFromPlanRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const record = value;
-    if (record.phase !== undefined && record.phase !== "committed")
-        return undefined;
-    const fact = record.fact;
-    return fact && typeof fact === "object" && !Array.isArray(fact)
-        ? fact
-        : typeof record.kind === "string"
-            ? record
-            : undefined;
-}
-function planFactStringList(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
-}
-function planFactScopeIntersects(fact, requirementIds) {
-    return planFactStringList(fact.scopeRequirementIds).some((id) => requirementIds.has(id));
-}
-/** Compute the authoritative coverage queue from the committed plan ledger. */
-export function collectFrontendPlanMissingFacts(input) {
-    const requirements = new Map();
-    const standaloneEvidenceGaps = new Set();
-    const verificationTargetIds = new Set();
-    const verificationTargetRequirements = new Map();
-    for (const value of input.committedFacts) {
-        const fact = committedFactFromPlanRecord(value);
-        if (!fact || fact.origin !== "plan")
-            continue;
-        if (fact.kind === "plan-requirement" && fact.entry && typeof fact.entry === "object") {
-            const entry = fact.entry;
-            if (typeof entry.id === "string" && entry.id.trim())
-                requirements.set(entry.id, entry);
-        }
-        if (fact.kind === "plan-verification-target" && fact.entry && typeof fact.entry === "object") {
-            const entry = fact.entry;
-            const id = entry.id;
-            if (typeof id === "string" && id.trim()) {
-                verificationTargetIds.add(id);
-                verificationTargetRequirements.set(id, new Set(Array.isArray(entry.requirementIds)
-                    ? entry.requirementIds.filter((value) => typeof value === "string")
-                    : []));
-            }
-        }
-        if (fact.kind === "plan-evidence-gap" && fact.entry && typeof fact.entry === "object") {
-            const entry = fact.entry;
-            const requirementId = entry.requirementId;
-            const description = entry.description;
-            if (typeof requirementId === "string" && requirementId.trim() && typeof description === "string" && description.trim()) {
-                standaloneEvidenceGaps.add(requirementId);
-            }
-        }
-    }
-    const missing = [];
-    for (const id of input.requirementIds) {
-        const entry = requirements.get(id);
-        if (!entry) {
-            missing.push({
-                kind: "plan-requirement",
-                id,
-                requirementIds: [id],
-                reason: `requirement ${id} has no committed plan-requirement fact`,
-            });
-            continue;
-        }
-        // Verification targets are the single authoritative direction. The
-        // legacy requirement-side list is accepted only as a fallback while
-        // resuming older ledgers; new plans derive it from target.requirementIds.
-        const derivedTargetIds = [...verificationTargetRequirements.entries()]
-            .filter(([, requirementIds]) => requirementIds.has(id))
-            .map(([targetId]) => targetId);
-        const legacyTargetIds = Array.isArray(entry.verificationTargetIds)
-            ? entry.verificationTargetIds.filter((value) => typeof value === "string" && value.trim().length > 0)
-            : [];
-        const targetIds = derivedTargetIds.length > 0 ? derivedTargetIds : legacyTargetIds;
-        const gap = entry.evidenceGap && typeof entry.evidenceGap === "object"
-            ? entry.evidenceGap
-            : undefined;
-        const hasEvidenceGap = (typeof gap?.description === "string" && gap.description.trim().length > 0) ||
-            standaloneEvidenceGaps.has(id);
-        if (targetIds.length === 0 && !hasEvidenceGap) {
-            missing.push({
-                kind: "plan-verification-target",
-                requirementIds: [id],
-                reason: `requirement ${id} declares neither a verification target nor a non-empty evidenceGap`,
-            });
-            continue;
-        }
-        for (const targetId of targetIds) {
-            if (!verificationTargetIds.has(targetId) ||
-                !verificationTargetRequirements.get(targetId)?.has(id)) {
-                missing.push({
-                    kind: "plan-verification-target",
-                    id: targetId,
-                    requirementIds: [id],
-                    reason: `requirement ${id} references verification target ${targetId}, but that target is not committed`,
-                });
-            }
-        }
-    }
-    return missing;
-}
-/** Completeness checks for phases whose facts are committed incrementally. */
-export function collectFrontendPlanPhaseMissingFacts(input) {
-    const facts = input.committedFacts
-        .map(committedFactFromPlanRecord)
-        .filter((fact) => Boolean(fact && fact.origin === "plan"));
-    if (input.phase === "ux-registry") {
-        return facts.some((fact) => fact.kind === "state-registry")
-            ? []
-            : [
-                {
-                    kind: "state-registry",
-                    requirementIds: [...input.requirementIds],
-                    reason: "global UX vocabulary phase has no committed state-registry fact",
-                },
-            ];
-    }
-    if (input.phase === "ux-local") {
-        const missing = [];
-        // Evaluate each behaviour requirement independently. A fact scoped to AC-1
-        // must not accidentally satisfy AC-2 merely because both ids share one
-        // UX session; shared facts remain valid when they explicitly list both ids.
-        for (const requirementId of input.requirementIds) {
-            if (!input.behaviorRequiredRequirementIds?.includes(requirementId))
-                continue;
-            const scopedFacts = facts.filter((fact) => planFactScopeIntersects(fact, new Set([requirementId])));
-            const hasChoice = scopedFacts.some((fact) => fact.kind === "component-choice" &&
-                Array.isArray(fact.uiComponentChoices) &&
-                fact.uiComponentChoices.length > 0);
-            const canonicalStateFlow = collectCanonicalStateFlowNames(scopedFacts);
-            const hasStateFlow = canonicalStateFlow.uiStateNames.size > 0 ||
-                canonicalStateFlow.interactionNames.size > 0;
-            if (!hasChoice) {
-                missing.push({
-                    kind: "component-choice",
-                    requirementIds: [requirementId],
-                    reason: "behaviour-required UX slice has no committed component-choice fact",
-                });
-            }
-            if (!hasStateFlow) {
-                missing.push({
-                    kind: "state-flow",
-                    requirementIds: [requirementId],
-                    reason: "behaviour-required UX slice has no committed state-flow fact",
-                });
-            }
-        }
-        return missing;
-    }
-    const hasMockApi = facts.some((fact) => fact.kind === "mock-api");
-    const allInteractions = collectCanonicalStateFlowNames(input.committedFacts).interactionNames;
-    const liveInteractions = new Set([...collectCanonicalStateFlowNames(facts.filter(f => !planFactStringList(f.scopeRequirementIds).length || planFactScopeIntersects(f, new Set(input.requirementIds)))).interactionNames].filter(name => allInteractions.has(name)));
-    const coveredInteractions = new Set(facts
-        .filter((fact) => fact.kind === "data-flow")
-        .flatMap((fact) => planFactStringList(fact.interactions)));
-    const missing = [];
-    if (!hasMockApi) {
-        missing.push({
-            kind: "mock-api",
-            requirementIds: [...input.requirementIds],
-            reason: "global Mock/data phase has no committed mock-api fact",
-        });
-    }
-    for (const interaction of liveInteractions) {
-        if (coveredInteractions.has(interaction))
-            continue;
-        missing.push({
-            kind: "data-flow",
-            id: interaction,
-            requirementIds: [...input.requirementIds],
-            reason: `interaction ${interaction} has no committed data-flow fact`,
-        });
-    }
-    return missing;
-}
 /** Estimate calls conservatively: requirement + one VT, with a second VT
  * reserved for behaviour-required requirements. Explicit declarations win. */
 export function estimateFrontendPlanRequirementRecordCalls(fact) {
@@ -5914,9 +2883,9 @@ export async function runFrontendPlanSegmentedSessions(input) {
             }
         }
         const work = [...domains.values()];
-        const scaffoldBytes = Buffer.byteLength(input.basePrompt.replace(/<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/, JSON.stringify({ ...compiledInput, requirements: [] }))) + Buffer.byteLength(JSON.stringify(input.segmentCustomTools(globalMockDataSegment.toolNames)));
+        // Work-unit packing and full provider envelope capacity have separate budgets.
         return packFrontendInputUnits(work, {
-            targetBytes: Math.max(1, (input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES) - scaffoldBytes),
+            targetBytes: input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES,
             maxUnits: input.sessionOptions.frontendExecutionPolicy?.maxScopeUnits ?? 4,
             maxCost: FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS,
             cost: (group) => group.estimatedCalls,
@@ -6170,7 +3139,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
         };
         const customTools = input.segmentCustomTools(atomicFocus ? new Set([atomicTools[atomicFocus.kind]]) : session.toolNames);
         const result = await observeFrontendSession({
-            ...input.observation, phase: `plan/${session.id}`, scopeIds: session.requirementSlice ?? session.coverageSlice ?? allRequirementIds,
+            ...input.observation, phase: `plan/${session.id}`, dispatchReason: (session.retryCount ?? 0) > 0 || !!session.missingFacts?.length || /capacity|recovery|split/.test(session.id) ? "correction" : "initial", scopeIds: session.requirementSlice ?? session.coverageSlice ?? allRequirementIds,
             prompt, userMessage: input.sessionOptions.userMessage, customTools, committedCount: input.committedFactCount, durableCommittedCount: () => lastDurableCount,
             artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-${invocationCount}.json` : undefined,
         }, async (observer) => {
@@ -6530,7 +3499,12 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 optionalPlanFields.realIntegrationGap = fact.realIntegrationGap;
             }
         }
-        let finalizeResult = await input.finalizePlan(optionalPlanFields);
+        let finalizationCount = 0;
+        const finalize = () => observeFrontendFinalization({
+            ...input.observation,
+            artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-runtime-finalize-${++finalizationCount}.json` : undefined,
+        }, () => input.finalizePlan(optionalPlanFields));
+        let finalizeResult = await finalize();
         const finalizeDetails = finalizeResult && typeof finalizeResult === "object"
             ? (finalizeResult.details ?? finalizeResult)
             : finalizeResult;
@@ -6551,20 +3525,30 @@ export async function runFrontendPlanSegmentedSessions(input) {
             ].filter(Boolean).join("\n\n");
             input.setActiveRequirementScope?.([]);
             const correctionTools = input.segmentCustomTools(null);
-            const correction = await input.piStepFn({
-                ...input.sessionOptions,
-                prompt: correctionPrompt,
-                writerToolPolicy: { requireSdk: true, customTools: correctionTools },
+            const correction = await observeFrontendSession({
+                ...input.observation, phase: "plan/finalize-correction", dispatchReason: "correction",
+                scopeIds: input.requirementIds, prompt: correctionPrompt, userMessage: input.sessionOptions.userMessage,
+                customTools: correctionTools, committedCount: input.committedFactCount, durableCommittedCount: () => lastDurableCount,
+                artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-finalize-correction.json` : undefined,
+            }, async (observer) => {
+                const result = await input.piStepFn({
+                    ...input.sessionOptions, onAttemptObservation: observer, prompt: correctionPrompt,
+                    writerToolPolicy: { requireSdk: true, customTools: correctionTools },
+                });
+                try {
+                    await input.flushLedger();
+                    lastDurableCount = input.committedFactCount();
+                }
+                catch { /* node-level flush retries below */ }
+                return result;
             });
-            try {
-                await input.flushLedger();
-            }
-            catch { /* node-level flush retries below */ }
             accumulated = accumulated
                 ? combineSequentialPiResults(accumulated, correction)
                 : correction;
+            if (!correction.ok && !["invalid-output", "empty-output", "success"].includes(correction.failureCategory))
+                return { ...accumulated, ok: false, failureCategory: correction.failureCategory };
             if (correction.ok) {
-                finalizeResult = await input.finalizePlan(optionalPlanFields);
+                finalizeResult = await finalize();
             }
             const retriedDetails = finalizeResult && typeof finalizeResult === "object"
                 ? (finalizeResult.details ?? finalizeResult)
@@ -6657,7 +3641,7 @@ async function runFrontendScoutParallelSessions(input) {
             toolName: "record_target_surface",
             instruction: [
                 "PARALLEL SCOUT SHARD — target surface only.",
-                "Inspect routes, entrypoints, implementation ownership, data source, and applicable test paths.",
+                "Inspect routes, entrypoints, implementation ownership, data source, and existing test entrypoints. Inspect project source/config first; do not recursively explore dependency internals merely to reconfirm standard test-runner behavior. If a concrete required capability cannot be established from project evidence, report the precise gap.",
                 "Call record_target_surface exactly once with the complete runtime-evidenced surface. Do not call record_design_evidence.",
             ].join(" "),
         },
@@ -6666,12 +3650,16 @@ async function runFrontendScoutParallelSessions(input) {
             toolName: "record_design_evidence",
             instruction: [
                 "PARALLEL SCOUT SHARD — design evidence only.",
-                "Inspect the frontend framework, styling/theme conventions, reusable components, and relevant design/spec files.",
+                "Inspect project-owned frontend framework, styling/theme conventions, reusable components, and relevant design/spec files. The surface shard owns test-runner/environment discovery; do not duplicate its Vitest/happy-dom investigation. Stop discovery once the design evidence is sufficient and commit it.",
                 "Call record_design_evidence for the evidence you actually read. Do not call record_target_surface.",
             ].join(" "),
         },
     ];
     const outcomes = await Promise.all(shards.map(async (shard) => {
+        const cacheKey = JSON.stringify([input.runDir, input.nodeId, shard.id, input.sessionOptions.modelConfig, input.observation?.model, input.observation?.sourceDigest, input.sourceDeclaredPaths]);
+        const cached = input.completedShards?.get(cacheKey);
+        if (cached)
+            return { shard, facts: cached.facts, result: { ...cached.result, durationMs: 0, tokensUsed: 0, parsedEvents: 0, attemptedModels: [], fallbackUsed: false } };
         let shardTools;
         let shardResult;
         try {
@@ -6714,7 +3702,12 @@ async function runFrontendScoutParallelSessions(input) {
                 },
             }));
             await shardTools.flush();
-            return { shard, result: shardResult, tools: shardTools };
+            const facts = shardTools.committedFacts();
+            const expectedKind = shard.id === "design" ? "design-evidence" : "target-surface";
+            if (shardResult.ok && facts.some(record => { const fact = record.fact; return fact.kind === expectedKind && (shard.id !== "surface" || fact.completeness === "complete"); })) {
+                input.completedShards?.set(cacheKey, { result: structuredClone(shardResult), facts: structuredClone(facts) });
+            }
+            return { shard, result: shardResult, tools: shardTools, facts };
         }
         catch (error) {
             const crashMessage = `frontend scout parallel shard ${shard.id} crashed: ${error instanceof Error ? error.message : String(error)}`;
@@ -6754,8 +3747,8 @@ async function runFrontendScoutParallelSessions(input) {
     const ordered = [...outcomes].sort((left, right) => left.shard.id.localeCompare(right.shard.id));
     try {
         for (const outcome of ordered) {
-            if (outcome.result.ok && outcome.tools) {
-                await input.mainTools.adoptCommittedFacts(outcome.tools.committedFacts());
+            if (outcome.result.ok) {
+                await input.mainTools.adoptCommittedFacts(outcome.facts ?? outcome.tools?.committedFacts() ?? []);
             }
         }
     }
@@ -6782,7 +3775,7 @@ async function runFrontendScoutParallelSessions(input) {
             stderr: `${aggregate.stderr}\nfrontend scout parallel shard failed: ${failed.shard.id}`.trim(),
         };
     }
-    const committedKinds = new Set(ordered.flatMap((outcome) => (outcome.tools?.committedFacts() ?? [])
+    const committedKinds = new Set(ordered.flatMap((outcome) => (outcome.facts ?? outcome.tools?.committedFacts() ?? [])
         .map((record) => record.fact?.kind)
         .filter((kind) => typeof kind === "string")));
     const missing = ["target-surface", "design-evidence"].filter((kind) => !committedKinds.has(kind));
@@ -6987,7 +3980,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
             const store = createTypedEventStore();
             reviewTerminalTools = await createFrontendReviewTerminalTools({
-                inventory: reviewInventory = await loadFrontendReviewScopes(meta.runDir, "review", meta.spec?.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES),
+                inventory: reviewInventory = await loadFrontendReviewScopes(meta.runDir, "review", meta.spec?.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES, input.cwd),
                 inputDigest: reviewInventory?.digest ?? createHash("sha256").update(input.prompt).digest("hex"),
                 attemptId: `${meta.runId}:${input.task.id}`,
                 store,
@@ -7144,7 +4137,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 if (useDecisionPlan) {
                     // Recovery child: read the parent snapshot before the tools so
                     // the replay and the identical-plan finalize guard share it.
-                    parentDecisionSnapshot = await readParentDecisionSnapshot(meta.runDir, input.task.id);
+                    parentDecisionSnapshot = await readParentDecisionSnapshot(meta.runDir, input.task.id, { workspaceRoot: input.cwd, sourceBinding: meta.spec.sourceBinding });
                 }
                 decisionPlanTools = await createFrontendPlanDecisionTools({
                     attemptId: `${meta.runId}:${input.task.id}`,
@@ -7334,6 +4327,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             scoutEvidenceTools &&
             input.task.complexity !== "LOW") {
             result = await runFrontendScoutParallelSessions({
+                completedShards: input.scoutCompletedShards,
                 piStepFn,
                 sessionOptions: piSessionOptions,
                 basePrompt: input.prompt,
@@ -7412,46 +4406,86 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     return base;
                 })()
                 : input.prompt;
-            const decisionResult = await piStepFn({
-                ...piSessionOptions,
-                prompt: decisionPrompt,
-                writerToolPolicy: { requireSdk: true, customTools: decisionPlanTools.customTools },
+            let decisionDurableCount = decisionPlanTools.committedFacts().length;
+            const decisionResult = await observeFrontendSession({
+                artifactPath: path.join(meta.runDir, input.task.id, "session-budget", `attempt-${input.attempt ?? 1}-decision.json`),
+                phase: "plan/decision", dispatchReason: "initial",
+                runId: meta.runId, nodeId: input.task.id, taskId: meta.spec?.sourceBinding?.taskId,
+                attempt: input.attempt ?? 1, model: input.model,
+                sourceDigest: meta.spec?.sourceBinding?.schemaVersion === 2 ? meta.spec.sourceBinding.inputDigest : undefined,
+                prompt: decisionPrompt, userMessage: piSessionOptions.userMessage, customTools: decisionPlanTools.customTools,
+                committedCount: () => decisionPlanTools.committedFacts().length,
+                durableCommittedCount: () => decisionDurableCount,
+            }, async (observer) => {
+                const result = await piStepFn({
+                    ...piSessionOptions, frontendPlanControl: decisionPlanTools.planControl, onAttemptObservation: observer, prompt: decisionPrompt,
+                    writerToolPolicy: { requireSdk: true, customTools: decisionPlanTools.customTools },
+                });
+                try {
+                    await decisionPlanTools.flush();
+                    decisionDurableCount = decisionPlanTools.committedFacts().length;
+                }
+                catch { /* node-level flush retries below */ }
+                return result;
             });
-            try {
-                await decisionPlanTools.flush();
+            if ((!decisionResult.ok && !["empty-output", "invalid-output", "unknown"].includes(decisionResult.failureCategory)) || decisionPlanTools.planControl.readStop()) {
+                const stopped = decisionPlanTools.planControl.readStop();
+                result = decisionResult.ok && stopped ? { ...decisionResult, ok: false, failureCategory: "invalid-output", stderr: `${stopped.code}: ${stopped.error}` } : decisionResult;
             }
-            catch { /* node-level flush retries below */ }
-            const finalizeResult = await decisionPlanTools.finalizeDecision();
-            const finalizeDetails = finalizeResult && typeof finalizeResult === "object"
-                ? (finalizeResult.details ?? finalizeResult)
-                : finalizeResult;
-            if (finalizeDetails && typeof finalizeDetails === "object" && finalizeDetails.ok === true) {
-                // Bridge the finalized decisions into the relationship-shaped plan
-                // ledger. The node-level R1 self-check and all downstream shells
-                // compile ONLY plan-typed-facts.jsonl; without this write the whole
-                // decision run fails "frontend plan ledger missing" at R1 on every
-                // attempt. Validation failures surface as invalid-output so the
-                // retry ladder restarts the session with the diagnostics.
-                try {
-                    const bridge = await bridgeFrontendPlanDecisionToRelationshipLedger({
-                        runDir: meta.runDir,
-                        nodeId: input.task.id,
-                        attemptId: `${meta.runId}:${input.task.id}`,
-                        facts: decisionPlanTools.committedFacts(),
-                        authority: decisionPlanAuthority,
-                        skeleton: input.task.structuredContractOutput?.skeleton,
-                        sourceBinding: meta.spec.sourceBinding,
-                    });
-                    if (!bridge.ok) {
-                        throw new Error(bridge.error);
+            else {
+                const finalizeResult = await observeFrontendFinalization({
+                    artifactPath: path.join(meta.runDir, input.task.id, "session-budget", `attempt-${input.attempt ?? 1}-runtime-finalize.json`),
+                    runId: meta.runId, nodeId: input.task.id, taskId: meta.spec?.sourceBinding?.taskId, attempt: input.attempt ?? 1,
+                }, () => decisionPlanTools.finalizeDecision());
+                const finalizeDetails = finalizeResult && typeof finalizeResult === "object"
+                    ? (finalizeResult.details ?? finalizeResult)
+                    : finalizeResult;
+                if (finalizeDetails && typeof finalizeDetails === "object" && finalizeDetails.ok === true) {
+                    // Bridge the finalized decisions into the relationship-shaped plan
+                    // ledger. The node-level R1 self-check and all downstream shells
+                    // compile ONLY plan-typed-facts.jsonl; without this write the whole
+                    // decision run fails "frontend plan ledger missing" at R1 on every
+                    // attempt. Validation failures surface as invalid-output so the
+                    // retry ladder restarts the session with the diagnostics.
+                    try {
+                        const bridge = await bridgeFrontendPlanDecisionToRelationshipLedger({
+                            runDir: meta.runDir,
+                            nodeId: input.task.id,
+                            attemptId: `${meta.runId}:${input.task.id}`,
+                            facts: decisionPlanTools.committedFacts(),
+                            authority: decisionPlanAuthority,
+                            skeleton: input.task.structuredContractOutput?.skeleton,
+                            sourceBinding: meta.spec.sourceBinding,
+                        });
+                        if (!bridge.ok) {
+                            throw new Error(bridge.error);
+                        }
+                        result = decisionResult;
+                    }
+                    catch (error) {
+                        result = {
+                            ok: false,
+                            stdout: decisionResult.stdout ?? "",
+                            stderr: `${decisionResult.stderr ?? ""}\n${error instanceof Error ? error.message : String(error)}`.trim(),
+                            failureCategory: "invalid-output",
+                            durationMs: Date.now() - started,
+                            modelDisplay: decisionResult.modelDisplay,
+                            parsedEvents: decisionResult.parsedEvents,
+                            timedOut: decisionResult.timedOut,
+                            attemptedModels: decisionResult.attemptedModels,
+                            fallbackUsed: decisionResult.fallbackUsed,
+                            tokensUsed: decisionResult.tokensUsed,
+                            assistantText: decisionResult.assistantText ?? "",
+                            command: decisionResult.command ?? [],
+                            exitCode: decisionResult.exitCode,
+                        };
                     }
-                    result = decisionResult;
                 }
-                catch (error) {
+                else {
                     result = {
                         ok: false,
                         stdout: decisionResult.stdout ?? "",
-                        stderr: `${decisionResult.stderr ?? ""}\n${error instanceof Error ? error.message : String(error)}`.trim(),
+                        stderr: `${decisionResult.stderr ?? ""}\nfrontend decision finalize failed: ${String(finalizeDetails?.error ?? "decision finalize rejected")}`.trim(),
                         failureCategory: "invalid-output",
                         durationMs: Date.now() - started,
                         modelDisplay: decisionResult.modelDisplay,
@@ -7466,24 +4500,6 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     };
                 }
             }
-            else {
-                result = {
-                    ok: false,
-                    stdout: decisionResult.stdout ?? "",
-                    stderr: `${decisionResult.stderr ?? ""}\nfrontend decision finalize failed: ${String(finalizeDetails?.error ?? "decision finalize rejected")}`.trim(),
-                    failureCategory: "invalid-output",
-                    durationMs: Date.now() - started,
-                    modelDisplay: decisionResult.modelDisplay,
-                    parsedEvents: decisionResult.parsedEvents,
-                    timedOut: decisionResult.timedOut,
-                    attemptedModels: decisionResult.attemptedModels,
-                    fallbackUsed: decisionResult.fallbackUsed,
-                    tokensUsed: decisionResult.tokensUsed,
-                    assistantText: decisionResult.assistantText ?? "",
-                    command: decisionResult.command ?? [],
-                    exitCode: decisionResult.exitCode,
-                };
-            }
         }
         else if (isFrontendPlanLedgerNode(input.task) && planLedgerTools) {
             // Frontend-only split: independent coverage map sessions feed a single
@@ -7496,14 +4512,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             try {
                 const { readCommittedOriginFacts } = await import("../workflows/dag/frontend-committed-facts.js");
                 const contractFacts = await readCommittedOriginFacts(meta.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl");
-                // Only requirement facts: the contract ledger also carries
-                // constraints (CON-*), evidence expectations (EV-*), handoff
-                // intents (HND-*), open questions (OQ-*) and split proposals
-                // (SPLIT-*) that all have ids — feeding those into the coverage
-                // batches made the model record non-frozen plan-requirement ids
-                // that finalize's canonical-coverage gate then rejected (r-ext2).
-                planRequirementIds = collectFrontendPlanRequirementIds(contractFacts);
-                for (const fact of resolveFrontendContractRequirements(contractFacts.map((record) => record.fact))) {
+                // Read current requirements, not append-only revisions introduced when
+                // Contract attaches execution metadata. Coverage and costs must share
+                // the same identity projection as the rendered Plan input.
+                const requirements = resolveFrontendContractRequirements(contractFacts.map(record => record.fact));
+                planRequirementIds = requirements.map(fact => fact.id);
+                for (const fact of requirements) {
                     if (fact.evidence.behavior === "required")
                         behaviorRequiredRequirementIds.push(fact.id);
                     planRequirementCosts.set(fact.id, estimateFrontendPlanRequirementRecordCalls(fact));
@@ -7529,7 +4543,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     contractDigest: meta.spec?.taskContractBinding?.canonicalHash,
                 },
                 piStepFn,
-                sessionOptions: options.sessionOptions,
+                sessionOptions: { ...options.sessionOptions, frontendPlanControl: options.ledgerTools.planControl },
                 basePrompt: options.basePrompt ?? input.prompt,
                 attempt: input.attempt ?? 1,
                 committedFactCount: () => options.ledgerTools.committedFactCount(),