@tea-agent/loop-agent 0.42.0-next.2 → 0.42.0-next.3

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

@@ -1,15 +1,21 @@
 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 { pathMatchesPattern } from "../shared/git-progress.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 { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
@@ -25,6 +31,15 @@ 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";
+/**
+ * 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;
 function readWriterThinkingExhaustionEvidence(result) {
     const wider = result;
     return {
@@ -167,6 +182,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)) {
@@ -182,7 +205,141 @@ export function resolveDagPiStepName(task) {
     }
     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"];
     }
@@ -196,233 +353,3184 @@ export function resolveDagPiToolNames(task) {
     }
     return tools;
 }
-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
-            ? [
-                "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.",
-            "Use write tools only for the bounded implementation requested by this node.",
-            "The upstream plan node's output is a BLUEPRINT, not a deliverable: reading it never satisfies this node. You MUST materialize the plan into actual working-tree changes by calling write/edit tools before claiming changed. A detailed plan that names every file, test, or snippet still requires you to write those files yourself.",
-            "Forbidden paths bound the writeSet, not the task: when the task only requires writing inside the writeSet (e.g. adding tests that call existing public APIs), a forbidden src/** does not make the task impossible — do NOT claim blocked merely because some path you never need to write is forbidden. blocked is only for when you genuinely cannot produce the required writeSet changes.",
-            outcomeInstruction,
-            `Allowed paths: ${(task.allowedPaths ?? []).join(", ") || "(none declared)"}.`,
-            `Write set: ${(task.writeSet ?? []).join(", ") || "(none declared)"}.`,
-            `Forbidden paths: ${(task.forbiddenPaths ?? []).join(", ") || "(none declared)"}.`,
-            "Preserve unrelated files. Do not edit outside allowedPaths/writeSet. Never write forbiddenPaths, .harness/dag-runs/**, or undeclared root artifacts/**.",
-            "Return concise Markdown with changed files, verification performed or still required, and residual risks.",
-            "Do not wrap the output in code fences and do not add conversational preamble.",
-        ]
-            .filter((value) => Boolean(value))
-            .join(" ");
+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);
+        }
     }
-    // Decision Gate nodes must emit a mandatory DECISION_ENVELOPE_JSON fenced block;
-    // do not inject the global no-fence instruction that would conflict with outputContract.
-    if (task.decisionGate?.enabled === true) {
-        return [
-            `You are executing hybrid DAG node "${task.id}" (role=${role}, piPersona=${persona}, piStep=${step}, writePolicy=${writePolicy}).`,
-            "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
-            "Use read-only tools only. Do not edit, write, or commit repository files.",
-            "Return your conclusion as Markdown that includes exactly one ```DECISION_ENVELOPE_JSON fenced block (info string DECISION_ENVELOPE_JSON, not json) matching the Decision Envelope schema, plus a short evidence/risk summary.",
-            "Follow the node outputContract for the mandatory fenced block. Do not add conversational preamble outside the required Markdown structure.",
-        ].join(" ");
+    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 [
-        `You are executing hybrid DAG node "${task.id}" (role=${role}, piPersona=${persona}, piStep=${step}, writePolicy=${writePolicy}).`,
-        "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
-        "Use read-only tools only. Do not edit, write, or commit repository files.",
-        (task.readSet?.length ?? 0) > 0
-            ? `Strict read set: ${task.readSet.join(", ")}. The read tool rejects every other repository path; do not search for substitutes.`
-            : undefined,
-        "Return your conclusion as plain Markdown text suitable for downstream DAG nodes.",
-        "Do not wrap the output in code fences and do not add conversational preamble.",
-    ].join(" ");
+    return undefined;
 }
-export function resolveDagPiModelConfig(modelReference, options) {
-    const separatorIndex = modelReference.indexOf("/");
-    const qualified = separatorIndex >= 0;
-    const provider = qualified
-        ? modelReference.slice(0, separatorIndex)
-        : (DAG_PI_MODEL_PROVIDERS[modelReference] ?? DEFAULT_DAG_PI_PROVIDER);
-    const model = qualified
-        ? modelReference.slice(separatorIndex + 1)
-        : modelReference;
-    if (!provider || !model) {
-        throw new Error(`invalid DAG Pi model reference "${modelReference}": expected non-empty provider/model`);
+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;
+        }
     }
-    const explicitThinking = options?.thinking?.trim();
-    const thinking = explicitThinking ??
-        (provider === "wizard-local" && model === "gpt-5.5" ? "low" : undefined);
-    return {
-        provider,
-        model,
-        ...(thinking ? { thinking } : {}),
-    };
+    return undefined;
 }
-const SUMMARY_STDOUT_MAX = 4_000;
-const SUMMARY_STDERR_MAX = 2_000;
-export function buildPiPromptRedactedMarkdown(prompt) {
-    const redacted = redactPromptForLog(prompt);
-    return [
-        "# Pi prompt (redacted)",
-        "",
-        `- ${redacted}`,
-        "",
-        "Full prompt text is not stored. See node `result.summary.md` for execution metadata.",
-        "",
-    ].join("\n");
+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 function buildPiResultSummaryMarkdown(input) {
-    const stdout = truncateOutput(input.result.stdout, SUMMARY_STDOUT_MAX);
-    const stderr = truncateOutput(input.result.stderr || "", SUMMARY_STDERR_MAX);
-    const lines = [
-        "# Pi execution summary",
-        "",
-        "## Run metadata",
-        "",
-        "| Field | Value |",
-        "|-------|-------|",
-        `| channel | ${input.context.channel} |`,
-        `| dagRunId | ${input.context.dagRunId} |`,
-        `| dagNodeId | ${input.context.dagNodeId} |`,
-        `| cwd | ${input.context.cwd} |`,
-        `| model | ${input.model} |`,
-        `| piPersona | ${input.persona} |`,
-        `| piStep | ${input.step} |`,
-        `| ok | ${input.result.ok} |`,
-        `| failureCategory | ${input.result.failureCategory} |`,
-        `| backend | ${input.result.backend ?? "(unknown)"} |`,
-        `| sdkAttempted | ${input.result.sdkAttempted ?? false} |`,
-        `| durationMs | ${input.result.durationMs} |`,
-        `| tokensUsed | ${input.result.tokensUsed} |`,
-        `| parsedEvents | ${input.result.parsedEvents} |`,
-        "",
-        "## Prompt reference",
-        "",
-        `- ${redactPromptForLog(input.prompt)}`,
-        "",
-        "## Assistant output",
-        "",
-    ];
-    if (input.result.assistantText.trim()) {
-        lines.push("```markdown", input.result.assistantText, "```", "");
+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");
     }
-    if (stdout.text.trim()) {
-        lines.push("### raw stdout", "", "```text", stdout.text, "```", "");
-        if (stdout.truncated)
-            lines.push("_(stdout truncated)_", "");
+    catch {
+        return [];
     }
-    if (stderr.text.trim()) {
-        lines.push("### stderr", "", "```text", stderr.text, "```", "");
-        if (stderr.truncated)
-            lines.push("_(stderr truncated)_", "");
+    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 */ }
     }
