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

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

@@ -1,18 +1,25 @@
 import path from "node:path";
-import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { createHash, randomUUID } 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 { 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";
+import { parseLedgerJson } from "../task/source-prepare/ledger.js";
 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 { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_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, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_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";
+import { assessBackendTestPlanProtocol } from "../workflows/dag/backend-test-plan-protocol.js";
 import { frontendTestLayoutFromSpec } from "../workflows/dag/frontend-test-layout.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 import { writeEffectiveContextReceipt } from "../workflows/dag/context-receipt.js";
@@ -25,6 +32,47 @@ import { writeEffectiveContextReceipt } from "../workflows/dag/context-receipt.j
  * recoverable partial-write-set (incomplete-write-set) upgrade.
  */
 export const WRITER_THINKING_EXHAUSTED_CATEGORY = "writer-thinking-exhausted";
+/**
+ * Planner classification mirroring writer-thinking-exhausted: a read-only
+ * planning session stopped on length, observed thinking, and committed zero
+ * typed facts with no assistant text. By the time this survives the segmented
+ * ladder the scope has already been degraded, so the durable fix is a
+ * thinking-capped or non-thinking model for the tier — not another replay of
+ * the same full-scope prompt.
+ */
+export const PLANNER_THINKING_EXHAUSTED_CATEGORY = "planner-thinking-exhausted";
+export function isPlannerThinkingExhausted(result, committedAnyFacts) {
+    if (result.ok)
+        return false;
+    const evidence = readWriterThinkingExhaustionEvidence(result);
+    if (evidence.stopReason !== "length")
+        return false;
+    if (evidence.thinkingObserved !== true)
+        return false;
+    if (committedAnyFacts)
+        return false;
+    if ((result.assistantText ?? "").trim())
+        return false;
+    // Gateways sometimes relabel a length-stopped stream as `network` or
+    // `nonzero-exit`; provider evidence outweighs the transport label.
+    if (result.failureCategory &&
+        !["empty-output", "network", "nonzero-exit", "unknown"].includes(result.failureCategory))
+        return false;
+    return true;
+}
+/**
+ * The writer session burned an excessive token budget (a read-edit-test loop
+ * that never converged) and still failed. Distinct from empty-output so the
+ * report shows the real cause and recovery recommends a fresh compacted run.
+ * Not auto-retried by default; operators may rerun after a model switch.
+ */
+export const WRITER_BUDGET_EXHAUSTED_CATEGORY = "writer-budget-exhausted";
+/** Token ceiling for a single writer node before it is judged budget-exhausted. */
+export const WRITER_TOKEN_BUDGET = 2_000_000;
+export function allowsMissingChangedWriterOutcomeRecovery(task) {
+    return (isBackendTestCompletenessRetryCandidate(task) ||
+        isBackendTestPytestCollectionRepairOutcomeRecoveryCandidate(task));
+}
 function readWriterThinkingExhaustionEvidence(result) {
     const wider = result;
     return {
@@ -50,8 +98,6 @@ function readWriterThinkingExhaustionEvidence(result) {
 export function isWriterThinkingExhausted(result, mapped, changeManifestChangedFiles) {
     if (mapped.ok)
         return false;
-    if (mapped.failureCategory !== "empty-output")
-        return false;
     const evidence = readWriterThinkingExhaustionEvidence(result);
     if (evidence.stopReason !== "length")
         return false;
@@ -59,6 +105,13 @@ export function isWriterThinkingExhausted(result, mapped, changeManifestChangedF
         return false;
     if ((evidence.writeToolCallCount ?? 0) !== 0)
         return false;
+    // Gateways sometimes classify a length-stopped stream as `network` or
+    // `nonzero-exit` because the terminal event is carried in stderr. The
+    // provider evidence is stronger than that transport label when no write
+    // tool was called and the run produced no diff.
+    if (mapped.failureCategory &&
+        !["empty-output", "network", "nonzero-exit", "unknown"].includes(mapped.failureCategory))
+        return false;
     if (changeManifestChangedFiles === undefined)
         return false;
     if (changeManifestChangedFiles.length !== 0)
@@ -167,6 +220,14 @@ function resolvePiExecutorStep(persona) {
 function isDagPiWriteTask(task) {
     return task.executor === "pi" && task.toolProfile === "write";
 }
+/**
+ * M4: `frontend-implement-pi` derives its status from mechanical facts instead
+ * of the IMPLEMENTATION_OUTCOME first line. Everything else (backend/README/
+ * module writers + frontend-repair-pi) keeps the legacy protocol face.
+ */
+export function isFrontendFactsWriter(task) {
+    return task.writerOutcomePolicy?.type === "frontend-facts-v1";
+}
 /** Map DAG `piStep` / `role` to a safe workflow step for read-only Pi or bounded write. */
 export function resolveDagPiStepName(task) {
     if (isDagPiWriteTask(task)) {
@@ -178,38 +239,2080 @@ export function resolveDagPiStepName(task) {
         if (task.role) {
             return PI_WRITE_ROLE_TO_STEP[task.role];
         }
-        return "implement";
-    }
-    return resolvePiExecutorStep(resolveDagPiPersona(task));
-}
-export function resolveDagPiToolNames(task) {
-    if ((task.readSet?.length ?? 0) > 0) {
-        return isDagPiWriteTask(task) ? ["read", "edit", "write"] : ["read"];
-    }
-    if (!isDagPiWriteTask(task))
-        return [...DAG_PI_READONLY_TOOLS];
-    const tools = [...DAG_PI_WRITE_TOOLS];
-    // Pi SDK activates custom tools only when they are in this explicit list.
-    // Command capabilities (playwright_cli) stay capability-gated; read-only nodes never get command tools.
-    if (dagCommandPolicyAllows(task.commandPolicy, "playwright-cli")) {
-        tools.push("playwright_cli");
+        return "implement";
+    }
+    return resolvePiExecutorStep(resolveDagPiPersona(task));
+}
+/** A+B: `frontend-contract-pi` incremental record tools (origin=contract). */
+export const FRONTEND_CONTRACT_RECORD_TOOL_NAMES = [
+    "record_requirement",
+    "record_constraint",
+    "record_evidence_expectation",
+    "record_handoff_intent",
+    "record_open_question",
+    "record_split_proposal",
+];
+export const FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES = [
+    "finalize_contract",
+];
+/** A+B: `frontend-scout-pi` incremental evidence tools (origin=scout). */
+export const FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES = [
+    "record_target_surface",
+    "record_design_evidence",
+];
+/** A+B: `frontend-plan-pi` incremental record tools (origin=plan). */
+export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
+    "record_route_selection",
+    "record_component_choice",
+    "record_state_flow",
+    "record_data_flow",
+    "record_mock_api",
+    "record_design_deviation",
+    "record_dependency",
+    "record_plan_requirement",
+    "record_plan_verification_target",
+    "record_plan_evidence_gap",
+];
+export const FRONTEND_PLAN_TERMINAL_TOOL_NAMES = ["finalize_plan"];
+export const FRONTEND_PLAN_ADOPT_TOOL_NAMES = ["adopt_staged_fact"];
+/** M5: `frontend-review-pi` emits its authoritative terminal verdict through
+ * committed typed tools instead of the legacy JSON verdict parse. */
+export function isFrontendReviewTypedTerminalNode(task) {
+    return task.id === "frontend-review-pi";
+}
+/** M8: `frontend-design-review-pi` emits its authoritative terminal verdict
+ * through committed typed tools (`approve_design` / `request_design_changes`)
+ * instead of the legacy first-line `VERDICT: pass|request-revision` text. */
+export function isFrontendDesignTypedTerminalNode(task) {
+    return task.id === "frontend-design-review-pi";
+}
+/** A+B: `frontend-contract-pi` submits its contract through incremental typed
+ * tools + the `finalize_contract` terminal (origin=contract). */
+export function isFrontendContractTypedNode(task) {
+    return task.id === "frontend-contract-pi";
+}
+/** A+B: `frontend-scout-pi` submits target-surface/design-evidence through
+ * incremental evidence tools (origin=scout). */
+export function isFrontendScoutEvidenceNode(task) {
+    return task.id === "frontend-scout-pi";
+}
+/** A+B: `frontend-plan-pi` records its decision ledger through seven
+ * incremental `record_*` tools and closes with `finalize_plan`. */
+export function isFrontendPlanLedgerNode(task) {
+    return task.id === "frontend-plan-pi";
+}
+/** Facts-first nodes whose authoritative output is a committed typed terminal
+ * fact (not the assistant text). Downstream compilation reads the flushed
+ * `<nodeId>/<file>` store and never the node narrative, so a committed
+ * terminal means the work is done. */
+const TYPED_TERMINAL_FACT_NODES = {
+    "frontend-contract-pi": {
+        file: "contract-typed-facts.jsonl",
+        kind: "contract-finalized",
+    },
+    "frontend-plan-pi": {
+        file: "plan-typed-facts.jsonl",
+        kind: "finalize_plan",
+    },
+};
+/**
+ * Accept a facts-terminal node result whose final assistant text is blank
+ * when the typed terminal fact was committed successfully. Small-output
+ * models legitimately end after the terminal tool call; without this the
+ * empty assistantText fails the node as empty-output, the failure classifier
+ * phrase-scans the whole session stream and can mislabel the committed run
+ * as rate-limit/network, and the finished ledger is thrown away for a
+ * deterministic retry that burns the full prompt budget again. Fail-closed:
+ * acceptance requires a committed terminal record from the flushed typed
+ * facts store; provider-error attempts (non-empty stderr) are never accepted
+ * by the caller.
+ */
+export async function acceptCommittedTypedTerminalFact(runDir, nodeId) {
+    const binding = TYPED_TERMINAL_FACT_NODES[nodeId];
+    if (!binding)
+        return false;
+    try {
+        const { readCommittedOriginFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+        const records = await readCommittedOriginFacts(runDir, nodeId, binding.file);
+        return records.some((record) => record.fact.kind === binding.kind);
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveDagPiToolNames(task) {
+    if (isFrontendReviewTypedTerminalNode(task)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            "approve_review",
+            "request_review_changes",
+        ];
+    }
+    if (isFrontendDesignTypedTerminalNode(task)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            "approve_design",
+            "request_design_changes",
+        ];
+    }
+    if (isFrontendContractTypedNode(task)) {
+        // Contract is an incremental-commit node: the source-fidelity ledger is
+        // compiled into the <frontend_contract_input> block (node-execution), so
+        // no read tools — mirrors the plan node. Omitting read tools prevents a
+        // contract from spending its output budget re-reading the raw source.
+        return [
+            ...FRONTEND_CONTRACT_RECORD_TOOL_NAMES,
+            ...FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES,
+        ];
+    }
+    if (isFrontendScoutEvidenceNode(task)) {
+        return [...DAG_PI_READONLY_TOOLS, ...FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES];
+    }
+    if (isFrontendPlanLedgerNode(task)) {
+        return [
+            // Plan is a decision-only node. Contract/scout own source and repository
+            // discovery; omitting read tools prevents a planner from spending its
+            // output budget reconstructing already-frozen evidence.
+            ...FRONTEND_PLAN_RECORD_TOOL_NAMES,
+            ...FRONTEND_PLAN_TERMINAL_TOOL_NAMES,
+            ...FRONTEND_PLAN_ADOPT_TOOL_NAMES,
+        ];
+    }
+    if ((task.readSet?.length ?? 0) > 0) {
+        return isDagPiWriteTask(task) ? ["read", "edit", "write"] : ["read"];
+    }
+    if (!isDagPiWriteTask(task))
+        return [...DAG_PI_READONLY_TOOLS];
+    const tools = [...DAG_PI_WRITE_TOOLS];
+    // Pi SDK activates custom tools only when they are in this explicit list.
+    // Command capabilities (playwright_cli) stay capability-gated; read-only nodes never get command tools.
+    if (dagCommandPolicyAllows(task.commandPolicy, "playwright-cli")) {
+        tools.push("playwright_cli");
+    }
+    return tools;
+}
+export const FRONTEND_REVIEW_TERMINAL_TOOL_NAMES = new Set([
+    "approve_review",
+    "request_review_changes",
+]);
+/**
+ * Fail-closed scanner for the two committed review terminal tools. Mirrors
+ * M4's `countWriteToolEventsFromSessionEvents` pattern: an unparseable line
+ * never counts as a terminal fact, so a corrupt/empty log cannot inflate the
+ * typed verdict.
+ */
+export function scanReviewTerminalKindsFromSessionEvents(content) {
+    const kinds = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_REVIEW_TERMINAL_TOOL_NAMES.has(event.toolName)) {
+            kinds.push(event.toolName);
+        }
+    }
+    return kinds;
+}
+const READ_ONLY_TOOL_NAMES = new Set(["read", "grep", "ls", "find"]);
+function readEventPath(event) {
+    const candidates = [event.path, event.readPath, event.input];
+    for (const value of candidates) {
+        if (typeof value === "string")
+            return value;
+        if (value && typeof value === "object") {
+            const nested = value;
+            for (const key of ["path", "readPath", "file"]) {
+                if (typeof nested[key] === "string")
+                    return nested[key];
+            }
+        }
+    }
+    return undefined;
+}
+function eventTimestamp(event) {
+    for (const key of ["timestamp", "timestampMs", "ts", "createdAt"]) {
+        const value = event[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value < 10_000_000_000 ? value * 1000 : value;
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return undefined;
+}
+function eventBytes(event, line) {
+    const result = event.result ?? event.toolResult ?? event.output;
+    if (typeof result === "string")
+        return Buffer.byteLength(result);
+    if (result !== undefined)
+        return Buffer.byteLength(JSON.stringify(result));
+    return Buffer.byteLength(line);
+}
+export async function detectNodeReadBudget(input) {
+    if (!input.budget)
+        return [];
+    const sessionEventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    let content;
+    try {
+        content = await readFile(sessionEventsPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const stats = { files: new Set(), bytes: 0, tools: 0 };
+    let firstTs;
+    let lastTs;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.type !== "tool_execution_start" || typeof event.toolName !== "string" || !READ_ONLY_TOOL_NAMES.has(event.toolName))
+                continue;
+            stats.tools++;
+            const readPath = readEventPath(event);
+            if (readPath)
+                stats.files.add(readPath);
+            stats.bytes += eventBytes(event, line);
+            const ts = eventTimestamp(event);
+            if (ts !== undefined) {
+                firstTs ??= ts;
+                lastTs = ts;
+            }
+        }
+        catch { /* ignore malformed telemetry */ }
+    }
+    if (firstTs !== undefined && lastTs !== undefined)
+        stats.elapsedMs = Math.max(0, lastTs - firstTs);
+    const issues = [];
+    if (stats.files.size > input.budget.maxFiles)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.files.size} files (budget ${input.budget.maxFiles})`);
+    if (stats.bytes > input.budget.maxBytes)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.bytes} bytes (budget ${input.budget.maxBytes})`);
+    if (input.budget.maxMs !== undefined &&
+        stats.elapsedMs !== undefined &&
+        stats.elapsedMs > input.budget.maxMs)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.elapsedMs}ms (budget ${input.budget.maxMs}ms)`);
+    return issues;
+}
+export const FRONTEND_DESIGN_TERMINAL_TOOL_NAMES = new Set([
+    "approve_design",
+    "request_design_changes",
+]);
+/**
+ * Fail-closed scanner for the two committed design terminal tools. Mirrors the
+ * review scanner: an unparseable line never counts as a terminal fact, so a
+ * corrupt/empty log cannot inflate the typed verdict.
+ */
+export function scanDesignTerminalKindsFromSessionEvents(content) {
+    const kinds = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_DESIGN_TERMINAL_TOOL_NAMES.has(event.toolName)) {
+            kinds.push(event.toolName);
+        }
+    }
+    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");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.String({
+            description: "Critical | Important | Minor | Info",
+        }),
+        file: Type.Optional(Type.String({})),
+        line: Type.Optional(Type.Number({})),
+        issue: Type.String({}),
+        requiredChange: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const approveParameters = Type.Object({
+        findings: 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({}), {
+            description: "Evidence refs (paths or artifact ids); at least one",
+        }),
+        findings: Type.Array(findingSchema, {
+            description: "At least one finding",
+        }),
+    }, { additionalProperties: false });
+    async function adoptReviewFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            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: 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: params?.findings,
+            });
+        },
+    });
+    return {
+        customTools: [approveReviewTool, requestReviewChangesTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "review-typed-facts.jsonl"), committed);
+        },
+    };
+}
+/**
+ * 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");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.String({
+            description: "Critical | Important | Minor | Info",
+        }),
+        file: Type.Optional(Type.String({})),
+        line: Type.Optional(Type.Number({})),
+        issue: Type.String({}),
+        requiredChange: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const approveParameters = Type.Object({
+        findings: 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({}), {
+            description: "Evidence refs (paths or artifact ids); at least one",
+        }),
+        findings: Type.Array(findingSchema, {
+            description: "At least one finding",
+        }),
+    }, { additionalProperties: false });
+    async function adoptDesignFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            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: 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: params?.findings,
+            });
+        },
+    });
+    return {
+        customTools: [approveDesignTool, requestDesignChangesTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "design-typed-facts.jsonl"), committed);
+        },
+    };
+}
+/**
+ * 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, {
+                ...(sourceFragmentIds ? { sourceFragmentIds } : {}),
+                ...(sourceRefs ? { sourceRefs } : {}),
+            });
+        }
+    }
+    return byId;
+}
+/**
+ * Resolve task-source citations from the source-fidelity ledger before the
+ * planner starts. The planner names a frozen requirement id and one of its
+ * fragment ids; it never needs to re-read a PRD merely to recover a
+ * path/section/line triple.
+ */
+async function resolveFrontendPlanNewComponentSourceReferences(input) {
+    const binding = input.sourceBinding;
+    if (!binding || binding.schemaVersion !== 2)
+        return new Map();
+    const ledgerPath = binding.ledgerPath;
+    const absolutePath = path.resolve(input.cwd, ledgerPath);
+    const workspaceRoot = path.resolve(input.cwd);
+    if (absolutePath !== workspaceRoot &&
+        !absolutePath.startsWith(`${workspaceRoot}${path.sep}`)) {
+        return new Map();
+    }
+    try {
+        const ledger = parseLedgerJson(await readFile(absolutePath, "utf8"));
+        const fragmentsById = new Map(ledger.fragments.map((fragment) => [fragment.id, fragment]));
+        const references = new Map();
+        for (const requirement of ledger.canonicalRequirements) {
+            const citations = requirement.sourceFragmentIds
+                .map((fragmentId) => fragmentsById.get(fragmentId))
+                .filter((fragment) => fragment !== undefined)
+                .map((fragment) => ({
+                fragmentId: fragment.id,
+                path: fragment.path,
+                section: fragment.headingPath,
+                line: fragment.lineRange.start,
+            }));
+            if (citations.length > 0)
+                references.set(requirement.id, citations);
+        }
+        return references;
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * A+B: `frontend-plan-pi` now records its decision ledger through seven
+ * incremental `record_*` tools (origin=plan) and closes with exactly one
+ * `finalize_plan` terminal. A later attempt may explicitly adopt a quarantined
+ * fact via `adopt_staged_fact`. Flush writes `plan-typed-facts.jsonl` for the
+ * node validator / compile authority.
+ */
+export async function createFrontendPlanLedgerTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    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-shadow-dual-write.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    let activeRequirementScope = [];
+    const scopedRequirementIds = () => [...activeRequirementScope];
+    // A retry creates a fresh executor-local store, but the plan ledger is the
+    // cross-attempt authority. Restore the committed prefix before registering
+    // tools; otherwise the first flush of a retry can overwrite facts that the
+    // previous attempt had already committed. The on-disk file contains only
+    // committed records, so loading it is also fail-closed with respect to
+    // staged/quarantined facts.
+    const persisted = await loadTypedEventStore(path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"));
+    if (persisted.records.length > 0) {
+        const existingEventIds = new Set(store.records.map((record) => record.eventId));
+        for (const record of persisted.records) {
+            if (!existingEventIds.has(record.eventId)) {
+                store.records.push(record);
+            }
+        }
+        store.revision = Math.max(store.revision, persisted.revision);
+    }
+    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: 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.String({
+            description: "GET | POST | PUT | PATCH | DELETE | HEAD | 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.Number({})),
+        }, { additionalProperties: false })),
+        rationale: Type.String({}),
+    }, { 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,
+    });
+    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 shadow 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 recordComponentChoiceTool = defineTool({
+        name: "record_component_choice",
+        label: "record_component_choice",
+        description: "Record ONE component choice (origin=plan component-choice fact). Declare every UI purpose's component selection. 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 (e.g. reusing ActiveRunBadge's styling convention). Omit rationale for reuse-existing; it is optional. Call up to 5 component choices per assistant message (batching reduces API round trips and rate-limit risk); 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\"}, \"sourceRequirementIds\": [\"<AC-XXX mandating this component>\"], \"sourceFragmentId\": \"<REQ-SRC-...>\"}",
+        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 } : {}),
+                };
+            }
+            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);
+        },
+    });
+    const recordStateFlowTool = defineTool({
+        name: "record_state_flow",
+        label: "record_state_flow",
+        description: "Record UI states and interactions as an origin=plan state-flow fact. 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 });
+            }
+            const states = uiStates
+                .map((state) => (typeof state?.name === "string" ? state.name : ""))
+                .filter(Boolean);
+            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 }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const result = await adoptPlanFact("data-flow", `${attemptId}:record_data_flow:${randomUUID()}`, {
+                kind: "data-flow",
+                origin: "plan",
+                interactions: stringList(params?.interactions),
+                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 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. For a correction, re-submit the same id with replace=true; the ledger compiles the latest replacement. Entry carries id, implementationTargets, verificationTargetIds, 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>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}}",
+        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 (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`,
+                    });
+                }
+            }
+            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 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 need a test file whose describe/it/test title contains the target id). 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 behavior target id is the stable trace token that implementation must place in a real describe/it/test title. 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\": []}}",
+        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}"`,
+                    });
+                }
+            }
+            // 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));
+            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 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. Call exactly once.",
+        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 fragment = assemblePlanPatchFromCommittedFacts(committed, contractInheritance) ?? {};
+                const patch = {
+                    ...fragment,
+                    ...(params?.residualRisks
+                        ? { residualRisks: params.residualRisks }
+                        : {}),
+                    ...(params?.realIntegrationGap
+                        ? { realIntegrationGap: params.realIntegrationGap }
+                        : {}),
+                };
+                // 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 ready-to-submit record_component_choice
+                            // call. One reuse-existing choice covers all
+                            // behavioural interactions.
+                            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",
+                                    },
+                                },
+                            }));
+                            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,
+                });
+            }
+        },
+    });
+    return {
+        customTools: [
+            recordRouteSelectionTool,
+            recordComponentChoiceTool,
+            recordStateFlowTool,
+            recordDataFlowTool,
+            recordMockApiTool,
+            recordDesignDeviationTool,
+            recordDependencyTool,
+            recordPlanRequirementTool,
+            recordPlanVerificationTargetTool,
+            recordPlanEvidenceGapTool,
+            adoptStagedFactTool,
+            finalizePlanTool,
+        ],
+        setActiveRequirementScope: (requirementIds) => {
+            activeRequirementScope = [
+                ...new Set(requirementIds.filter((id) => id.trim().length > 0)),
+            ];
+        },
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), committed);
+        },
+        committedFactCount: () => readCommittedEvents(store, attemptId).length,
+        committedRequirementIds: () => {
+            const ids = new Set();
+            for (const event of readCommittedEvents(store, attemptId)) {
+                const fact = event.fact;
+                if (!fact || fact.kind !== "plan-requirement")
+                    continue;
+                const entryFact = fact.entry;
+                if (typeof entryFact?.id === "string")
+                    ids.add(entryFact.id);
+            }
+            return ids;
+        },
+        committedFacts: () => readCommittedEvents(store, attemptId),
+    };
+}
+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 (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"),
+        handoffIntents: byKind("handoff-intent"),
+        openQuestions: byKind("open-question"),
+        splitProposals: byKind("split-proposal"),
+        unmappedSourceSegments,
+    };
+}
+/**
+ * A+B: `frontend-contract-pi` incremental contract tools. Six `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");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    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_requirement: "requirement",
+        record_constraint: "constraint",
+        record_evidence_expectation: "evidence-expectation",
+        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({}, { additionalProperties: true }),
+        async execute(_toolCallId, params) {
+            const result = await adoptContractFact(kind, {
+                kind,
+                origin: "contract",
+                ...(params ?? {}),
+            });
+            return receipt(result);
+        },
+    }));
+    // 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). Call exactly once.",
+        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)",
+                });
+            }
+            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);
+        },
+    });
+    return {
+        customTools: [
+            ...recordTools,
+            recordOpenspecSelectionTool,
+            finalizeContractTool,
+        ],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "contract-typed-facts.jsonl"), committed);
+            await writeJsonAtomic(path.join(input.runDir, input.nodeId, "frontend-task-contract-vNext.json"), buildFrontendTaskContractVNext(committed));
+        },
+    };
+}
+async function resolveFrontendScoutSourceDeclaredPaths(input) {
+    const binding = input.spec.sourceBinding;
+    if (!binding?.sources?.length)
+        return undefined;
+    const declared = new Set();
+    const pathToken = /(?:\.?\.?\/)?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\/?/g;
+    const writerPaths = input.spec.tasks
+        .filter((task) => task.executor === "pi" && task.toolProfile === "write")
+        .flatMap((task) => task.allowedPaths ?? []);
+    const prefixes = writerPaths
+        .map((pattern) => pattern.replaceAll("\\", "/").replace(/^\.\//, ""))
+        .map((pattern) => pattern.slice(0, pattern.search(/[!*?[{]/) >= 0 ? pattern.search(/[!*?[{]/) : pattern.length))
+        .map((prefix) => prefix.slice(0, prefix.lastIndexOf("/") + 1))
+        .filter(Boolean);
+    for (const source of binding.sources) {
+        try {
+            const text = await readFile(path.resolve(input.cwd, source.path), "utf8");
+            for (const match of text.matchAll(pathToken)) {
+                const token = match[0].replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+                if (!token || token.startsWith("http") || token.startsWith("api/"))
+                    continue;
+                declared.add(token);
+                for (const prefix of prefixes) {
+                    if (!token.startsWith(prefix) && !token.startsWith(".harness/"))
+                        declared.add(`${prefix}${token}`);
+                }
+            }
+        }
+        catch {
+            // The source binding itself remains the authority; an unreadable source
+            // produces an empty declaration set, so future test paths fail closed.
+        }
+    }
+    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");
+    const 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;
+    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),
+            };
+        }
     }
-    return tools;
+    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({
+            completeness: scoutCompleteness,
+            entrypoint: optionalString,
+            routeOrMount: optionalString,
+            implementationPaths: stringArray,
+            testPaths: stringArray,
+            dataSource: optionalString,
+            allowedPathConflicts: stringArray,
+            unresolvedPaths: stringArray,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const implementationPaths = params?.implementationPaths ?? [];
+            const testPaths = params?.testPaths ?? [];
+            const pathEvidence = await enrichScoutPathEvidence([
+                ...(params?.entrypoint ? [params.entrypoint] : []),
+                ...implementationPaths,
+                ...testPaths,
+            ]);
+            const result = await adoptScoutFact("target-surface", {
+                kind: "target-surface",
+                origin: "scout",
+                completeness: params?.completeness ?? "blocked",
+                entrypoint: params?.entrypoint ?? "",
+                routeOrMount: params?.routeOrMount ?? "",
+                implementationPaths,
+                testPaths,
+                dataSource: params?.dataSource ?? "",
+                allowedPathConflicts: params?.allowedPathConflicts ?? [],
+                unresolvedPaths: params?.unresolvedPaths ?? [],
+                ...(hasSourceDeclarations ? { sourceDeclaredPaths } : {}),
+                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
+            });
+            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);
+        },
+    });
+    return {
+        customTools: [recordTargetSurfaceTool, recordDesignEvidenceTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "scout-typed-facts.jsonl"), committed);
+        },
+    };
 }
 export function buildDagPiUserMessage(task, persona, step) {
     const role = task.role ?? "unspecified";
     const writePolicy = task.writePolicy ?? "read-only (default)";
     if (isDagPiWriteTask(task)) {
-        const outcomeInstruction = task.writerOutcomePolicy
+        const outcomeInstruction = isFrontendFactsWriter(task)
             ? [
-                "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. The runner measures your diff mechanically from git status snapshots taken before and after this node: code pasted into the response text is NOT an implementation and yields an empty diff. Use changed only after actually calling write/edit tools that persist files to disk; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed. Claiming changed without a persisted diff fails this node as invalid-output.",
-                task.writerOutcomePolicy.requireChangedFiles
-                    ? "This generation node requires a non-empty bounded diff; already-satisfied cannot complete it successfully."
-                    : undefined,
+                "Your implementation status is derived by the executor from mechanical facts (persisted write-tool events, run delta, write guard, requirement coverage, focused-check failures) — never from an IMPLEMENTATION_OUTCOME first line. Do not emit an IMPLEMENTATION_OUTCOME first line. Make real write/edit tool calls that persist files to disk: a response-only change is an empty diff that fails this node. If the contract is already satisfied, prove it with concrete target/verification evidence; a bare self-report cannot authorize an empty implementation.",
             ]
                 .filter((value) => Boolean(value))
                 .join(" ")
-            : undefined;
+            : task.writerOutcomePolicy
+                ? [
+                    "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. The runner measures your diff mechanically from git status snapshots taken before and after this node: code pasted into the response text is NOT an implementation and yields an empty diff. Use changed only after actually calling write/edit tools that persist files to disk; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed. Claiming changed without a persisted diff fails this node as invalid-output.",
+                    task.writerOutcomePolicy.requireChangedFiles
+                        ? "This generation node requires a non-empty bounded diff; already-satisfied cannot complete it successfully."
+                        : undefined,
+                ]
+                    .filter((value) => Boolean(value))
+                    .join(" ")
+                : undefined;
         return [
             `You are executing hybrid DAG node "${task.id}" (role=${role}, piStep=${step}, writePolicy=${writePolicy}).`,
             "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
@@ -399,30 +2502,1350 @@ async function resolveValidatedFrontendBaseUrlFromContext(workspaceRoot, runDir)
             break;
         }
     }
-    if (!rawBaseUrl || !/environmentProbe\s*[:=]\s*reachable/i.test(markdown)) {
-        throw new Error("browser-command-capability-unavailable: frontend context URL is missing or not environment-validated");
-    }
-    let parsed;
-    try {
-        parsed = new URL(rawBaseUrl);
-    }
-    catch {
-        throw new Error("browser-command-capability-unavailable: invalid frontend context origin");
-    }
-    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
-        parsed.username ||
-        parsed.password ||
-        parsed.search ||
-        parsed.hash ||
-        /(?:^|\.)(?:www\.)?[^.]*(?:prod|production)/i.test(parsed.hostname)) {
-        throw new Error("browser-command-capability-unavailable: unsafe frontend context origin");
+    if (!rawBaseUrl || !/environmentProbe\s*[:=]\s*reachable/i.test(markdown)) {
+        throw new Error("browser-command-capability-unavailable: frontend context URL is missing or not environment-validated");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawBaseUrl);
+    }
+    catch {
+        throw new Error("browser-command-capability-unavailable: invalid frontend context origin");
+    }
+    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash ||
+        /(?:^|\.)(?:www\.)?[^.]*(?:prod|production)/i.test(parsed.hostname)) {
+        throw new Error("browser-command-capability-unavailable: unsafe frontend context origin");
+    }
+    return parsed.toString();
+}
+const DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES = {
+    readGitStatusPorcelain,
+    recoverRootNulArtifact,
+};
+/**
+ * M5 shadow pass for `frontend-review-pi`: extract the committed typed terminal
+ * facts from session events, parse the legacy JSON verdict from the response
+ * text, compare them (audit-only), and persist the audit artifact. Missing
+ * typed terminal facts fail the node closed (AC-001); a shadow mismatch never
+ * blocks the node.
+ */
+async function runFrontendReviewTerminalShadow(input) {
+    // A provider/executor failure (in particular context-overflow) is already
+    // authoritative. Do not rewrite it to review-terminal-missing merely
+    // because no terminal tool could be submitted after the failed call.
+    if (!input.mapped.ok)
+        return input.mapped;
+    const { compareTypedReviewToLegacyJsonVerdict } = await import("../workflows/dag/frontend-review-context.js");
+    const { parseJsonReviewVerdict } = await import("../workflows/dag/output-protocol.js");
+    const sessionEventsPath = path.join(input.meta.runDir, input.task.id, "session-events.jsonl");
+    let typedKinds = [];
+    try {
+        const content = await readFile(sessionEventsPath, "utf8");
+        typedKinds = scanReviewTerminalKindsFromSessionEvents(content);
+    }
+    catch {
+        // Missing/unreadable session log → fail-closed at zero terminal facts.
+        typedKinds = [];
+    }
+    let legacyVerdict;
+    try {
+        const parsed = parseJsonReviewVerdict(input.mapped.assistantText ?? input.mapped.stdout);
+        if (parsed.ok)
+            legacyVerdict = parsed.verdict;
+    }
+    catch {
+        legacyVerdict = undefined;
+    }
+    let comparison;
+    try {
+        comparison = compareTypedReviewToLegacyJsonVerdict({
+            typedKinds,
+            legacyVerdict,
+        });
+    }
+    catch (error) {
+        comparison = {
+            typedVerdict: undefined,
+            legacyVerdict: undefined,
+            match: false,
+            reason: `typed review equivalence comparison crashed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // Audit-only flush + artifact. Neither blocks the node.
+    try {
+        await input.tools?.flush?.();
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        await writeDagNodeJsonArtifact(input.meta.runDir, input.task.id, "fact-review-status.json", {
+            schemaVersion: 1,
+            nodeId: input.task.id,
+            typedKinds,
+            legacyVerdict,
+            comparison,
+        });
+    }
+    catch {
+        // best-effort audit artifact
+    }
+    if (typedKinds.length === 0) {
+        return {
+            ...input.mapped,
+            ok: false,
+            failureCategory: "review-terminal-missing",
+            stderr: [
+                input.mapped.stderr,
+                "frontend review typed terminal fact missing: no approve_review/request_review_changes tool call was committed",
+            ]
+                .filter(Boolean)
+                .join("\n\n"),
+        };
+    }
+    return input.mapped;
+}
+/**
+ * M8 shadow pass for `frontend-design-review-pi`: extract the committed typed
+ * design terminal facts from session events, flush them, and persist the audit
+ * artifact. The design review's legacy output was a first-line
+ * `VERDICT: pass|request-revision` text protocol (not a JSON verdict), so
+ * there is no JSON equivalence comparison here. Missing typed terminal facts
+ * fail the node closed; writer admission later reads the committed
+ * `design-typed-facts.jsonl` as the only authoritative verdict.
+ */
+async function runFrontendDesignTerminalShadow(input) {
+    // See the review counterpart above: a failed provider call cannot be
+    // diagnosed as an omitted terminal tool call.
+    if (!input.mapped.ok)
+        return input.mapped;
+    const sessionEventsPath = path.join(input.meta.runDir, input.task.id, "session-events.jsonl");
+    let typedKinds = [];
+    try {
+        const content = await readFile(sessionEventsPath, "utf8");
+        typedKinds = scanDesignTerminalKindsFromSessionEvents(content);
+    }
+    catch {
+        // Missing/unreadable session log → fail-closed at zero terminal facts.
+        typedKinds = [];
+    }
+    // Audit-only flush + artifact. Neither blocks the node.
+    try {
+        await input.tools?.flush?.();
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        await writeDagNodeJsonArtifact(input.meta.runDir, input.task.id, "fact-design-status.json", {
+            schemaVersion: 1,
+            nodeId: input.task.id,
+            typedKinds,
+        });
+    }
+    catch {
+        // best-effort audit artifact
+    }
+    if (typedKinds.length === 0) {
+        return {
+            ...input.mapped,
+            ok: false,
+            failureCategory: "design-terminal-missing",
+            stderr: [
+                input.mapped.stderr,
+                "frontend design typed terminal fact missing: no approve_design/request_design_changes tool call was committed",
+            ]
+                .filter(Boolean)
+                .join("\n\n"),
+        };
+    }
+    return input.mapped;
+}
+/** Tool subsets for the frontend plan phases. Local UX decisions and global
+ * policies intentionally have different sessions and different tool sets. */
+const FRONTEND_PLAN_SEGMENTS = [
+    {
+        id: "coverage",
+        toolNames: new Set([
+            "record_plan_requirement",
+            "record_plan_verification_target",
+            "record_plan_evidence_gap",
+            "adopt_staged_fact",
+        ]),
+        instruction: [
+            "PLAN PHASE — requirement coverage only.",
+            "Your ONLY job: for every frozen requirement, emit record_plan_requirement (requirement → implementation files) and record_plan_verification_target facts (verification target bound to requirement ids and files). Group related requirements under one non-static behavior target when one observable test behavior proves them together; do not mechanically create one target per requirement. A non-static target id is the stable machine trace token; never submit prose as a symbol. Do NOT record components, UI states, mock, dependency, or routes — a follow-up session owns those.",
+            "If a requirement genuinely cannot have a verification target, record a non-empty record_plan_evidence_gap. Do not call finalize_plan; it is not available in this phase.",
+        ].join(" "),
+    },
+    {
+        id: "ux-local",
+        toolNames: new Set([
+            "record_component_choice",
+            "record_state_flow",
+            "adopt_staged_fact",
+        ]),
+        instruction: [
+            "PLAN PHASE — requirement-local UX decisions.",
+            "Requirements and verification targets are already committed in the ledger (do NOT re-record them; duplicates are rejected). For ONLY this requirement slice, record component choices and UI state flow. Keep these facts for this slice together. Cross-cutting data flow belongs to the global Mock/data phase. Do not record routes, Mock/API policy, dependencies, or design deviations here.",
+            "Do not call finalize_plan; it is not available in this phase.",
+        ].join(" "),
+    },
+    {
+        id: "global-route",
+        toolNames: new Set(["record_route_selection", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global route decision.",
+            "Use the Scout target surface and record only the selected route(s). Do not record requirement-local UX, Mock/data, dependency, or deviation facts. Do not call finalize_plan.",
+        ].join(" "),
+    },
+    {
+        id: "global-mock-data",
+        toolNames: new Set(["record_data_flow", "record_mock_api", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global Mock/API and data policy.",
+            "Record the cross-cutting interaction-to-endpoint data flow and Mock/API strategy only. Keep this decision set separate from route, component, state, dependency, and deviation facts. Do not call finalize_plan.",
+        ].join(" "),
+    },
+    {
+        id: "global-dependency-deviation",
+        toolNames: new Set(["record_dependency", "record_design_deviation", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global dependency and design-deviation policy.",
+            "Record only dependency policy and design-evidence conflicts. Do not record route, Mock/data, or requirement-local UX facts. Do not call finalize_plan.",
+        ].join(" "),
+    },
+    {
+        id: "finalize",
+        toolNames: null,
+        instruction: [
+            "PLAN PHASE — finalize.",
+            "All record_* tools are available only for a narrowly named correction if the finalize receipt reports missing or invalid facts. Otherwise call finalize_plan exactly once with no extra fields.",
+        ].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));
+}
+/** Apply state-flow replacement/removal semantics exactly as the plan compiler does. */
+function collectCanonicalStateFlowNames(committedFacts) {
+    const uiStateNames = new Set();
+    const interactionNames = new Set();
+    for (const value of committedFacts) {
+        const fact = committedFactFromPlanRecord(value);
+        if (!fact || fact.origin !== "plan" || fact.kind !== "state-flow")
+            continue;
+        for (const name of planFactStringList(fact.removeUiStateNames)) {
+            uiStateNames.delete(name);
+        }
+        for (const name of planFactStringList(fact.removeInteractionNames)) {
+            interactionNames.delete(name);
+        }
+        for (const state of Array.isArray(fact.uiStates) ? fact.uiStates : []) {
+            if (!state || typeof state !== "object" || Array.isArray(state))
+                continue;
+            const name = state.name;
+            if (typeof name === "string" && name.trim())
+                uiStateNames.add(name);
+        }
+        for (const interaction of Array.isArray(fact.interactions)
+            ? fact.interactions
+            : []) {
+            if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) {
+                continue;
+            }
+            const name = interaction.name;
+            if (typeof name === "string" && name.trim())
+                interactionNames.add(name);
+        }
+    }
+    return { uiStateNames, interactionNames };
+}
+/** 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;
+        }
+        const targetIds = Array.isArray(entry.verificationTargetIds)
+            ? entry.verificationTargetIds.filter((value) => typeof value === "string" && value.trim().length > 0)
+            : [];
+        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-local") {
+        const needsUx = input.requirementIds.some((id) => input.behaviorRequiredRequirementIds?.includes(id));
+        if (!needsUx)
+            return [];
+        const requirementSlice = new Set(input.requirementIds);
+        const scopedFacts = facts.filter((fact) => planFactScopeIntersects(fact, requirementSlice));
+        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;
+        const missing = [];
+        if (!hasChoice) {
+            missing.push({
+                kind: "component-choice",
+                requirementIds: [...input.requirementIds],
+                reason: "behaviour-required UX slice has no committed component-choice fact",
+            });
+        }
+        if (!hasStateFlow) {
+            missing.push({
+                kind: "state-flow",
+                requirementIds: [...input.requirementIds],
+                reason: "behaviour-required UX slice has no committed state-flow fact",
+            });
+        }
+        return missing;
+    }
+    const hasMockApi = facts.some((fact) => fact.kind === "mock-api");
+    const liveInteractions = collectCanonicalStateFlowNames(input.committedFacts).interactionNames;
+    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) {
+    const record = fact && typeof fact === "object" && !Array.isArray(fact)
+        ? fact
+        : {};
+    const declaredTargetCount = Array.isArray(record.verificationTargetIds)
+        ? record.verificationTargetIds.filter((value) => typeof value === "string" && value.trim()).length
+        : Array.isArray(record.verificationTargets)
+            ? record.verificationTargets.length
+            : 0;
+    const evidence = record.evidence && typeof record.evidence === "object"
+        ? record.evidence
+        : undefined;
+    const targetCount = Math.max(declaredTargetCount, evidence?.behavior === "required" ? 2 : 1);
+    return 1 + targetCount;
+}
+/** Pack requirements without splitting one requirement across sessions. */
+export function batchFrontendPlanRequirements(input) {
+    const batches = [];
+    let current = [];
+    let currentCost = 0;
+    for (const id of input.requirementIds) {
+        const cost = Math.max(1, input.requirementCosts?.get(id) ?? 2);
+        if (current.length > 0 &&
+            (currentCost + cost > input.maxEstimatedRecordCalls ||
+                (input.maxRequirements !== undefined &&
+                    current.length >= input.maxRequirements))) {
+            batches.push(current);
+            current = [];
+            currentCost = 0;
+        }
+        current.push(id);
+        currentCost += cost;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+const FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS = 10;
+const FRONTEND_PLAN_UX_LOCAL_MAX_RECORD_CALLS = 6;
+// A large requirement set creates both coverage and UX-local shards. Keep a
+// safety bound, but do not let the old 32-session ceiling skip finalize for a
+// legitimate large plan.
+const FRONTEND_PLAN_BATCH_MAX_SESSIONS = 128;
+const FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS = 8;
+const FRONTEND_PLAN_SMALL_MAX_ESTIMATED_CALLS = 24;
+function compactPromptString(value, maxChars) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length <= maxChars
+        ? normalized
+        : `${normalized.slice(0, maxChars - 1)}…`;
+}
+function compactPromptStringArray(value, maxEntries = 12, maxChars = 180) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => compactPromptString(item, maxChars))
+        .filter((item) => item !== undefined)
+        .slice(0, maxEntries);
+}
+function countFrontendPlanTargetSurfaces(basePrompt) {
+    const match = /<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/.exec(basePrompt);
+    if (!match)
+        return undefined;
+    for (const line of match[0].split(/\r?\n/)) {
+        try {
+            const payload = JSON.parse(line);
+            if (Array.isArray(payload.targetSurface))
+                return payload.targetSurface.length;
+        }
+        catch {
+            // surrounding lines are prose
+        }
+    }
+    return undefined;
+}
+/**
+ * Deterministically extract repository file paths that frozen verification
+ * commands operate on (`--config <file>`, `node --check <file>`). A frozen
+ * command whose referenced file is outside the planner's verification targets
+ * can never run: the admission writeSet derives from those targets, so the
+ * writer is not authorized to create the file and verify-shell fails ~20
+ * minutes later. Surfacing the gap as plan missing-facts lets the coverage or
+ * compact session record the missing verification target inside the same
+ * attempt instead.
+ */
+export function collectFrontendVerificationCommandFiles(basePrompt) {
+    const files = new Set();
+    const configRe = /--config\s+([\w@./-]+\.(?:js|mjs|cjs|ts|json))/g;
+    const checkRe = /node\s+--check\s+([\w@./-]+\.(?:js|mjs|cjs))/g;
+    for (const re of [configRe, checkRe]) {
+        for (const match of basePrompt.matchAll(re)) {
+            const file = match[1];
+            if (file && file.includes("/"))
+                files.add(file);
+        }
+    }
+    return [...files].sort();
+}
+/**
+ * Remove the repeated full planner input from a coverage batch. The normal
+ * plan prompt already contains a bounded JSON handoff, but repeating all
+ * requirements and the upstream preview once per batch still makes the
+ * provider spend its output budget reasoning about work owned by other
+ * sessions. If the handoff is absent, malformed, or missing a requested id,
+ * preserve the old prompt as a safe compatibility fallback rather than
+ * silently giving the model an incomplete requirement.
+ */
+export function compactFrontendPlanPromptForRequirementSlice(basePrompt, requirementIds, options = {}) {
+    const slice = [...new Set(requirementIds.filter((id) => id.trim().length > 0))];
+    if (slice.length === 0)
+        return basePrompt;
+    const planInputPattern = /<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/;
+    const planInputMatch = planInputPattern.exec(basePrompt);
+    if (!planInputMatch)
+        return basePrompt;
+    const blockLines = planInputMatch[0].split(/\r?\n/);
+    let payload;
+    for (const line of blockLines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                payload = parsed;
+                break;
+            }
+        }
+        catch {
+            // The surrounding block contains prose; only its JSON line is data.
+        }
+    }
+    if (!payload || !Array.isArray(payload.requirements))
+        return basePrompt;
+    const requirementsById = new Map();
+    for (const value of payload.requirements) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const requirement = value;
+        if (typeof requirement.id === "string") {
+            requirementsById.set(requirement.id, requirement);
+        }
+    }
+    const requirements = slice.map((id) => requirementsById.get(id));
+    if (requirements.some((requirement) => requirement === undefined)) {
+        return basePrompt;
+    }
+    const compactRequirements = requirements.map((requirement) => ({
+        id: compactPromptString(requirement.id, 80),
+        ...(options.includeRequirementText !== false && compactPromptString(requirement.text, 240)
+            ? { text: compactPromptString(requirement.text, 240) }
+            : {}),
+        sourceFragmentIds: compactPromptStringArray(requirement.sourceFragmentIds, 20, 80),
+    }));
+    const sliceSet = new Set(slice);
+    const compactVerificationTargets = options.includeVerificationTargets === false
+        ? []
+        : Array.isArray(payload.verificationTargets)
+            ? payload.verificationTargets.flatMap((value) => {
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    return [];
+                const target = value;
+                const targetRequirementIds = compactPromptStringArray(target.requirementIds, 20, 80);
+                const relatedRequirementIds = targetRequirementIds.filter((id) => sliceSet.has(id));
+                if (relatedRequirementIds.length === 0)
+                    return [];
+                return [
+                    {
+                        ...(compactPromptString(target.id, 80)
+                            ? { id: compactPromptString(target.id, 80) }
+                            : {}),
+                        ...(compactPromptString(target.commandId, 80)
+                            ? { commandId: compactPromptString(target.commandId, 80) }
+                            : {}),
+                        ...(compactPromptString(target.commandLabel, 180)
+                            ? { commandLabel: compactPromptString(target.commandLabel, 180) }
+                            : {}),
+                        ...(compactPromptString(target.file, 180)
+                            ? { file: compactPromptString(target.file, 180) }
+                            : {}),
+                        requirementIds: relatedRequirementIds,
+                        uiStates: compactPromptStringArray(target.uiStates, 12, 100),
+                    },
+                ];
+            })
+            : [];
+    const compactTargetSurface = Array.isArray(payload.targetSurface)
+        ? payload.targetSurface.flatMap((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [];
+            const surface = value;
+            return [
+                {
+                    ...(compactPromptString(surface.completeness, 32)
+                        ? { completeness: compactPromptString(surface.completeness, 32) }
+                        : {}),
+                    ...(compactPromptString(surface.entrypoint, 180)
+                        ? { entrypoint: compactPromptString(surface.entrypoint, 180) }
+                        : {}),
+                    ...(compactPromptString(surface.routeOrMount, 180)
+                        ? { routeOrMount: compactPromptString(surface.routeOrMount, 180) }
+                        : {}),
+                    implementationPaths: compactPromptStringArray(surface.implementationPaths),
+                    testPaths: compactPromptStringArray(surface.testPaths),
+                    ...(compactPromptString(surface.dataSource, 180)
+                        ? { dataSource: compactPromptString(surface.dataSource, 180) }
+                        : {}),
+                    allowedPathConflicts: compactPromptStringArray(surface.allowedPathConflicts),
+                    unresolvedPaths: compactPromptStringArray(surface.unresolvedPaths),
+                },
+            ];
+        })
+        : [];
+    const compactDesignEvidence = options.includeDesignEvidence === true &&
+        Array.isArray(payload.designEvidence)
+        ? payload.designEvidence.flatMap((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [];
+            const evidence = value;
+            return [{
+                    ...(compactPromptString(evidence.source, 180)
+                        ? { source: compactPromptString(evidence.source, 180) }
+                        : {}),
+                    paths: compactPromptStringArray(evidence.paths, 12, 180),
+                    conflicts: compactPromptStringArray(evidence.conflicts, 24, 180),
+                }];
+        })
+        : [];
+    const compactPayload = {
+        requirements: compactRequirements,
+        ...(compactTargetSurface.length > 0
+            ? { targetSurface: compactTargetSurface }
+            : {}),
+        ...(compactVerificationTargets.length > 0
+            ? { verificationTargets: compactVerificationTargets }
+            : {}),
+        ...(compactDesignEvidence.length > 0
+            ? { designEvidence: compactDesignEvidence }
+            : {}),
+    };
+    const compactBlock = [
+        "<frontend_plan_input>",
+        `Committed Contract/Scout facts for ONLY the current requirement slice (${slice.join(", ")}); do not infer or record requirements outside this slice.`,
+        JSON.stringify(compactPayload),
+        "Do not read upstream artifacts, task sources, or repository files. If this slice cannot support a decision, record a genuine evidence gap.",
+        "</frontend_plan_input>",
+    ].join("\n");
+    let compactPrompt = basePrompt.replace(planInputPattern, compactBlock);
+    compactPrompt = compactPrompt.replace(/<upstream_context>[\s\S]*?<\/upstream_context>/, "<upstream_context>\n(full upstream prose omitted; use only the slice-specific typed facts above)\n</upstream_context>");
+    compactPrompt = compactPrompt.replace(/Cover each frozen requirement ID exactly once:[^\n]*/, `Cover ONLY the current requirement slice: ${slice.join(", ")}. Record each slice requirement exactly once.`);
+    const checklistPattern = /<plan_review_checklist>([\s\S]*?)<\/plan_review_checklist>/;
+    const checklistMatch = checklistPattern.exec(compactPrompt);
+    if (checklistMatch) {
+        if (options.includeChecklist === false) {
+            compactPrompt = compactPrompt.replace(checklistPattern, "");
+            return compactPrompt;
+        }
+        const checklist = checklistMatch[1]
+            .split(/\r?\n/)
+            .filter((line) => {
+            const requirementLine = /^Requirements requiring behavioural coverage:\s*(.*)$/.exec(line.trim());
+            if (requirementLine) {
+                return false;
+            }
+            const citationId = /^([^\s]+)\s+\+/.exec(line.trim())?.[1];
+            return citationId === undefined || sliceSet.has(citationId);
+        })
+            .concat([`Requirements requiring behavioural coverage: ${slice.join(", ") || "(none)"}`])
+            .join("\n");
+        compactPrompt = compactPrompt.replace(checklistPattern, `<plan_review_checklist>${checklist}</plan_review_checklist>`);
+    }
+    return compactPrompt;
+}
+function compactFrontendPlanLedgerContext(input) {
+    const slice = new Set(input.requirementIds);
+    const allowed = new Set(input.kinds);
+    const scopedKinds = new Set(input.scopedKinds ?? []);
+    const compactFacts = [];
+    for (const value of input.committedFacts) {
+        const fact = committedFactFromPlanRecord(value);
+        if (!fact || fact.origin !== "plan" || typeof fact.kind !== "string" || !allowed.has(fact.kind))
+            continue;
+        if (scopedKinds.has(fact.kind) && !planFactScopeIntersects(fact, slice)) {
+            continue;
+        }
+        const entry = fact.entry && typeof fact.entry === "object" && !Array.isArray(fact.entry)
+            ? fact.entry
+            : undefined;
+        if (fact.kind === "plan-requirement") {
+            if (!entry || typeof entry.id !== "string" || !slice.has(entry.id))
+                continue;
+            compactFacts.push({
+                kind: fact.kind,
+                entry: {
+                    id: compactPromptString(entry.id, 80),
+                    implementationTargets: compactPromptStringArray(entry.implementationTargets, 12, 180),
+                    verificationTargetIds: compactPromptStringArray(entry.verificationTargetIds, 12, 80),
+                    ...(compactPromptString(entry.expectedOutcome, 240)
+                        ? { expectedOutcome: compactPromptString(entry.expectedOutcome, 240) }
+                        : {}),
+                    ...(entry.evidenceGap && typeof entry.evidenceGap === "object"
+                        ? { evidenceGap: entry.evidenceGap }
+                        : {}),
+                },
+            });
+            continue;
+        }
+        if (fact.kind === "plan-verification-target") {
+            if (!entry)
+                continue;
+            const requirementIds = compactPromptStringArray(entry.requirementIds, 20, 80);
+            if (!requirementIds.some((id) => slice.has(id)))
+                continue;
+            compactFacts.push({
+                kind: fact.kind,
+                entry: {
+                    id: compactPromptString(entry.id, 80),
+                    commandId: compactPromptString(entry.commandId, 80),
+                    file: compactPromptString(entry.file, 180),
+                    requirementIds,
+                    uiStates: compactPromptStringArray(entry.uiStates, 12, 100),
+                },
+            });
+            continue;
+        }
+        if (fact.kind === "component-choice") {
+            const choices = Array.isArray(fact.uiComponentChoices)
+                ? fact.uiComponentChoices.flatMap((choice) => {
+                    if (!choice || typeof choice !== "object" || Array.isArray(choice))
+                        return [];
+                    const item = choice;
+                    return [{
+                            purpose: compactPromptString(item.purpose, 120),
+                            component: compactPromptString(item.component, 120),
+                            decision: compactPromptString(item.decision, 40),
+                        }];
+                }).slice(0, 24)
+                : [];
+            if (choices.length > 0)
+                compactFacts.push({ kind: fact.kind, uiComponentChoices: choices });
+            continue;
+        }
+        if (fact.kind === "state-flow") {
+            compactFacts.push({
+                kind: fact.kind,
+                uiStates: Array.isArray(fact.uiStates) ? fact.uiStates.slice(0, 24) : [],
+                interactions: Array.isArray(fact.interactions) ? fact.interactions.slice(0, 24) : [],
+                removeUiStateNames: compactPromptStringArray(fact.removeUiStateNames, 24, 100),
+                removeInteractionNames: compactPromptStringArray(fact.removeInteractionNames, 24, 100),
+            });
+            continue;
+        }
+        if (fact.kind === "data-flow") {
+            compactFacts.push({
+                kind: fact.kind,
+                interactions: compactPromptStringArray(fact.interactions, 32, 120),
+                endpoints: compactPromptStringArray(fact.endpoints, 32, 180),
+            });
+            continue;
+        }
+        if (fact.kind === "mock-api") {
+            const mockApi = fact.mockApi && typeof fact.mockApi === "object" && !Array.isArray(fact.mockApi)
+                ? fact.mockApi
+                : {};
+            compactFacts.push({
+                kind: fact.kind,
+                mockApi: {
+                    strategy: compactPromptString(mockApi.strategy, 40),
+                    activation: compactPromptString(mockApi.activation, 180),
+                    endpoints: Array.isArray(mockApi.endpoints) ? mockApi.endpoints.slice(0, 24) : [],
+                },
+            });
+            continue;
+        }
+        if (fact.kind === "design-deviation") {
+            compactFacts.push({ kind: fact.kind, conflicts: compactPromptStringArray(fact.conflicts, 32, 180) });
+            continue;
+        }
+        if (fact.kind === "dependency") {
+            compactFacts.push({ kind: fact.kind, policy: compactPromptString(fact.policy, 300) });
+            continue;
+        }
+        if (fact.kind === "target-surface") {
+            compactFacts.push({ kind: fact.kind, routes: compactPromptStringArray(fact.routes, 24, 180) });
+        }
+    }
+    if (compactFacts.length === 0)
+        return "";
+    const priorityFacts = compactFacts.filter((fact) => fact.kind === "plan-requirement" || fact.kind === "plan-verification-target");
+    const otherFacts = compactFacts.filter((fact) => fact.kind !== "plan-requirement" && fact.kind !== "plan-verification-target");
+    const boundedFacts = [
+        ...priorityFacts.slice(0, 64),
+        ...otherFacts.slice(-32),
+    ].slice(0, 96);
+    return [
+        "<frontend_plan_ledger>",
+        "Committed plan facts from earlier sessions. Treat these as authoritative; correct them only with the allowed replacement/removal fields.",
+        JSON.stringify(boundedFacts),
+        "</frontend_plan_ledger>",
+    ].join("\n");
+}
+export async function runFrontendPlanSegmentedSessions(input) {
+    const queue = [];
+    const coverageSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "coverage");
+    const uxSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "ux-local");
+    const globalMockDataSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "global-mock-data");
+    const finalizeSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "finalize");
+    const allRequirementIds = input.requirementIds ?? [];
+    const buildPhasePrompt = (segment, missing = []) => {
+        const compact = allRequirementIds.length > 0
+            ? compactFrontendPlanPromptForRequirementSlice(input.basePrompt, allRequirementIds, {
+                includeRequirementText: segment.id === "global-mock-data" || segment.id === "global-dependency-deviation",
+                includeVerificationTargets: false,
+                includeDesignEvidence: segment.id === "global-dependency-deviation" || segment.id === "finalize",
+                includeChecklist: false,
+            })
+            : input.basePrompt;
+        const kinds = segment.id === "global-route"
+            ? ["target-surface"]
+            : segment.id === "global-mock-data"
+                ? ["plan-requirement", "plan-verification-target", "state-flow", "data-flow", "mock-api"]
+                : segment.id === "global-dependency-deviation"
+                    ? ["dependency", "design-deviation"]
+                    : ["plan-requirement", "plan-verification-target", "component-choice", "state-flow", "data-flow", "mock-api", "design-deviation", "dependency", "target-surface"];
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: allRequirementIds,
+                kinds,
+            })
+            : "";
+        return [
+            compact,
+            segment.instruction,
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: repair ONLY these items, then re-check the phase:",
+                    ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const buildCoveragePrompt = (slice, missing = []) => [
+        compactFrontendPlanPromptForRequirementSlice(input.basePrompt, slice),
+        coverageSegment.instruction,
+        `COVERAGE BATCH: process ONLY these requirements in this session: ${slice.join(", ")}. Other requirements are handled by separate sessions; do not record them.`,
+        ...(missing.length > 0
+            ? [
+                "MISSING-FACT QUEUE: the previous session did not establish complete coverage. Repair ONLY these items, then re-check the slice:",
+                ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+            ]
+            : []),
+    ].join("\n\n");
+    const buildUxPrompt = (slice, missing = []) => {
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: slice,
+                kinds: ["plan-requirement", "plan-verification-target", "component-choice", "state-flow"],
+                scopedKinds: ["component-choice", "state-flow"],
+            })
+            : "";
+        return [
+            compactFrontendPlanPromptForRequirementSlice(input.basePrompt, slice),
+            uxSegment.instruction,
+            `UX LOCAL BATCH: process ONLY these requirements: ${slice.join(", ")}.`,
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: repair ONLY these items, then re-check this UX slice:",
+                    ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const buildCompactLocalPrompt = (missing = []) => {
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: allRequirementIds,
+                kinds: [
+                    "plan-requirement",
+                    "plan-verification-target",
+                    "component-choice",
+                    "state-flow",
+                ],
+            })
+            : "";
+        return [
+            compactFrontendPlanPromptForRequirementSlice(input.basePrompt, allRequirementIds),
+            "PLAN PHASE — compact local planning for a small frontend request.",
+            "For every listed requirement, record plan-requirement and verification-target facts, then record the component-choice and state-flow facts needed by the observable UX. Do not read the repository or task source; use only the committed input above. Do not call finalize_plan in this session.",
+            "TOOL-FIRST: your first assistant actions must be record_* tool calls, at most 2-3 facts per message. Do not draft the whole analysis before recording; if a fact is uncertain, record it with an evidence gap instead of reasoning longer.",
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: repair ONLY these items, then re-check the compact local phase:",
+                    ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const compactFinalizeInstruction = "This is a small-request compact pass. Reconcile the committed local facts with route, data-flow, Mock/API, dependency and deviation policy, then call finalize_plan exactly once.";
+    const buildCompactFinalizePrompt = (missing = []) => [buildPhasePrompt(finalizeSegment, missing), compactFinalizeInstruction].join("\n\n");
+    const mapPlannerExhaustion = (r, committedAnyFacts) => isPlannerThinkingExhausted(r, committedAnyFacts)
+        ? {
+            ...r,
+            failureCategory: PLANNER_THINKING_EXHAUSTED_CATEGORY,
+            stderr: `${r.stderr}\n${PLANNER_THINKING_EXHAUSTED_CATEGORY}: stopReason=length, thinking observed, 0 typed facts committed; the batch ladder degraded the scope without converging — set thinking=off for this tier or switch to a non-thinking model`.trim(),
+        }
+        : r;
+    // An empty list means "ledger unreadable / unknown" and falls back to one
+    // unscoped coverage session; a non-empty list enables deterministic sharding.
+    const requirementIdsProvided = input.requirementIds !== undefined && input.requirementIds.length > 0;
+    const pending = (input.requirementIds ?? []).filter((id) => !input.committedRequirementIds?.().has(id));
+    const initialMissing = requirementIdsProvided && input.committedFacts
+        ? collectFrontendPlanMissingFacts({
+            requirementIds: input.requirementIds,
+            committedFacts: input.committedFacts(),
+        })
+        : [];
+    const incompleteRequirementIds = new Set(initialMissing.flatMap((item) => item.requirementIds));
+    const coverageWorkIds = (input.requirementIds ?? []).filter((id) => pending.includes(id) || incompleteRequirementIds.has(id));
+    const estimatedCalls = (input.requirementIds ?? []).reduce((total, id) => total + Math.max(1, input.requirementCosts?.get(id) ?? 2), 0);
+    const targetSurfaceCount = countFrontendPlanTargetSurfaces(input.basePrompt);
+    // Small, single-surface requests do not benefit from six isolated Pi
+    // sessions. Keep the typed ledger as the authority, but let one local
+    // session establish requirement/UX facts and one final session establish
+    // cross-cutting policy + finalize. The old sharded ladder remains available
+    // for larger plans and for the unscoped compatibility path.
+    const useCompactSmallPlan = requirementIdsProvided &&
+        input.compactSmallPlan === true &&
+        input.requirementCosts !== undefined &&
+        estimatedCalls > 12 &&
+        (input.requirementIds?.length ?? 0) <= FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS &&
+        estimatedCalls <= FRONTEND_PLAN_SMALL_MAX_ESTIMATED_CALLS &&
+        targetSurfaceCount === 1;
+    if (useCompactSmallPlan) {
+        const compactLocalTools = new Set([
+            "record_plan_requirement",
+            "record_plan_verification_target",
+            "record_plan_evidence_gap",
+            "record_component_choice",
+            "record_state_flow",
+            "adopt_staged_fact",
+        ]);
+        queue.push({
+            id: "compact-local",
+            toolNames: compactLocalTools,
+            requirementSlice: [...allRequirementIds],
+            prompt: buildCompactLocalPrompt(),
+        });
+        queue.push({
+            id: "finalize",
+            toolNames: null,
+            prompt: buildCompactFinalizePrompt(),
+        });
+    }
+    else if (!requirementIdsProvided) {
+        queue.push({
+            id: "coverage",
+            toolNames: coverageSegment.toolNames,
+            prompt: `${input.basePrompt}\n\n${coverageSegment.instruction}`,
+        });
+    }
+    else if (coverageWorkIds.length > 0) {
+        const coverageBatches = batchFrontendPlanRequirements({
+            requirementIds: coverageWorkIds,
+            maxEstimatedRecordCalls: FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS,
+            maxRequirements: 4,
+            requirementCosts: input.requirementCosts,
+        });
+        coverageBatches.forEach((slice, batchIndex) => queue.push({
+            id: `coverage-batch-${batchIndex + 1}`,
+            toolNames: coverageSegment.toolNames,
+            coverageSlice: slice,
+            coverageOnly: true,
+            prompt: buildCoveragePrompt(slice),
+        }));
+    }
+    if (useCompactSmallPlan) {
+        // Compact mode already queued both sessions above.
+    }
+    else {
+        const uxCosts = new Map((input.requirementIds ?? []).map((id) => [
+            id,
+            Math.max(2, Math.min(3, input.requirementCosts?.get(id) ?? 2)),
+        ]));
+        const uxSlices = requirementIdsProvided
+            ? batchFrontendPlanRequirements({
+                requirementIds: input.requirementIds,
+                maxEstimatedRecordCalls: FRONTEND_PLAN_UX_LOCAL_MAX_RECORD_CALLS,
+                maxRequirements: 3,
+                requirementCosts: uxCosts,
+            })
+            : [[]];
+        uxSlices.forEach((slice, batchIndex) => queue.push({
+            id: `ux-local-${batchIndex + 1}`,
+            toolNames: uxSegment.toolNames,
+            ...(slice.length > 0 ? { requirementSlice: slice } : {}),
+            prompt: slice.length > 0
+                ? buildUxPrompt(slice)
+                : buildPhasePrompt(uxSegment),
+        }));
+        for (const segment of FRONTEND_PLAN_SEGMENTS) {
+            if (["coverage", "ux-local", "finalize"].includes(segment.id))
+                continue;
+            queue.push({
+                id: segment.id,
+                toolNames: segment.toolNames,
+                prompt: buildPhasePrompt(segment),
+            });
+        }
+        queue.push({
+            id: finalizeSegment.id,
+            toolNames: finalizeSegment.toolNames,
+            prompt: buildPhasePrompt(finalizeSegment),
+        });
+    }
+    let last;
+    let index = 0;
+    let invocationCount = 0;
+    while (index < queue.length) {
+        const session = queue[index];
+        const remaining = (session.coverageOnly ? session.coverageSlice ?? [] : []).filter((id) => !input.committedRequirementIds?.().has(id));
+        const preexistingMissing = session.coverageOnly && session.coverageSlice && input.committedFacts
+            ? collectFrontendPlanMissingFacts({
+                requirementIds: session.coverageSlice,
+                committedFacts: input.committedFacts(),
+            })
+            : [];
+        // Resume/earlier-batch commits may already cover this slice.
+        if (session.coverageOnly &&
+            session.coverageSlice &&
+            remaining.length === 0 &&
+            preexistingMissing.length === 0) {
+            index += 1;
+            continue;
+        }
+        let prompt = session.prompt;
+        if (session.coverageOnly && session.coverageSlice) {
+            const promptSlice = remaining.length > 0 ? remaining : session.coverageSlice;
+            prompt = buildCoveragePrompt(promptSlice, session.missingFacts ?? preexistingMissing);
+        }
+        else if (session.id === "compact-local") {
+            prompt = buildCompactLocalPrompt(session.missingFacts);
+        }
+        else if (session.id.startsWith("ux-local-")) {
+            // Build this at execution time: coverage facts are committed by the
+            // preceding sessions and must be visible to the UX-local model.
+            prompt = session.requirementSlice
+                ? buildUxPrompt(session.requirementSlice, session.missingFacts)
+                : buildPhasePrompt(uxSegment, session.missingFacts);
+        }
+        else {
+            // Global phases and finalize also consume the latest committed ledger;
+            // constructing their prompt only when the session starts prevents a
+            // stale queue entry from dropping facts written by earlier phases.
+            const segment = FRONTEND_PLAN_SEGMENTS.find((candidate) => candidate.id === session.id);
+            if (segment) {
+                prompt =
+                    session.id === "finalize" && useCompactSmallPlan
+                        ? buildCompactFinalizePrompt(session.missingFacts)
+                        : buildPhasePrompt(segment, session.missingFacts);
+            }
+        }
+        const committedBefore = input.committedFactCount();
+        input.setActiveRequirementScope?.(session.id === "compact-local" || session.id.startsWith("ux-local-")
+            ? session.requirementSlice ?? []
+            : []);
+        if (invocationCount >= FRONTEND_PLAN_BATCH_MAX_SESSIONS)
+            break;
+        invocationCount += 1;
+        const customTools = input.segmentCustomTools(session.toolNames);
+        const result = await input.piStepFn({
+            ...input.sessionOptions,
+            prompt,
+            ...(customTools.length > 0
+                ? {
+                    writerToolPolicy: {
+                        requireSdk: true,
+                        customTools,
+                    },
+                }
+                : {}),
+        });
+        last = result;
+        try {
+            await input.flushLedger();
+        }
+        catch {
+            // best-effort: the node-level flush runs again after the attempt
+        }
+        const committedAfter = input.committedFactCount();
+        const committedFactsOnlySuccess = session.id !== "finalize" &&
+            !(result.assistantText ?? "").trim() &&
+            !result.stderr.trim() &&
+            !result.timedOut &&
+            committedAfter > committedBefore;
+        const missingCoverage = session.coverageOnly && session.coverageSlice && input.committedFacts
+            ? collectFrontendPlanMissingFacts({
+                requirementIds: session.coverageSlice,
+                committedFacts: input.committedFacts(),
+            })
+            : [];
+        const isCompactLocalSession = session.id === "compact-local";
+        const isUxLocalSession = session.id.startsWith("ux-local-");
+        const missingPhase = isCompactLocalSession && input.committedFacts
+            ? [
+                ...collectFrontendPlanMissingFacts({
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                }),
+                ...collectFrontendPlanPhaseMissingFacts({
+                    phase: "ux-local",
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                    behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
+                }),
+            ]
+            : isUxLocalSession && session.requirementSlice && input.committedFacts
+                ? collectFrontendPlanPhaseMissingFacts({
+                    phase: "ux-local",
+                    requirementIds: session.requirementSlice,
+                    committedFacts: input.committedFacts(),
+                    behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
+                })
+                : session.id === "global-mock-data" && allRequirementIds.length > 0 && input.committedFacts
+                    ? collectFrontendPlanPhaseMissingFacts({
+                        phase: "global-mock-data",
+                        requirementIds: allRequirementIds,
+                        committedFacts: input.committedFacts(),
+                    })
+                    : [];
+        const missingPhaseFacts = [...missingCoverage, ...missingPhase];
+        // Frozen verification commands must operate on files the planner has
+        // committed verification targets for; otherwise the admission writeSet
+        // cannot authorize the file and verify-shell deterministically fails.
+        const verificationCommandFiles = collectFrontendVerificationCommandFiles(input.basePrompt);
+        if (verificationCommandFiles.length > 0 && allRequirementIds.length > 0 && input.committedFacts) {
+            const coveredVerificationFiles = new Set(input
+                .committedFacts()
+                .map(committedFactFromPlanRecord)
+                .filter((fact) => Boolean(fact && fact.origin === "plan" && fact.kind === "plan-verification-target"))
+                .map((fact) => fact.entry?.file)
+                .filter((file) => typeof file === "string"));
+            for (const file of verificationCommandFiles) {
+                if (coveredVerificationFiles.has(file))
+                    continue;
+                missingPhaseFacts.push({
+                    kind: "plan-verification-target",
+                    id: file,
+                    requirementIds: allRequirementIds.slice(0, 1),
+                    reason: `frozen verification command references ${file} but no committed verification target covers it; record a static verification target for this file so it joins the writeSet`,
+                });
+            }
+        }
+        const promptForMissingPhase = (missing) => session.coverageOnly
+            ? buildCoveragePrompt(session.coverageSlice ?? [], missing)
+            : isCompactLocalSession
+                ? buildCompactLocalPrompt(missing)
+                : session.id === "finalize" && useCompactSmallPlan
+                    ? buildCompactFinalizePrompt(missing)
+                    : isUxLocalSession
+                        ? buildUxPrompt(session.requirementSlice ?? [], missing)
+                        : buildPhasePrompt(globalMockDataSegment, missing);
+        if (result.ok) {
+            if (missingPhaseFacts.length === 0) {
+                index += 1;
+                continue;
+            }
+            if ((session.retryCount ?? 0) < 2) {
+                queue[index] = {
+                    ...session,
+                    retryCount: (session.retryCount ?? 0) + 1,
+                    missingFacts: missingPhaseFacts,
+                    prompt: promptForMissingPhase(missingPhaseFacts),
+                };
+                continue;
+            }
+            return {
+                ...result,
+                ok: false,
+                stderr: `${result.stderr}\nfrontend plan completeness check failed: ${missingPhaseFacts.map((item) => item.reason).join("; ")}`.trim(),
+                failureCategory: "invalid-output",
+            };
+        }
+        if (committedFactsOnlySuccess) {
+            // The session died but banked facts: keep the progress and move on.
+            if (missingPhaseFacts.length > 0 && (session.retryCount ?? 0) < 2) {
+                queue[index] = {
+                    ...session,
+                    retryCount: (session.retryCount ?? 0) + 1,
+                    missingFacts: missingPhaseFacts,
+                    prompt: promptForMissingPhase(missingPhaseFacts),
+                };
+                continue;
+            }
+            if (missingPhaseFacts.length > 0) {
+                return {
+                    ...result,
+                    ok: false,
+                    stderr: `frontend plan completeness check failed: ${missingPhaseFacts.map((item) => item.reason).join("; ")}`,
+                    failureCategory: "invalid-output",
+                };
+            }
+            index += 1;
+            continue;
+        }
+        // A length-stopped, fact-less compact session is the planner variant of
+        // writer-thinking-exhausted. Give the same scope exactly one tool-first
+        // retry before the split below re-batches the requirements, because one
+        // reinforced full-scope pass is cheaper than re-planning split halves.
+        const plannerThinkingBurn = isCompactLocalSession &&
+            committedAfter === committedBefore &&
+            !(result.assistantText ?? "").trim() &&
+            !result.stderr.trim() &&
+            !result.timedOut &&
+            readWriterThinkingExhaustionEvidence(result).stopReason === "length";
+        if (plannerThinkingBurn && (session.retryCount ?? 0) < 1) {
+            queue[index] = {
+                ...session,
+                retryCount: (session.retryCount ?? 0) + 1,
+                prompt: buildCompactLocalPrompt(),
+            };
+            continue;
+        }
+        // Option 5: a multi-requirement coverage batch that failed with ZERO
+        // new facts and no provider stderr is the upfront-reasoning burn —
+        // halve the slice and retry instead of failing the attempt. The compact
+        // local session participates through its requirementSlice so a
+        // thinking-burned small plan degrades into smaller batched sessions
+        // instead of replaying one full-scope prompt until the repair budget
+        // runs out.
+        const coverageSlice = session.coverageOnly
+            ? session.coverageSlice
+            : isCompactLocalSession
+                ? session.requirementSlice
+                : undefined;
+        const zeroProgressBurn = coverageSlice !== undefined &&
+            coverageSlice.length > 1 &&
+            committedAfter === committedBefore &&
+            !(result.assistantText ?? "").trim() &&
+            !result.stderr.trim() &&
+            !result.timedOut;
+        if (zeroProgressBurn && coverageSlice) {
+            const half = Math.ceil(coverageSlice.length / 2);
+            const firstSlice = coverageSlice.slice(0, half);
+            const secondSlice = coverageSlice.slice(half);
+            if (isCompactLocalSession) {
+                // The split halves leave compact mode: continue them as ordinary
+                // coverage sessions so every downstream ladder branch applies.
+                queue.splice(index, 1, {
+                    ...session,
+                    id: `coverage-compact-split-1`,
+                    coverageOnly: true,
+                    coverageSlice: firstSlice,
+                    requirementSlice: firstSlice,
+                    prompt: buildCoveragePrompt(firstSlice),
+                }, {
+                    ...session,
+                    id: `coverage-compact-split-2`,
+                    coverageOnly: true,
+                    coverageSlice: secondSlice,
+                    requirementSlice: secondSlice,
+                    prompt: buildCoveragePrompt(secondSlice),
+                });
+                continue;
+            }
+            queue.splice(index, 1, {
+                ...session,
+                coverageSlice: firstSlice,
+                prompt: buildCoveragePrompt(firstSlice),
+            }, {
+                ...session,
+                coverageSlice: secondSlice,
+                prompt: buildCoveragePrompt(secondSlice),
+            });
+            continue;
+        }
+        if ((session.coverageOnly || isUxLocalSession || session.id === "global-mock-data") &&
+            missingPhaseFacts.length > 0 &&
+            !result.stderr.trim() &&
+            !result.timedOut &&
+            (session.retryCount ?? 0) < 2) {
+            queue[index] = {
+                ...session,
+                retryCount: (session.retryCount ?? 0) + 1,
+                missingFacts: missingPhaseFacts,
+                prompt: promptForMissingPhase(missingPhaseFacts),
+            };
+            continue;
+        }
+        return mapPlannerExhaustion(result, committedAfter > committedBefore);
+    }
+    if (index < queue.length) {
+        return {
+            ...(last ?? {
+                ok: false,
+                stdout: "",
+                stderr: "",
+                assistantText: "",
+                command: [],
+                durationMs: 0,
+                exitCode: null,
+                failureCategory: "invalid-output",
+                modelDisplay: "unknown",
+                parsedEvents: 0,
+                timedOut: false,
+                attemptedModels: [],
+                fallbackUsed: false,
+                tokensUsed: 0,
+            }),
+            ok: false,
+            stderr: `${last?.stderr ?? ""}\nfrontend plan segmentation exceeded the ${FRONTEND_PLAN_BATCH_MAX_SESSIONS}-session safety limit before finalize`.trim(),
+            failureCategory: "invalid-output",
+        };
     }
-    return parsed.toString();
+    return mapPlannerExhaustion(last ?? {
+        ok: false,
+        stdout: "",
+        stderr: "frontend plan segmentation produced no session",
+        failureCategory: "empty-output",
+        durationMs: 0,
+    }, false);
 }
-const DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES = {
-    readGitStatusPorcelain,
-    recoverRootNulArtifact,
-};
 export async function executeDagPiNode(input, meta, piStepFn = executePiStep, writeGuardDependencies = DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES) {
     const started = Date.now();
     const persona = resolveDagPiPersona(input.task);
@@ -512,6 +3935,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
         : undefined;
     let writerToolPolicy;
+    let reviewTerminalTools;
+    let designTerminalTools;
+    let planLedgerTools;
+    let contractTools;
+    let scoutEvidenceTools;
+    let readBudgetTools;
     const commandPolicy = resolveDagCommandPolicy(input.task.commandPolicy);
     const allowsPlaywrightCli = dagCommandPolicyAllows(input.task.commandPolicy, "playwright-cli");
     let playwrightToolContext;
@@ -595,6 +4024,167 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             };
         }
     }
+    if (isFrontendReviewTypedTerminalNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            reviewTerminalTools = await createFrontendReviewTerminalTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: reviewTerminalTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi review terminal tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendDesignTypedTerminalNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            designTerminalTools = await createFrontendDesignTerminalTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: designTerminalTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi design terminal tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendContractTypedNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            contractTools = await createFrontendContractTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: contractTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi contract tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendScoutEvidenceNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            scoutEvidenceTools = await createFrontendScoutEvidenceTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                workspaceRoot: input.cwd,
+                sourceDeclaredPaths: await resolveFrontendScoutSourceDeclaredPaths({
+                    cwd: input.cwd,
+                    spec: meta.spec,
+                }),
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: scoutEvidenceTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi scout evidence tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (isFrontendPlanLedgerNode(input.task)) {
+        try {
+            const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
+            const store = createTypedEventStore();
+            planLedgerTools = await createFrontendPlanLedgerTools({
+                attemptId: `${meta.runId}:${input.task.id}`,
+                store,
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                skeleton: input.task.structuredContractOutput?.skeleton,
+                sourceBinding: meta.spec.sourceBinding,
+                writeSetPatterns: input.task.writeSet,
+                componentNewSourceReferences: await resolveFrontendPlanNewComponentSourceReferences({
+                    cwd: input.cwd,
+                    sourceBinding: meta.spec.sourceBinding,
+                }),
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: planLedgerTools.customTools,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi plan ledger tool policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    if (input.task.readBudget) {
+        try {
+            readBudgetTools = await createPiReadBudgetCustomTools({
+                repoRoot: input.cwd,
+                budget: input.task.readBudget,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: [
+                    ...(writerToolPolicy?.customTools ?? []),
+                    ...readBudgetTools.customTools,
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi read budget policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     let result;
     try {
         // Phase 5 (P1-9): capture the writeSet baseline BEFORE the writer provider
@@ -603,8 +4193,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         // hard fail (no baseline → no rollback → no recovery). Dynamic import avoids
         // an executor ↔ scheduler static cycle.
         if (isWriteTask &&
-            (input.task.id === "frontend-implement-pi" ||
-                input.task.id === "frontend-repair-pi") &&
+            input.task.id === "frontend-implement-pi" &&
             (input.task.writeSet?.length ?? 0) > 0) {
             try {
                 const { captureFrontendWriterAttemptIntent } = await import("../workflows/dag/frontend-writer-recovery.js");
@@ -667,10 +4256,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 : [],
             activeTools: toolNames,
         });
-        result = await piStepFn({
+        const piSessionOptions = {
             attachedFiles: [],
             modelConfig,
-            prompt: input.prompt,
             repoRoot: input.cwd,
             step,
             toolNames,
@@ -683,7 +4271,6 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             ...(input.task.contextBudget
                 ? { contextBudget: input.task.contextBudget }
                 : {}),
-            ...(writerToolPolicy ? { writerToolPolicy } : {}),
             ...(piExtensionPaths && piExtensionPaths.length > 0
                 ? { piExtensionPaths }
                 : {}),
@@ -696,7 +4283,82 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     bridgeActivity(activity.kind, activity.at);
                 }
                 : undefined,
-        });
+        };
+        if (isFrontendPlanLedgerNode(input.task) && planLedgerTools) {
+            // Frontend-only split: sequential sessions with independent
+            // output budgets (coverage -> UX decisions -> finalize), mirroring the
+            // backend-test template's module sharding. Every other template keeps
+            // the single-session path below.
+            let planRequirementIds = [];
+            const planRequirementCosts = new Map();
+            const behaviorRequiredRequirementIds = [];
+            try {
+                const { readCommittedOriginFacts } = await import("../workflows/dag/frontend-shadow-dual-write.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 = contractFacts
+                    .filter((record) => record.fact
+                    ?.kind === "requirement")
+                    .map((record) => record.fact?.id)
+                    .filter((id) => typeof id === "string");
+                for (const record of contractFacts) {
+                    const fact = record.fact;
+                    if (fact?.kind !== "requirement" || typeof fact.id !== "string")
+                        continue;
+                    const evidence = fact.evidence;
+                    if (evidence?.behavior === "required")
+                        behaviorRequiredRequirementIds.push(fact.id);
+                    planRequirementCosts.set(fact.id, estimateFrontendPlanRequirementRecordCalls(fact));
+                }
+            }
+            catch {
+                // Unreadable ledger falls back to a single coverage session.
+            }
+            result = await runFrontendPlanSegmentedSessions({
+                piStepFn,
+                sessionOptions: piSessionOptions,
+                basePrompt: input.prompt,
+                attempt: input.attempt ?? 1,
+                committedFactCount: () => planLedgerTools.committedFactCount(),
+                requirementIds: planRequirementIds,
+                requirementCosts: planRequirementCosts,
+                compactSmallPlan: true,
+                committedRequirementIds: () => planLedgerTools.committedRequirementIds(),
+                committedFacts: () => planLedgerTools.committedFacts(),
+                behaviorRequiredRequirementIds,
+                setActiveRequirementScope: (requirementIds) => planLedgerTools.setActiveRequirementScope(requirementIds),
+                segmentCustomTools: (toolNames) => toolNames === null
+                    ? planLedgerTools.customTools
+                    : planLedgerTools.customTools.filter((tool) => typeof tool === "object" &&
+                        tool !== null &&
+                        toolNames.has(tool.name)),
+                flushLedger: () => planLedgerTools.flush(),
+            });
+        }
+        else {
+            result = await piStepFn({
+                ...piSessionOptions,
+                prompt: input.prompt,
+                ...(writerToolPolicy ? { writerToolPolicy } : {}),
+            });
+        }
+        try {
+            const verificationCommandFiles = collectFrontendVerificationCommandFiles(input.prompt);
+            const debugPath = path.join(meta.runDir, input.task.id, "verification-command-coverage.json");
+            await import("node:fs/promises").then(({ writeFile, mkdir }) => mkdir(path.dirname(debugPath), { recursive: true }).then(() => writeFile(debugPath, `${JSON.stringify({
+                schemaVersion: 1,
+                basePromptChars: input.prompt.length,
+                verificationCommandFiles,
+            }, null, 2)}\n`)));
+        }
+        catch {
+            // best-effort diagnostic breadcrumb
+        }
     }
     catch (error) {
         if (playwrightToolContext) {
@@ -734,10 +4396,171 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     if (input.task.id === "generate-backend-md-plan-pi" && result.assistantText?.trim()) {
         await writeTextArtifactFile(path.join(meta.runDir, input.task.id, "plan.md"), result.assistantText.trim() + "\n");
     }
-    const mapped = mapPiResultToDagNodeResult(result, input.task.writerOutcomePolicy
-        ? WRITER_OUTCOME_PROTOCOL_LINE
-        : input.task.firstProtocolLine);
+    const mapped = mapPiResultToDagNodeResult(result, isFrontendFactsWriter(input.task)
+        ? undefined
+        : input.task.writerOutcomePolicy
+            ? WRITER_OUTCOME_PROTOCOL_LINE
+            : input.task.firstProtocolLine);
+    if (input.task.id === "generate-backend-md-plan-pi") {
+        if (mapped.stopReason === "length") {
+            return {
+                ...mapped,
+                ok: false,
+                failureCategory: STRUCTURED_OUTPUT_RETRY_CATEGORY,
+                stderr: [
+                    mapped.stderr,
+                    "backend-test Markdown plan was truncated before its required protocol could be trusted: stopReason=length; retry with the final artifact first",
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            };
+        }
+        if (mapped.ok) {
+            const protocol = assessBackendTestPlanProtocol(mapped.assistantText || mapped.stdout);
+            if (!protocol.ok) {
+                return {
+                    ...mapped,
+                    ok: false,
+                    failureCategory: "invalid-output",
+                    stderr: [
+                        mapped.stderr,
+                        `backend-test Markdown plan protocol invalid: ${protocol.issues.map((issue) => `${issue.code}: ${issue.detail}`).join("; ")}`,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+            }
+        }
+    }
+    // A node-specific budget is enforced for every frontend reader that opts in,
+    // including design/final review. Earlier code only checked contract, scout,
+    // and plan nodes, leaving the two largest review sessions unbounded.
+    // A soft-limit node has already stopped repository access in its SDK tool
+    // guard. Session events still include the rejected tool attempt, so using
+    // those telemetry events as a second budget gate would wrongly turn a
+    // successful plan into read-burst.
+    const readBudgetIssues = input.task.readBudget?.onExhaustion === "return-guidance"
+        ? []
+        : [
+            ...(readBudgetTools?.issues() ?? []),
+            ...(await detectNodeReadBudget({
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+                budget: input.task.readBudget,
+            })),
+        ];
+    if (readBudgetIssues.length > 0) {
+        const hasTypedFrontendTerminal = isFrontendReviewTypedTerminalNode(input.task) ||
+            isFrontendDesignTypedTerminalNode(input.task);
+        // A stale/generated DAG may still carry the legacy read budget. Once a
+        // design/review node has a successful typed terminal, telemetry is
+        // diagnostic only; the terminal shadow below still fails closed when the
+        // fact is missing or conflicting.
+        if (mapped.ok && hasTypedFrontendTerminal) {
+            // Continue to the typed terminal shadow validation below.
+        }
+        else {
+            // Read-budget telemetry is diagnostic only when the provider/executor
+            // has already failed. In particular, keep context-overflow so
+            // node-execution selects its compact retry envelope instead of treating
+            // the attempt as a generic read-burst retry.
+            if (!mapped.ok) {
+                return {
+                    ...mapped,
+                    stderr: [mapped.stderr, ...readBudgetIssues]
+                        .filter(Boolean)
+                        .join("\n\n"),
+                };
+            }
+            return {
+                ...mapped,
+                ok: false,
+                failureCategory: "read-burst",
+                stderr: [mapped.stderr, ...readBudgetIssues]
+                    .filter(Boolean)
+                    .join("\n\n"),
+            };
+        }
+    }
+    if (isFrontendReviewTypedTerminalNode(input.task)) {
+        return await runFrontendReviewTerminalShadow({
+            task: input.task,
+            meta,
+            mapped,
+            tools: reviewTerminalTools,
+        });
+    }
+    if (isFrontendDesignTypedTerminalNode(input.task)) {
+        return await runFrontendDesignTerminalShadow({
+            task: input.task,
+            meta,
+            mapped,
+            tools: designTerminalTools,
+        });
+    }
+    if (isFrontendContractTypedNode(input.task)) {
+        try {
+            await contractTools?.flush?.();
+        }
+        catch {
+            // best-effort flush
+        }
+    }
+    if (isFrontendScoutEvidenceNode(input.task)) {
+        try {
+            await scoutEvidenceTools?.flush?.();
+        }
+        catch {
+            // best-effort flush
+        }
+        if (mapped.ok) {
+            const { checkCommittedOriginFacts, readCommittedOriginFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+            const scoutFacts = await readCommittedOriginFacts(meta.runDir, input.task.id, "scout-typed-facts.jsonl");
+            const completeness = checkCommittedOriginFacts({
+                records: scoutFacts,
+                origin: "scout",
+            });
+            if (!completeness.ok) {
+                return {
+                    ...mapped,
+                    ok: false,
+                    failureCategory: "invalid-output",
+                    stderr: [mapped.stderr, completeness.reason]
+                        .filter(Boolean)
+                        .join("\n\n"),
+                };
+            }
+        }
+    }
+    if (isFrontendPlanLedgerNode(input.task)) {
+        try {
+            await planLedgerTools?.flush?.();
+        }
+        catch {
+            // best-effort flush; missing ledger still fails at the node validator
+        }
+        // NOTE: the legacy plan read-burst guard lived here. It is dead code
+        // since the plan node went tool-only (resolveDagPiToolNames grants no
+        // read/grep/ls/find), so a read burst is structurally impossible; the
+        // read-budget path (scout etc.) keeps its own guard.
+    }
     if (!isWriteTask) {
+        if (!mapped.ok &&
+            !(mapped.assistantText ?? "").trim() &&
+            !mapped.stderr.trim()) {
+            // Terminal-fact acceptance: the run finished with every fact committed
+            // (including the terminal) but no final narrative text. A timeout or
+            // provider error always leaves supervision/provider stderr, so a
+            // blank stderr here means the only "failure" is the empty text.
+            const terminalAccepted = await acceptCommittedTypedTerminalFact(meta.runDir, input.task.id);
+            if (terminalAccepted) {
+                return {
+                    ...mapped,
+                    ok: true,
+                    failureCategory: undefined,
+                };
+            }
+        }
         return mapped;
     }
     let writeGuardOk = true;
@@ -870,8 +4693,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             changeManifestChangedFiles = changedFiles;
             // Phase 5: record the attempt changed paths/hashes into the rollback
             // intent so a transient partial write can be CAS-restored.
-            if ((input.task.id === "frontend-implement-pi" ||
-                input.task.id === "frontend-repair-pi") &&
+            if (input.task.id === "frontend-implement-pi" &&
                 (input.task.writeSet?.length ?? 0) > 0) {
                 try {
                     const { recordFrontendWriterAttempt } = await import("../workflows/dag/frontend-writer-recovery.js");
@@ -921,15 +4743,96 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
     }
     let writerOutcomeViolation;
+    let factDerivedStatus;
     if (mapped.ok && input.task.writerOutcomePolicy) {
-        if (changeManifestChangedFiles === undefined) {
+        if (isFrontendFactsWriter(input.task)) {
+            // AC-001/AC-003: facts-derived status. The first line is never read;
+            // the legacy validator still runs for the shadow comparison only.
+            try {
+                const [writerStatus, contractModule, traceModule] = await Promise.all([
+                    import("../workflows/dag/frontend-writer-status.js"),
+                    import("../workflows/dag/frontend-implementation-contract.js"),
+                    import("../workflows/dag/frontend-verification-trace.js"),
+                ]);
+                const { collectFrontendWriterFacts, deriveFrontendWriterStatus, computeFailureFingerprint, compareFactStatusToLegacyOutcome, } = writerStatus;
+                const contractPath = path.join(meta.runDir, "contracts", "frontend-implementation-contract.json");
+                const contractRaw = JSON.parse(await readFile(contractPath, "utf8"));
+                const parsedContract = contractModule.frontendImplementationContractSchema.safeParse(contractRaw);
+                if (!parsedContract.success) {
+                    throw new Error(`invalid run-owned canonical contract: ${parsedContract.error.issues
+                        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+                        .join("; ")}`);
+                }
+                const tracePreflight = await traceModule.evaluateFrontendWriterTracePreflight({
+                    contract: parsedContract.data,
+                    workspaceRoot: input.cwd,
+                });
+                await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "frontend-trace-preflight.json", {
+                    schemaVersion: 1,
+                    nodeId: input.task.id,
+                    ok: tracePreflight.ok,
+                    targets: tracePreflight.targets,
+                    failures: tracePreflight.failures,
+                });
+                const facts = await collectFrontendWriterFacts({
+                    sessionEventsPath: path.join(meta.runDir, input.task.id, "session-events.jsonl"),
+                    changedFiles: changeManifestChangedFiles ?? [],
+                    writeGuard: { ok: writeGuardOk, violations: writeGuardViolations },
+                    requirementTargets: [],
+                    coveredRequirementIds: [],
+                    focusedCheckFailures: tracePreflight.failures,
+                    tokensUsed: result.tokensUsed,
+                    wallTimeMs: Date.now() - started,
+                    rounds: 1,
+                    writeAttempts: attempt,
+                    firstLineText: mapped.assistantText,
+                });
+                const derived = deriveFrontendWriterStatus(facts);
+                factDerivedStatus = derived.status;
+                const legacyValidation = validateWriterImplementationOutcome(mapped.assistantText || mapped.stdout, changeManifestChangedFiles ?? [], {
+                    requireChangedFiles: false,
+                    allowMissingChangedOutcomeWhenDiffPresent: false,
+                });
+                const legacyOutcome = legacyValidation.ok
+                    ? legacyValidation.outcome
+                    : legacyValidation.reason.includes("blocked")
+                        ? "blocked"
+                        : "missing";
+                await writeDagNodeJsonArtifact(meta.runDir, input.task.id, "fact-implementation-status.json", {
+                    schemaVersion: 1,
+                    nodeId: input.task.id,
+                    status: derived.status,
+                    reason: derived.reason,
+                    changedFiles: facts.changedFiles,
+                    writeToolEvents: facts.writeToolEvents,
+                    writeGuardOk: facts.writeGuardOk,
+                    writeGuardViolations: facts.writeGuardViolations,
+                    focusedCheckFailures: facts.focusedCheckFailures,
+                    alreadySatisfiedEvidence: facts.alreadySatisfiedEvidence,
+                    tokensUsed: facts.tokensUsed,
+                    wallTimeMs: facts.wallTimeMs,
+                    rounds: facts.rounds,
+                    writeAttempts: facts.writeAttempts,
+                    failureFingerprint: computeFailureFingerprint(facts),
+                    shadow: compareFactStatusToLegacyOutcome(derived.status, legacyOutcome),
+                });
+                if (derived.status !== "changed" &&
+                    derived.status !== "already-satisfied") {
+                    writerOutcomeViolation = `fact-derived status ${derived.status}: ${derived.reason}`;
+                }
+            }
+            catch (error) {
+                writerOutcomeViolation = `frontend facts derivation failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        else if (changeManifestChangedFiles === undefined) {
             writerOutcomeViolation =
                 "writer outcome validation failed: actual diff is unavailable";
         }
         else {
             const outcomeValidation = validateWriterImplementationOutcome(mapped.assistantText || mapped.stdout, changeManifestChangedFiles, {
                 requireChangedFiles: input.task.writerOutcomePolicy.requireChangedFiles === true,
-                allowMissingChangedOutcomeWhenDiffPresent: isBackendTestCompletenessRetryCandidate(input.task),
+                allowMissingChangedOutcomeWhenDiffPresent: allowsMissingChangedWriterOutcomeRecovery(input.task),
             });
             if (!outcomeValidation.ok) {
                 writerOutcomeViolation = outcomeValidation.reason;
@@ -969,6 +4872,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         ? "pytest-generate"
                         : "md-generate",
                     writeSet: input.task.writeSet ?? [],
+                    runDir: meta.runDir,
                 })
                 : isBackendTestMdPlanTask(input.task)
                     ? await assessBackendTestMdPlanCompleteness(input.cwd, backendLayout)
@@ -1045,6 +4949,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         changeManifestChangedFiles !== undefined &&
         changeManifestChangedFiles.length === 0 &&
         writeToolCallCount === 0;
+    // Budget-exhausted: the provider session consumed an extreme amount of
+    // tokens (e.g. an unresolved read-edit-test loop) and still failed. Only
+    // applies on a non-ok writer result; a successful write is never re-labeled.
+    const writerBudgetExhausted = !mapped.ok &&
+        typeof mapped.tokensUsed === "number" &&
+        mapped.tokensUsed > WRITER_TOKEN_BUDGET;
     const targetCleanTransport = !mapped.ok &&
         isTargetTemplateTransientRetryNode(input.task) &&
         rawFailureCategory !== undefined &&
@@ -1065,11 +4975,13 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             ? writeGuardOk
                 ? completenessFailure
                     ? completenessFailure.failureCategory
-                    : changeManifestChangedFiles?.length === 0 &&
-                        isWriterEmptyDiffRetryCandidate(input.task) &&
-                        isChangedWriterImplementationOutcome(mapped.assistantText || mapped.stdout)
+                    : factDerivedStatus === "empty-diff"
                         ? WRITER_EMPTY_DIFF_RETRY_CATEGORY
-                        : "invalid-output"
+                        : changeManifestChangedFiles?.length === 0 &&
+                            isWriterEmptyDiffRetryCandidate(input.task) &&
+                            isChangedWriterImplementationOutcome(mapped.assistantText || mapped.stdout)
+                            ? WRITER_EMPTY_DIFF_RETRY_CATEGORY
+                            : "invalid-output"
                 : "write-guard"
             : // When the attempt already failed with a writer-style category
                 // (empty-output / invalid-output / writer-empty-diff) but the workspace
@@ -1086,17 +4998,35 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         mapped.failureCategory === "invalid-output" ||
                         mapped.failureCategory === WRITER_EMPTY_DIFF_RETRY_CATEGORY)
                     ? INCOMPLETE_WRITE_SET_RETRY_CATEGORY
-                    : // writer-thinking-exhausted: a length-stopped thinking-only attempt with
-                        // zero write tool calls and zero attributed diff is terminal and
-                        // non-retryable; recommend a model switch + fresh run. Only applies on
-                        // the empty-output base category so provider/transport failures keep
-                        // their original category, and only when the completeness gate did not
-                        // upgrade to incomplete-write-set above.
-                        writerThinkingExhausted
-                            ? WRITER_THINKING_EXHAUSTED_CATEGORY
-                            : writerCleanTimeout
-                                ? WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY
-                                : mapped.failureCategory,
+                    : // partial-success-with-context-overflow: the writer hit a context
+                        // overflow on its final provider call but had already persisted
+                        // real file changes (change-manifest non-empty). Classify it
+                        // distinctly so the report shows "code largely done, verification
+                        // incomplete" instead of a misleading empty-output / spec issue,
+                        // and recovery can rerun from verify/implement with a compacted
+                        // session rather than asking the operator for spec clarification.
+                        rawFailureCategory === "context-overflow" &&
+                            (changeManifestChangedFiles?.length ?? 0) > 0
+                            ? "partial-success-with-context-overflow"
+                            : // writer-thinking-exhausted: a length-stopped thinking-only attempt with
+                                // zero write tool calls and zero attributed diff is terminal and
+                                // non-retryable; recommend a model switch + fresh run. Only applies on
+                                // the empty-output base category so provider/transport failures keep
+                                // their original category, and only when the completeness gate did not
+                                // upgrade to incomplete-write-set above.
+                                writerThinkingExhausted
+                                    ? WRITER_THINKING_EXHAUSTED_CATEGORY
+                                    : writerCleanTimeout
+                                        ? WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY
+                                        : // writer-budget-exhausted: the provider session consumed an
+                                            // excessive amount of tokens (a read-edit-test loop that never
+                                            // converged) and still failed. Classify distinctly so the
+                                            // report says the run burned its budget instead of a generic
+                                            // empty-output, and recovery recommends a fresh compacted
+                                            // run rather than spec-clarification.
+                                            writerBudgetExhausted
+                                                ? WRITER_BUDGET_EXHAUSTED_CATEGORY
+                                                : mapped.failureCategory,
         durationMs: mapped.durationMs || Date.now() - started,
     };
 }
@@ -1241,6 +5171,8 @@ export function mapPiResultToDagNodeResult(result, firstProtocolLine) {
         tokensUsed: result.tokensUsed,
         parsedEvents: result.parsedEvents,
         stopReason: readWriterThinkingExhaustionEvidence(result).stopReason,
+        thinkingObserved: readWriterThinkingExhaustionEvidence(result).thinkingObserved,
+        writeToolCallCount: readWriterThinkingExhaustionEvidence(result).writeToolCallCount,
     };
 }
 function canonicalizeProtocolFirstLine(assistantText, firstProtocolLine) {