-    return lines.join("\n");
-}
-export async function writePiExecutorArtifacts(artifactsDir, input) {
-    const promptPath = path.join(artifactsDir, "prompt.redacted.md");
-    const summaryPath = path.join(artifactsDir, "result.summary.md");
-    await writeTextArtifactFile(promptPath, buildPiPromptRedactedMarkdown(input.prompt));
-    await writeTextArtifactFile(summaryPath, buildPiResultSummaryMarkdown(input));
-    return { promptPath, summaryPath };
+    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",
+]);
 /**
- * Run-owned per-node Pi extension facts (plan 2026-08-21): requested ids,
- * resolved packages (with absolute entry paths), and degraded/missing ids.
- * Written only for nodes that declare `piExtensions`; never into the repo-level
- * DAG template. Best-effort: artifact failures never fail the node.
+ * 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.
  */
-async function writePiExtensionsArtifact(nodeArtifactsDir, requested, resolved, missing) {
-    try {
-        const runDir = path.dirname(nodeArtifactsDir);
-        const nodeId = path.basename(nodeArtifactsDir);
-        await writeDagNodeJsonArtifact(runDir, nodeId, "pi-extensions.json", {
-            schemaVersion: 1,
-            requested: [...requested],
-            resolved: resolved.map((entry) => ({
-                id: entry.id,
-                packageName: entry.packageName,
-                version: entry.version,
-                path: entry.entryPaths.join(", "),
-            })),
-            missing: missing.map((entry) => ({
-                id: entry.id,
-                reason: entry.reason,
-                ...(entry.detail ? { detail: entry.detail } : {}),
-            })),
-        });
+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);
+        }
     }
-    catch {
-        // best-effort run fact; node execution continues
+    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);
+        },
+    };
 }
-async function resolveValidatedFrontendBaseUrlFromContext(workspaceRoot, runDir) {
-    try {
-        const capability = JSON.parse(await readFile(path.join(runDir, "preflight-frontend-browser-tool-shell", "frontend-browser-capability.json"), "utf8"));
-        if (capability.status !== "ready" ||
-            capability.structuredToolName !== "playwright_cli") {
-            throw new Error("invalid capability artifact");
+/**
+ * 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 },
+            };
         }
     }
-    catch {
-        throw new Error("browser-command-capability-unavailable: missing or invalid frontend browser capability artifact");
+    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 });
+    // Enum fields use literal unions, not advisory strings: a soft Type.String
+    // lets the model commit values like type="behavior" that pass the tool
+    // boundary, flush into the ledger, and only fail the compile-time zod enum
+    // — a deterministic attempt failure the model could have fixed in-node.
+    const verificationTargetTypeSchema = Type.Union([
+        Type.Literal("static"),
+        Type.Literal("unit"),
+        Type.Literal("component"),
+        Type.Literal("integration"),
+        Type.Literal("mock"),
+    ]);
+    const verificationTargetSchema = Type.Object({
+        id: Type.String({}),
+        type: verificationTargetTypeSchema,
+        commandLabel: Type.String({}),
+        file: Type.String({}),
+        requirementIds: stringArray,
+        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). For non-static 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 non-static target id is the stable trace token that implementation must place in a real describe/it/test title; static targets are traced by file and command only. Entry carries id, type, commandLabel, file, requirementIds, and uiStates; 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\", \"type\": \"unit\", \"commandLabel\": \"<frozen command label>\", \"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",
+                });
+            }
+            // Belt-and-braces for providers that do not strictly enforce the
+            // tool-schema enum: reject an invalid type here with the allowed
+            // values so the model can re-record in-node instead of the whole
+            // attempt dying at compile time on the strict zod enum.
+            const verificationTargetType = rawEntry.type;
+            if (typeof verificationTargetType !== "string" ||
+                !["static", "unit", "component", "integration", "mock"].includes(verificationTargetType)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target entry.type must be one of static | unit | component | integration | mock (received ${JSON.stringify(verificationTargetType ?? null)}); for a runtime behavior check use type=mock or type=integration`,
+                });
+            }
+            // 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));
+        },
+    };
+}
+/**
+ * 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,
+    });
+    // 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 });
+                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,
+                    });
+                    continue;
+                }
+                const bytes = await readFile(absolute);
+                evidence.push({
+                    path: relative,
+                    sha256: createHash("sha256").update(bytes).digest("hex"),
+                    fresh: true,
+                });
+            }
+            catch {
+                evidence.push({ path: relative, sha256: "0".repeat(64), fresh: false });
+            }
+        }
+        return evidence;
+    };
+    async function adoptScoutFact(kind, fact) {
+        try {
+            const requestId = `${attemptId}:${kind}:${randomUUID()}`;
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+            });
+            const committed = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: fact,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                ok: true,
+                kind,
+                eventId: committed.eventId,
+                revision: committed.revision,
+                error: "",
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                kind,
+                code: error?.code,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    const recordTargetSurfaceTool = defineTool({
+        name: "record_target_surface",
+        label: "record_target_surface",
+        description: "Commit an origin=scout target-surface fact with complete/blocked discovery status. A complete surface needs a proven target path and no unresolved paths; blocked surfaces name the unresolved paths instead of guessing. Example: {\"completeness\": \"complete\", \"entrypoint\": \"<file>\", \"implementationPaths\": [\"<dir or file>\"], \"testPaths\": [\"<file>\"], \"allowedPathConflicts\": [], \"unresolvedPaths\": []}",
+        promptSnippet: "Commit an origin=scout target-surface fact.",
+        parameters: Type.Object({
+            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 ?? [],
+                ...(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 = isFrontendFactsWriter(task)
+            ? [
+                "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(" ")
+            : 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.",
+            "Use write tools only for the bounded implementation requested by this node.",
+            "The upstream plan node's output is a BLUEPRINT, not a deliverable: reading it never satisfies this node. You MUST materialize the plan into actual working-tree changes by calling write/edit tools before claiming changed. A detailed plan that names every file, test, or snippet still requires you to write those files yourself.",
+            "Forbidden paths bound the writeSet, not the task: when the task only requires writing inside the writeSet (e.g. adding tests that call existing public APIs), a forbidden src/** does not make the task impossible — do NOT claim blocked merely because some path you never need to write is forbidden. blocked is only for when you genuinely cannot produce the required writeSet changes.",
+            outcomeInstruction,
+            `Allowed paths: ${(task.allowedPaths ?? []).join(", ") || "(none declared)"}.`,
+            `Write set: ${(task.writeSet ?? []).join(", ") || "(none declared)"}.`,
+            `Forbidden paths: ${(task.forbiddenPaths ?? []).join(", ") || "(none declared)"}.`,
+            "Preserve unrelated files. Do not edit outside allowedPaths/writeSet. Never write forbiddenPaths, .harness/dag-runs/**, or undeclared root artifacts/**.",
+            "Return concise Markdown with changed files, verification performed or still required, and residual risks.",
+            "Do not wrap the output in code fences and do not add conversational preamble.",
+        ]
+            .filter((value) => Boolean(value))
+            .join(" ");
+    }
+    // Decision Gate nodes must emit a mandatory DECISION_ENVELOPE_JSON fenced block;
+    // do not inject the global no-fence instruction that would conflict with outputContract.
+    if (task.decisionGate?.enabled === true) {
+        return [
+            `You are executing hybrid DAG node "${task.id}" (role=${role}, piPersona=${persona}, piStep=${step}, writePolicy=${writePolicy}).`,
+            "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
+            "Use read-only tools only. Do not edit, write, or commit repository files.",
+            "Return your conclusion as Markdown that includes exactly one ```DECISION_ENVELOPE_JSON fenced block (info string DECISION_ENVELOPE_JSON, not json) matching the Decision Envelope schema, plus a short evidence/risk summary.",
+            "Follow the node outputContract for the mandatory fenced block. Do not add conversational preamble outside the required Markdown structure.",
+        ].join(" ");
+    }
+    return [
+        `You are executing hybrid DAG node "${task.id}" (role=${role}, piPersona=${persona}, piStep=${step}, writePolicy=${writePolicy}).`,
+        "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
+        "Use read-only tools only. Do not edit, write, or commit repository files.",
+        (task.readSet?.length ?? 0) > 0
+            ? `Strict read set: ${task.readSet.join(", ")}. The read tool rejects every other repository path; do not search for substitutes.`
+            : undefined,
+        "Return your conclusion as plain Markdown text suitable for downstream DAG nodes.",
+        "Do not wrap the output in code fences and do not add conversational preamble.",
+    ].join(" ");
+}
+export function resolveDagPiModelConfig(modelReference, options) {
+    const separatorIndex = modelReference.indexOf("/");
+    const qualified = separatorIndex >= 0;
+    const provider = qualified
+        ? modelReference.slice(0, separatorIndex)
+        : (DAG_PI_MODEL_PROVIDERS[modelReference] ?? DEFAULT_DAG_PI_PROVIDER);
+    const model = qualified
+        ? modelReference.slice(separatorIndex + 1)
+        : modelReference;
+    if (!provider || !model) {
+        throw new Error(`invalid DAG Pi model reference "${modelReference}": expected non-empty provider/model`);
+    }
+    const explicitThinking = options?.thinking?.trim();
+    const thinking = explicitThinking ??
+        (provider === "wizard-local" && model === "gpt-5.5" ? "low" : undefined);
+    return {
+        provider,
+        model,
+        ...(thinking ? { thinking } : {}),
+    };
+}
+const SUMMARY_STDOUT_MAX = 4_000;
+const SUMMARY_STDERR_MAX = 2_000;
+export function buildPiPromptRedactedMarkdown(prompt) {
+    const redacted = redactPromptForLog(prompt);
+    return [
+        "# Pi prompt (redacted)",
+        "",
+        `- ${redacted}`,
+        "",
+        "Full prompt text is not stored. See node `result.summary.md` for execution metadata.",
+        "",
+    ].join("\n");
+}
+export function buildPiResultSummaryMarkdown(input) {
+    const stdout = truncateOutput(input.result.stdout, SUMMARY_STDOUT_MAX);
+    const stderr = truncateOutput(input.result.stderr || "", SUMMARY_STDERR_MAX);
+    const lines = [
+        "# Pi execution summary",
+        "",
+        "## Run metadata",
+        "",
+        "| Field | Value |",
+        "|-------|-------|",
+        `| channel | ${input.context.channel} |`,
+        `| dagRunId | ${input.context.dagRunId} |`,
+        `| dagNodeId | ${input.context.dagNodeId} |`,
+        `| cwd | ${input.context.cwd} |`,
+        `| model | ${input.model} |`,
+        `| piPersona | ${input.persona} |`,
+        `| piStep | ${input.step} |`,
+        `| ok | ${input.result.ok} |`,
+        `| failureCategory | ${input.result.failureCategory} |`,
+        `| backend | ${input.result.backend ?? "(unknown)"} |`,
+        `| sdkAttempted | ${input.result.sdkAttempted ?? false} |`,
+        `| durationMs | ${input.result.durationMs} |`,
+        `| tokensUsed | ${input.result.tokensUsed} |`,
+        `| parsedEvents | ${input.result.parsedEvents} |`,
+        "",
+        "## Prompt reference",
+        "",
+        `- ${redactPromptForLog(input.prompt)}`,
+        "",
+        "## Assistant output",
+        "",
+    ];
+    if (input.result.assistantText.trim()) {
+        lines.push("```markdown", input.result.assistantText, "```", "");
+    }
+    if (stdout.text.trim()) {
+        lines.push("### raw stdout", "", "```text", stdout.text, "```", "");
+        if (stdout.truncated)
+            lines.push("_(stdout truncated)_", "");
+    }
+    if (stderr.text.trim()) {
+        lines.push("### stderr", "", "```text", stderr.text, "```", "");
+        if (stderr.truncated)
+            lines.push("_(stderr truncated)_", "");
+    }
+    return lines.join("\n");
+}
+export async function writePiExecutorArtifacts(artifactsDir, input) {
+    const promptPath = path.join(artifactsDir, "prompt.redacted.md");
+    const summaryPath = path.join(artifactsDir, "result.summary.md");
+    await writeTextArtifactFile(promptPath, buildPiPromptRedactedMarkdown(input.prompt));
+    await writeTextArtifactFile(summaryPath, buildPiResultSummaryMarkdown(input));
+    return { promptPath, summaryPath };
+}
+/**
+ * Run-owned per-node Pi extension facts (plan 2026-08-21): requested ids,
+ * resolved packages (with absolute entry paths), and degraded/missing ids.
+ * Written only for nodes that declare `piExtensions`; never into the repo-level
+ * DAG template. Best-effort: artifact failures never fail the node.
+ */
+async function writePiExtensionsArtifact(nodeArtifactsDir, requested, resolved, missing) {
+    try {
+        const runDir = path.dirname(nodeArtifactsDir);
+        const nodeId = path.basename(nodeArtifactsDir);
+        await writeDagNodeJsonArtifact(runDir, nodeId, "pi-extensions.json", {
+            schemaVersion: 1,
+            requested: [...requested],
+            resolved: resolved.map((entry) => ({
+                id: entry.id,
+                packageName: entry.packageName,
+                version: entry.version,
+                path: entry.entryPaths.join(", "),
+            })),
+            missing: missing.map((entry) => ({
+                id: entry.id,
+                reason: entry.reason,
+                ...(entry.detail ? { detail: entry.detail } : {}),
+            })),
+        });
+    }
+    catch {
+        // best-effort run fact; node execution continues
+    }
+}
+async function resolveValidatedFrontendBaseUrlFromContext(workspaceRoot, runDir) {
+    try {
+        const capability = JSON.parse(await readFile(path.join(runDir, "preflight-frontend-browser-tool-shell", "frontend-browser-capability.json"), "utf8"));
+        if (capability.status !== "ready" ||
+            capability.structuredToolName !== "playwright_cli") {
+            throw new Error("invalid capability artifact");
+        }
+    }
+    catch {
+        throw new Error("browser-command-capability-unavailable: missing or invalid frontend browser capability artifact");
+    }
+    const contextPath = path.join(workspaceRoot, "testcase", "frontend", "rag", "context.md");
+    let markdown;
+    try {
+        markdown = await readFile(contextPath, "utf8");
+    }
+    catch {
+        throw new Error("browser-command-capability-unavailable: missing frontend context.md after environment preflight");
+    }
+    const patterns = [
+        /baseUrl\s*[:=]\s*["'`]?((?:https?):\/\/[^\s"'`<>]+)/i,
+        /base[-_ ]url\s*[:=]\s*["'`]?((?:https?):\/\/[^\s"'`<>]+)/i,
+        /playwright-cli open --browser=chrome\s+((?:https?):\/\/[^\s"'`<>]+)/i,
+    ];
+    let rawBaseUrl;
+    for (const pattern of patterns) {
+        const match = markdown.match(pattern);
+        if (match?.[1]) {
+            rawBaseUrl = match[1].replace(/[)\]},.;]+$/, "");
+            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");
+    }
+    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;
+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);
+}
+/**
+ * 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.type, 40)
+                            ? { type: compactPromptString(target.type, 40) }
+                            : {}),
+                        ...(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),
+                    type: compactPromptString(entry.type, 40),
+                    commandLabel: compactPromptString(entry.commandLabel, 180),
+                    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 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");
+    };
+    // 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));
+    if (!requirementIdsProvided) {
+        queue.push({
+            id: "coverage",
+            toolNames: coverageSegment.toolNames,
+            prompt: `${input.basePrompt}\n\n${coverageSegment.instruction}`,
+        });
     }
-    const contextPath = path.join(workspaceRoot, "testcase", "frontend", "rag", "context.md");
-    let markdown;
-    try {
-        markdown = await readFile(contextPath, "utf8");
+    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),
+        }));
     }
-    catch {
-        throw new Error("browser-command-capability-unavailable: missing frontend context.md after environment preflight");
+    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),
+        });
     }
-    const patterns = [
-        /baseUrl\s*[:=]\s*["'`]?((?:https?):\/\/[^\s"'`<>]+)/i,
-        /base[-_ ]url\s*[:=]\s*["'`]?((?:https?):\/\/[^\s"'`<>]+)/i,
-        /playwright-cli open --browser=chrome\s+((?:https?):\/\/[^\s"'`<>]+)/i,
-    ];
-    let rawBaseUrl;
-    for (const pattern of patterns) {
-        const match = markdown.match(pattern);
-        if (match?.[1]) {
-            rawBaseUrl = match[1].replace(/[)\]},.;]+$/, "");
+    const finalizeSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "finalize");
+    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.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 = buildPhasePrompt(segment, session.missingFacts);
+            }
+        }
+        const committedBefore = input.committedFactCount();
+        input.setActiveRequirementScope?.(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 isUxLocalSession = session.id.startsWith("ux-local-");
+        const missingPhase = 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];
+        const promptForMissingPhase = (missing) => session.coverageOnly
+            ? buildCoveragePrompt(session.coverageSlice ?? [], 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;
+        }
+        // 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.
+        const coverageSlice = session.coverageOnly ? session.coverageSlice : 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);
+            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 result;
     }
-    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 (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 (last ?? {
+        ok: false,
+        stdout: "",
+        stderr: "frontend plan segmentation produced no session",
+        failureCategory: "empty-output",
+        durationMs: 0,
+    });
 }
-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 +3620,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 +3709,163 @@ 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,
+            });
+            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 +3874,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 +3937,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 +3952,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 +3964,69 @@ 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,
+                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 } : {}),
+            });
+        }
     }
     catch (error) {
         if (playwrightToolContext) {
@@ -734,10 +4064,127 @@ 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);
+    // 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) {
+        // 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 +4317,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,8 +4367,89 @@ 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";
         }
@@ -1045,6 +4572,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 +4598,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 +4621,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,
     };
 }