@tea-agent/loop-agent 0.39.0-beta.1 → 0.39.0-beta.11

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

@@ -1,16 +1,24 @@
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
-import { executePiStep, } from "./pi-executor.js";
-import { buildPiWriterToolPolicyContext, createPiWriterCustomTools, } from "./pi-writer-tool-policy.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 { isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
+import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
+import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
+import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
 import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
 /**
  * Writer classification for a length-stopped thinking-only attempt: the model
@@ -21,6 +29,15 @@ import { redactSecrets, truncateUtf8Preview } from "../shared/preview.js";
  * 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 {
@@ -163,6 +180,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)) {
@@ -174,35 +199,1694 @@ export function resolveDagPiStepName(task) {
         if (task.role) {
             return PI_WRITE_ROLE_TO_STEP[task.role];
         }
-        return "implement";
-    }
-    return resolvePiExecutorStep(resolveDagPiPersona(task));
-}
-export function resolveDagPiToolNames(task) {
-    if (!isDagPiWriteTask(task))
-        return [...DAG_PI_READONLY_TOOLS];
-    const tools = [...DAG_PI_WRITE_TOOLS];
-    // Pi SDK activates custom tools only when they are in this explicit list.
-    // Command capabilities (playwright_cli) stay capability-gated; read-only nodes never get command tools.
-    if (dagCommandPolicyAllows(task.commandPolicy, "playwright-cli")) {
-        tools.push("playwright_cli");
+        return "implement";
+    }
+    return resolvePiExecutorStep(resolveDagPiPersona(task));
+}
+/** A+B: `frontend-contract-pi` incremental record tools (origin=contract). */
+export const FRONTEND_CONTRACT_RECORD_TOOL_NAMES = [
+    "record_requirement",
+    "record_constraint",
+    "record_evidence_expectation",
+    "record_handoff_intent",
+    "record_open_question",
+    "record_split_proposal",
+];
+export const FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES = [
+    "finalize_contract",
+];
+/** A+B: `frontend-scout-pi` incremental evidence tools (origin=scout). */
+export const FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES = [
+    "record_target_surface",
+    "record_design_evidence",
+];
+/** A+B: `frontend-plan-pi` incremental record tools (origin=plan). */
+export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
+    "record_route_selection",
+    "record_component_choice",
+    "record_state_flow",
+    "record_data_flow",
+    "record_mock_api",
+    "record_design_deviation",
+    "record_dependency",
+    "record_plan_requirement",
+    "record_plan_verification_target",
+    "record_plan_evidence_gap",
+];
+export const FRONTEND_PLAN_TERMINAL_TOOL_NAMES = ["finalize_plan"];
+export const FRONTEND_PLAN_ADOPT_TOOL_NAMES = ["adopt_staged_fact"];
+/** M5: `frontend-review-pi` emits its authoritative terminal verdict through
+ * committed typed tools instead of the legacy JSON verdict parse. */
+export function isFrontendReviewTypedTerminalNode(task) {
+    return task.id === "frontend-review-pi";
+}
+/** M8: `frontend-design-review-pi` emits its authoritative terminal verdict
+ * through committed typed tools (`approve_design` / `request_design_changes`)
+ * instead of the legacy first-line `VERDICT: pass|request-revision` text. */
+export function isFrontendDesignTypedTerminalNode(task) {
+    return task.id === "frontend-design-review-pi";
+}
+/** A+B: `frontend-contract-pi` submits its contract through incremental typed
+ * tools + the `finalize_contract` terminal (origin=contract). */
+export function isFrontendContractTypedNode(task) {
+    return task.id === "frontend-contract-pi";
+}
+/** A+B: `frontend-scout-pi` submits target-surface/design-evidence through
+ * incremental evidence tools (origin=scout). */
+export function isFrontendScoutEvidenceNode(task) {
+    return task.id === "frontend-scout-pi";
+}
+/** A+B: `frontend-plan-pi` records its decision ledger through seven
+ * incremental `record_*` tools and closes with `finalize_plan`. */
+export function isFrontendPlanLedgerNode(task) {
+    return task.id === "frontend-plan-pi";
+}
+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)) {
+        return [
+            ...DAG_PI_READONLY_TOOLS,
+            ...FRONTEND_CONTRACT_RECORD_TOOL_NAMES,
+            ...FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES,
+        ];
+    }
+    if (isFrontendScoutEvidenceNode(task)) {
+        return [...DAG_PI_READONLY_TOOLS, ...FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES];
+    }
+    if (isFrontendPlanLedgerNode(task)) {
+        return [
+            // Plan is a decision-only node. Contract/scout own source and repository
+            // discovery; omitting read tools prevents a planner from spending its
+            // output budget reconstructing already-frozen evidence.
+            ...FRONTEND_PLAN_RECORD_TOOL_NAMES,
+            ...FRONTEND_PLAN_TERMINAL_TOOL_NAMES,
+            ...FRONTEND_PLAN_ADOPT_TOOL_NAMES,
+        ];
+    }
+    if ((task.readSet?.length ?? 0) > 0) {
+        return isDagPiWriteTask(task) ? ["read", "edit", "write"] : ["read"];
+    }
+    if (!isDagPiWriteTask(task))
+        return [...DAG_PI_READONLY_TOOLS];
+    const tools = [...DAG_PI_WRITE_TOOLS];
+    // Pi SDK activates custom tools only when they are in this explicit list.
+    // Command capabilities (playwright_cli) stay capability-gated; read-only nodes never get command tools.
+    if (dagCommandPolicyAllows(task.commandPolicy, "playwright-cli")) {
+        tools.push("playwright_cli");
+    }
+    return tools;
+}
+export const FRONTEND_REVIEW_TERMINAL_TOOL_NAMES = new Set([
+    "approve_review",
+    "request_review_changes",
+]);
+/**
+ * Fail-closed scanner for the two committed review terminal tools. Mirrors
+ * M4's `countWriteToolEventsFromSessionEvents` pattern: an unparseable line
+ * never counts as a terminal fact, so a corrupt/empty log cannot inflate the
+ * typed verdict.
+ */
+export function scanReviewTerminalKindsFromSessionEvents(content) {
+    const kinds = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_REVIEW_TERMINAL_TOOL_NAMES.has(event.toolName)) {
+            kinds.push(event.toolName);
+        }
+    }
+    return kinds;
+}
+/** Read-only discovery tool budget for frontend-plan-pi. Exceeding it means
+ * the plan re-read upstream outputs/sources instead of trusting typed facts,
+ * which blows up the context window (400 request-too-large). */
+const PLAN_READ_TOOL_BUDGET = 40;
+const READ_ONLY_TOOL_NAMES = new Set(["read", "grep", "ls", "find"]);
+function readEventPath(event) {
+    const candidates = [event.path, event.readPath, event.input];
+    for (const value of candidates) {
+        if (typeof value === "string")
+            return value;
+        if (value && typeof value === "object") {
+            const nested = value;
+            for (const key of ["path", "readPath", "file"]) {
+                if (typeof nested[key] === "string")
+                    return nested[key];
+            }
+        }
+    }
+    return undefined;
+}
+function eventTimestamp(event) {
+    for (const key of ["timestamp", "timestampMs", "ts", "createdAt"]) {
+        const value = event[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value < 10_000_000_000 ? value * 1000 : value;
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return undefined;
+}
+function eventBytes(event, line) {
+    const result = event.result ?? event.toolResult ?? event.output;
+    if (typeof result === "string")
+        return Buffer.byteLength(result);
+    if (result !== undefined)
+        return Buffer.byteLength(JSON.stringify(result));
+    return Buffer.byteLength(line);
+}
+export async function detectNodeReadBudget(input) {
+    if (!input.budget)
+        return [];
+    const sessionEventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    let content;
+    try {
+        content = await readFile(sessionEventsPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const stats = { files: new Set(), bytes: 0, tools: 0 };
+    let firstTs;
+    let lastTs;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.type !== "tool_execution_start" || typeof event.toolName !== "string" || !READ_ONLY_TOOL_NAMES.has(event.toolName))
+                continue;
+            stats.tools++;
+            const readPath = readEventPath(event);
+            if (readPath)
+                stats.files.add(readPath);
+            stats.bytes += eventBytes(event, line);
+            const ts = eventTimestamp(event);
+            if (ts !== undefined) {
+                firstTs ??= ts;
+                lastTs = ts;
+            }
+        }
+        catch { /* ignore malformed telemetry */ }
+    }
+    if (firstTs !== undefined && lastTs !== undefined)
+        stats.elapsedMs = Math.max(0, lastTs - firstTs);
+    const issues = [];
+    if (stats.files.size > input.budget.maxFiles)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.files.size} files (budget ${input.budget.maxFiles})`);
+    if (stats.bytes > input.budget.maxBytes)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.bytes} bytes (budget ${input.budget.maxBytes})`);
+    if (input.budget.maxMs !== undefined &&
+        stats.elapsedMs !== undefined &&
+        stats.elapsedMs > input.budget.maxMs)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.elapsedMs}ms (budget ${input.budget.maxMs}ms)`);
+    return issues;
+}
+/** Deterministic read-burst guard for frontend-plan-pi: count read-only
+ * discovery tool calls (read/grep/ls/find) from the session log. Over budget →
+ * read-burst, retried with a reduced-reading instruction. Pure scan; a
+ * successful plan under budget is never blocked. */
+export async function detectPlanReadBurst(input) {
+    const sessionEventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    let count = 0;
+    try {
+        const content = await readFile(sessionEventsPath, "utf8");
+        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" &&
+                    (event.toolName === "read" ||
+                        event.toolName === "grep" ||
+                        event.toolName === "ls" ||
+                        event.toolName === "find")) {
+                    count += 1;
+                }
+            }
+            catch {
+                // skip unparseable line
+            }
+        }
+    }
+    catch {
+        // Missing/unreadable session log → no burst detection
+        return [];
+    }
+    if (count > PLAN_READ_TOOL_BUDGET) {
+        return [
+            `frontend plan read-burst: ${count} read-only tool calls (budget ${PLAN_READ_TOOL_BUDGET}). Trust the upstream contract/scout typed facts; do not re-read contract/scout outputs or source files already captured. Minimize discovery reads, commit record_* facts directly, then finalize_plan.`,
+        ];
+    }
+    return [];
+}
+export const FRONTEND_DESIGN_TERMINAL_TOOL_NAMES = new Set([
+    "approve_design",
+    "request_design_changes",
+]);
+/**
+ * Fail-closed scanner for the two committed design terminal tools. Mirrors the
+ * review scanner: an unparseable line never counts as a terminal fact, so a
+ * corrupt/empty log cannot inflate the typed verdict.
+ */
+export function scanDesignTerminalKindsFromSessionEvents(content) {
+    const kinds = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (event !== null &&
+            typeof event === "object" &&
+            event.type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            FRONTEND_DESIGN_TERMINAL_TOOL_NAMES.has(event.toolName)) {
+            kinds.push(event.toolName);
+        }
+    }
+    return kinds;
+}
+/**
+ * M5: build the two committed typed review terminal tools (approve_review /
+ * request_review_changes). Each tool validates its parameters with the review
+ * fact zod schemas, stages + adopts a terminal fact into the typed event
+ * store, and returns a structured receipt. Terminal conflicts (a second
+ * terminal commit) are caught inside execute and returned as an error receipt
+ * rather than crashing the node.
+ */
+export async function createFrontendReviewTerminalTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { approveReviewFactSchema, readCommittedEvents, requestReviewChangesFactSchema, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.String({
+            description: "Critical | Important | Minor | Info",
+        }),
+        file: Type.Optional(Type.String({})),
+        line: Type.Optional(Type.Number({})),
+        issue: Type.String({}),
+        requiredChange: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const approveParameters = Type.Object({
+        findings: Type.Array(findingSchema, {
+            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
+        }),
+    }, { additionalProperties: false });
+    const requestParameters = Type.Object({
+        issueCategory: Type.Enum({
+            "implementation-mismatch": "implementation-mismatch",
+            "approved-design-defect": "approved-design-defect",
+            "target-surface-defect": "target-surface-defect",
+            "contract-requirement-gap": "contract-requirement-gap",
+            "unknown": "unknown",
+        }, { description: "Typed issue category (five-value enum)" }),
+        evidenceRefs: Type.Array(Type.String({}), {
+            description: "Evidence refs (paths or artifact ids); at least one",
+        }),
+        findings: Type.Array(findingSchema, {
+            description: "At least one finding",
+        }),
+    }, { additionalProperties: false });
+    async function adoptReviewFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            const parsed = kind === "approve_review"
+                ? approveReviewFactSchema.parse(fact)
+                : requestReviewChangesFactSchema.parse(fact);
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+            });
+            const adopted = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: true,
+                            kind,
+                            eventId: adopted.eventId,
+                            revision: adopted.revision,
+                        }),
+                    },
+                ],
+                details: {
+                    ok: true,
+                    kind,
+                    eventId: adopted.eventId,
+                    revision: adopted.revision,
+                },
+            };
+        }
+        catch (error) {
+            const code = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, kind, code, error: message }),
+                    },
+                ],
+                details: { ok: false, kind, code, error: message },
+            };
+        }
+    }
+    const approveReviewTool = defineTool({
+        name: "approve_review",
+        label: "approve_review",
+        description: "Commit the authoritative approve_review terminal fact. Use only when the implementation passes review with no Critical/Important findings.",
+        promptSnippet: "Commit the authoritative approve_review terminal verdict (no Critical/Important findings).",
+        parameters: approveParameters,
+        async execute(_toolCallId, params) {
+            return adoptReviewFact("approve_review", {
+                kind: "approve_review",
+                verdict: "approve_review",
+                findings: params?.findings ?? [],
+            });
+        },
+    });
+    const requestReviewChangesTool = defineTool({
+        name: "request_review_changes",
+        label: "request_review_changes",
+        description: "Commit the authoritative request_review_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+        promptSnippet: "Commit the authoritative request_review_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
+        parameters: requestParameters,
+        async execute(_toolCallId, params) {
+            return adoptReviewFact("request_review_changes", {
+                kind: "request_review_changes",
+                verdict: "request_review_changes",
+                issueCategory: params?.issueCategory,
+                evidenceRefs: params?.evidenceRefs,
+                findings: params?.findings,
+            });
+        },
+    });
+    return {
+        customTools: [approveReviewTool, requestReviewChangesTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "review-typed-facts.jsonl"), committed);
+        },
+    };
+}
+/**
+ * M8: build the two committed typed design terminal tools (approve_design /
+ * request_design_changes). Each tool validates its parameters with the design
+ * fact zod schemas, stages + adopts a terminal fact into the typed event
+ * store, and returns a structured receipt. Terminal conflicts are caught
+ * inside execute and returned as an error receipt rather than crashing the
+ * node.
+ */
+export async function createFrontendDesignTerminalTools(input) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { approveDesignFactSchema, readCommittedEvents, requestDesignChangesFactSchema, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
+    const store = input.store;
+    const attemptId = input.attemptId;
+    const findingSchema = Type.Object({
+        severity: Type.String({
+            description: "Critical | Important | Minor | Info",
+        }),
+        file: Type.Optional(Type.String({})),
+        line: Type.Optional(Type.Number({})),
+        issue: Type.String({}),
+        requiredChange: Type.Optional(Type.String({})),
+    }, { additionalProperties: false });
+    const approveParameters = Type.Object({
+        findings: Type.Array(findingSchema, {
+            description: "Optional informational findings (Minor/Info only; no Critical/Important on approval)",
+        }),
+    }, { additionalProperties: false });
+    const requestParameters = Type.Object({
+        issueCategory: Type.Enum({
+            "implementation-mismatch": "implementation-mismatch",
+            "approved-design-defect": "approved-design-defect",
+            "target-surface-defect": "target-surface-defect",
+            "contract-requirement-gap": "contract-requirement-gap",
+            "unknown": "unknown",
+        }, { description: "Typed issue category (five-value enum)" }),
+        evidenceRefs: Type.Array(Type.String({}), {
+            description: "Evidence refs (paths or artifact ids); at least one",
+        }),
+        findings: Type.Array(findingSchema, {
+            description: "At least one finding",
+        }),
+    }, { additionalProperties: false });
+    async function adoptDesignFact(kind, fact) {
+        const requestId = randomUUID();
+        try {
+            const parsed = kind === "approve_design"
+                ? approveDesignFactSchema.parse(fact)
+                : requestDesignChangesFactSchema.parse(fact);
+            const staged = stageTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+            });
+            const adopted = await adoptTypedEventFact({
+                store,
+                requestId,
+                attemptId,
+                fact: parsed,
+                eventId: staged.eventId,
+                expectedRevision: store.revision,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: true,
+                            kind,
+                            eventId: adopted.eventId,
+                            revision: adopted.revision,
+                        }),
+                    },
+                ],
+                details: {
+                    ok: true,
+                    kind,
+                    eventId: adopted.eventId,
+                    revision: adopted.revision,
+                },
+            };
+        }
+        catch (error) {
+            const code = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, kind, code, error: message }),
+                    },
+                ],
+                details: { ok: false, kind, code, error: message },
+            };
+        }
+    }
+    const approveDesignTool = defineTool({
+        name: "approve_design",
+        label: "approve_design",
+        description: "Commit the authoritative approve_design terminal fact. Use only when the plan passes design review with no Critical/Important findings.",
+        promptSnippet: "Commit the authoritative approve_design terminal verdict (no Critical/Important findings).",
+        parameters: approveParameters,
+        async execute(_toolCallId, params) {
+            return adoptDesignFact("approve_design", {
+                kind: "approve_design",
+                verdict: "approve_design",
+                findings: params?.findings ?? [],
+            });
+        },
+    });
+    const requestDesignChangesTool = defineTool({
+        name: "request_design_changes",
+        label: "request_design_changes",
+        description: "Commit the authoritative request_design_changes terminal fact. Requires a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+        promptSnippet: "Commit the authoritative request_design_changes terminal verdict (issueCategory + evidenceRefs + findings required).",
+        parameters: requestParameters,
+        async execute(_toolCallId, params) {
+            return adoptDesignFact("request_design_changes", {
+                kind: "request_design_changes",
+                verdict: "request_design_changes",
+                issueCategory: params?.issueCategory,
+                evidenceRefs: params?.evidenceRefs,
+                findings: params?.findings,
+            });
+        },
+    });
+    return {
+        customTools: [approveDesignTool, requestDesignChangesTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "design-typed-facts.jsonl"), committed);
+        },
+    };
+}
+/**
+ * Source fidelity ledger (AC-005/AC-006): load the contract node's committed
+ * requirement facts and build a requirement-id → provenance map. The contract
+ * node declared sourceFragmentIds/sourceRefs from the ledger's
+ * requirement→fragment mapping; the plan inherits them by id so the compiled
+ * canonical contract carries authoritative provenance without the plan
+ * re-deriving (or fabricating) it. Best-effort: missing/unreadable contract
+ * ledger yields an empty map and the plan compiles as before (the design
+ * policy shell will then fail closed on missing provenance).
+ */
+async function loadContractRequirementInheritance(runDir) {
+    const { readTypedEventStoreFromJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    let records;
+    try {
+        records = await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
+    }
+    catch {
+        return new Map();
+    }
+    const byId = new Map();
+    for (const record of records) {
+        const fact = record.fact;
+        if (!fact || typeof fact !== "object")
+            continue;
+        const recordFact = fact;
+        if (recordFact.origin !== "contract" ||
+            recordFact.kind !== "requirement") {
+            continue;
+        }
+        // Contract requirement facts carry id/sourceFragmentIds/sourceRefs on
+        // the fact itself (origin=contract, kind=requirement, id, text, ...),
+        // not inside an `entry` wrapper.
+        const id = typeof recordFact.id === "string" ? recordFact.id : "";
+        if (!id)
+            continue;
+        const sourceFragmentIds = Array.isArray(recordFact.sourceFragmentIds)
+            ? recordFact.sourceFragmentIds.filter((value) => typeof value === "string")
+            : undefined;
+        const sourceRefs = Array.isArray(recordFact.sourceRefs)
+            ? recordFact.sourceRefs.filter((value) => typeof value === "string")
+            : undefined;
+        if (sourceFragmentIds || sourceRefs) {
+            byId.set(id, {
+                ...(sourceFragmentIds ? { sourceFragmentIds } : {}),
+                ...(sourceRefs ? { sourceRefs } : {}),
+            });
+        }
+    }
+    return byId;
+}
+/**
+ * Resolve task-source citations from the source-fidelity ledger before the
+ * planner starts. The planner names a frozen requirement id; 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 fragment = requirement.sourceFragmentIds
+                .map((fragmentId) => fragmentsById.get(fragmentId))
+                .find((candidate) => candidate !== undefined);
+            if (!fragment)
+                continue;
+            references.set(requirement.id, {
+                path: fragment.path,
+                section: fragment.headingPath,
+                line: fragment.lineRange.start,
+            });
+        }
+        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 { 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;
+    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.String({
+            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 });
+    const verificationTargetSchema = Type.Object({
+        id: Type.String({}),
+        type: Type.String({
+            description: "static | unit | component | integration | mock",
+        }),
+        commandLabel: Type.String({}),
+        file: Type.String({}),
+        symbol: Type.Optional(Type.String({
+            description: "Optional. Real exported identifier or describe/it title in the target file. Omit it to keep the call small — the trace gate then only verifies the file exists and the command ran. Forbidden for type=static (runtime strips it).",
+        })),
+        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.String({
+            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.",
+        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; the runtime derives its exact PRD specReference from the source-fidelity ledger. 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 once per component — one tool call per message. Optionally include stylingStrategy (set it once, on the first call).",
+        promptSnippet: "Record one component choice (one tool call per message).",
+        parameters: Type.Object({
+            choice: uiComponentChoiceSchema,
+            sourceRequirementIds: Type.Optional(stringArray),
+            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 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",
+                    });
+                }
+                const specReference = sourceRequirementIds
+                    .map((id) => input.componentNewSourceReferences?.get(id))
+                    .find((reference) => reference !== undefined);
+                if (!specReference) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: `decision=new sourceRequirementIds have no frozen task-source citation: ${sourceRequirementIds.join(", ")}`,
+                    });
+                }
+                choice.specReference = specReference;
+            }
+            const components = typeof choice.component === "string" ? [choice.component] : [];
+            const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
+                kind: "component-choice",
+                origin: "plan",
+                components,
+                uiComponentChoices: [choice],
+                ...(params?.stylingStrategy
+                    ? { stylingStrategy: params.stylingStrategy }
+                    : {}),
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordStateFlowTool = defineTool({
+        name: "record_state_flow",
+        label: "record_state_flow",
+        description: "Record UI states and interactions as an origin=plan state-flow fact.",
+        promptSnippet: "Record the plan state-flow fact.",
+        parameters: Type.Object({
+            uiStates: Type.Array(uiStateSchema),
+            interactions: Type.Array(interactionSchema),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const rawUiStates = Array.isArray(params?.uiStates)
+                ? params.uiStates
+                : [];
+            const rawInteractions = Array.isArray(params?.interactions)
+                ? params.interactions
+                : [];
+            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)",
+                    });
+                }
+                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",
+                states,
+                uiStates,
+                interactions,
+            });
+            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.",
+        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.",
+        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.",
+        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.",
+        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; entry carries id, implementationTargets, verificationTargetIds, and optional expectedOutcome (omit it — the runtime derives the outcome text from the contract requirement). Each requirement id must be recorded EXACTLY once — re-recording the same id is rejected as a duplicate and would compile a duplicated requirements[] entry. IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        promptSnippet: "Commit one plan requirement entry (one tool call per message).",
+        parameters: Type.Object({
+            entry: requirementSchema,
+        }, { 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",
+                });
+            }
+            const entry = rawEntry;
+            // A requirement id is a canonical identity: recording it twice would
+            // compile a duplicate requirements[] entry and fail design review.
+            // Reject duplicates at the tool boundary so the model can fix them
+            // in-node instead of burning the attempt on a later validation error.
+            const id = typeof entry.id === "string" ? entry.id : "";
+            if (id) {
+                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 });
+            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). Call once per target; entry carries id, type, commandLabel, file, requirementIds, uiStates, and optional symbol (omit it — the trace gate verifies the file and command, not a symbol). IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        promptSnippet: "Commit one plan verification target entry (one tool call per message).",
+        parameters: Type.Object({
+            entry: verificationTargetSchema,
+        }, { 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",
+                });
+            }
+            // 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 entry = {
+                ...rawEntry,
+                uiStates: stringList(rawEntry.uiStates),
+            };
+            const result = await adoptPlanFact("plan-verification-target", `${attemptId}:record_plan_verification_target:${randomUUID()}`, { kind: "plan-verification-target", origin: "plan", entry });
+            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: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        promptSnippet: "Commit one plan evidence gap entry (one tool call 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;
+            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 }
+                        : {}),
+                };
+                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,
+        ],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), committed);
+        },
+    };
+}
+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.`,
+        promptSnippet: `Commit an origin=contract ${kind} fact.`,
+        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 {
+                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),
+            };
+        }
     }
-    return tools;
+    const recordTargetSurfaceTool = defineTool({
+        name: "record_target_surface",
+        label: "record_target_surface",
+        description: "Commit an origin=scout target-surface fact with complete/blocked discovery status. A complete surface needs a proven target path and no unresolved paths; blocked surfaces name the unresolved paths instead of guessing.",
+        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).",
+        promptSnippet: "Commit an origin=scout design-evidence fact.",
+        parameters: Type.Object({ source: Type.String({}), paths: stringArray, conflicts: stringArray }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const paths = params?.paths ?? [];
+            const pathEvidence = await enrichScoutPathEvidence(paths);
+            const result = await adoptScoutFact("design-evidence", {
+                kind: "design-evidence",
+                origin: "scout",
+                source: params?.source ?? "",
+                paths,
+                conflicts: params?.conflicts ?? [],
+                ...(pathEvidence.length > 0 ? { pathEvidence } : {}),
+            });
+            return receipt(result);
+        },
+    });
+    return {
+        customTools: [recordTargetSurfaceTool, recordDesignEvidenceTool],
+        flush: async () => {
+            const committed = readCommittedEvents(store, attemptId);
+            await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "scout-typed-facts.jsonl"), committed);
+        },
+    };
 }
 export function buildDagPiUserMessage(task, persona, step) {
     const role = task.role ?? "unspecified";
     const writePolicy = task.writePolicy ?? "read-only (default)";
     if (isDagPiWriteTask(task)) {
-        const outcomeInstruction = task.writerOutcomePolicy
+        const outcomeInstruction = isFrontendFactsWriter(task)
             ? [
-                "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. The runner measures your diff mechanically from git status snapshots taken before and after this node: code pasted into the response text is NOT an implementation and yields an empty diff. Use changed only after actually calling write/edit tools that persist files to disk; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed. Claiming changed without a persisted diff fails this node as invalid-output.",
-                task.writerOutcomePolicy.requireChangedFiles
-                    ? "This generation node requires a non-empty bounded diff; already-satisfied cannot complete it successfully."
-                    : undefined,
+                "Your implementation status is derived by the executor from mechanical facts (persisted write-tool events, run delta, write guard, requirement coverage, focused-check failures) — never from an IMPLEMENTATION_OUTCOME first line. Do not emit an IMPLEMENTATION_OUTCOME first line. Make real write/edit tool calls that persist files to disk: a response-only change is an empty diff that fails this node. If the contract is already satisfied, prove it with concrete target/verification evidence; a bare self-report cannot authorize an empty implementation.",
             ]
                 .filter((value) => Boolean(value))
                 .join(" ")
-            : undefined;
+            : task.writerOutcomePolicy
+                ? [
+                    "The first non-empty response line must be exactly IMPLEMENTATION_OUTCOME: changed, IMPLEMENTATION_OUTCOME: already-satisfied, or IMPLEMENTATION_OUTCOME: blocked. The runner measures your diff mechanically from git status snapshots taken before and after this node: code pasted into the response text is NOT an implementation and yields an empty diff. Use changed only after actually calling write/edit tools that persist files to disk; use already-satisfied only when the contract is already met and no file changed; use blocked when implementation cannot proceed. Claiming changed without a persisted diff fails this node as invalid-output.",
+                    task.writerOutcomePolicy.requireChangedFiles
+                        ? "This generation node requires a non-empty bounded diff; already-satisfied cannot complete it successfully."
+                        : undefined,
+                ]
+                    .filter((value) => Boolean(value))
+                    .join(" ")
+                : undefined;
         return [
             `You are executing hybrid DAG node "${task.id}" (role=${role}, piStep=${step}, writePolicy=${writePolicy}).`,
             "The system prompt contains the full DAG envelope: objective, constraints, upstream context, and task.",
@@ -235,6 +1919,9 @@ export function buildDagPiUserMessage(task, persona, step) {
         `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(" ");
@@ -327,6 +2014,36 @@ export async function writePiExecutorArtifacts(artifactsDir, input) {
     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"));
@@ -383,6 +2100,145 @@ 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;
+}
 export async function executeDagPiNode(input, meta, piStepFn = executePiStep, writeGuardDependencies = DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES) {
     const started = Date.now();
     const persona = resolveDagPiPersona(input.task);
@@ -414,9 +2270,28 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         };
     }
     let beforeStatus;
+    let beforeWorkspaceSnapshot;
     let beforePathFingerprints;
-    /** tools-only: keep SDK path sandbox; skip git baseline + post-diff write-guard hard fail. */
-    const skipGitWriteGuard = isWriteTask && input.task.writeGuardPolicy === "tools-only";
+    /** tools-only and filesystem-only keep the tool sandbox but skip Git baseline. */
+    const filesystemOnly = isWriteTask && meta.spec.backendTestWorkspaceControl === "filesystem-only";
+    const skipGitWriteGuard = isWriteTask && (input.task.writeGuardPolicy === "tools-only" || filesystemOnly);
+    if (isWriteTask && filesystemOnly) {
+        try {
+            beforeWorkspaceSnapshot = await captureWorkspaceWriteSnapshot({
+                rootCwd: input.cwd,
+                paths: input.task.writeSet ?? input.task.allowedPaths,
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `workspace filesystem baseline unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "write-guard",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     if (isWriteTask && !skipGitWriteGuard) {
         try {
             beforeStatus = await writeGuardDependencies.readGitStatusPorcelain(input.cwd, { phase: "pi-writer-before" });
@@ -453,6 +2328,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;
@@ -461,9 +2342,17 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             ok: false, stdout: "", stderr: "pi command capability requires an explicit bounded write tool profile", failureCategory: "tool-policy", durationMs: Date.now() - started,
         };
     }
-    if (isWriteTask || allowsPlaywrightCli) {
+    const strictReadSet = (input.task.readSet?.length ?? 0) > 0;
+    if (isWriteTask || allowsPlaywrightCli || strictReadSet) {
         try {
             const customTools = [];
+            if (strictReadSet) {
+                const readContext = buildPiWriterToolPolicyContext({
+                    repoRoot: input.cwd,
+                    readSet: input.task.readSet,
+                });
+                customTools.push(...(await createPiReaderCustomTools(readContext)));
+            }
             if (isWriteTask) {
                 const policyContext = buildPiWriterToolPolicyContext({
                     repoRoot: input.cwd,
@@ -471,6 +2360,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     writeSet: input.task.writeSet,
                     forbiddenPaths: input.task.forbiddenPaths,
                     writePolicy: input.task.writePolicy,
+                    readSet: input.task.readSet,
                 });
                 customTools.push(...(await createPiWriterCustomTools(policyContext)));
             }
@@ -481,10 +2371,11 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                         throw new Error(`unknown command capability: ${capability}`);
                     }
                     if (capability === "playwright-cli") {
-                        const caseId = resolveCaseIdFromWriteSet(input.task.writeSet) ??
+                        const layout = frontendTestLayoutFromSpec(meta.spec);
+                        const caseId = resolveCaseIdFromWriteSet(input.task.writeSet, layout) ??
                             input.task.id;
-                        const evidenceDir = resolveEvidenceDirFromWriteSet(input.task.writeSet) ??
-                            `testcase/frontend/evidence/${caseId}`;
+                        const evidenceDir = resolveEvidenceDirFromWriteSet(input.task.writeSet, layout) ??
+                            `${layout.evidenceDir}/${caseId}`;
                         playwrightToolContext = {
                             repoRoot: input.cwd,
                             runDir: meta.runDir,
@@ -492,7 +2383,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                             caseId,
                             evidenceDir,
                             baseUrl: await resolveValidatedFrontendBaseUrlFromContext(input.cwd, meta.runDir),
-                            inputRoot: "testcase/frontend/fixtures",
+                            inputRoot: layout.fixturesDir,
+                            layout,
                         };
                         // Cleanup must be confirmed before a new case; otherwise default-session
                         // isolation is unknown and no Pi invocation is permitted.
@@ -521,6 +2413,161 @@ 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,
+                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
@@ -529,8 +2576,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");
@@ -550,6 +2596,29 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 };
             }
         }
+        // Plan 2026-08-21 D4/D6: resolve the node's explicit Pi extension
+        // allowlist against the settings inventory. Degrade on missing packages —
+        // never fail the node — and persist requested/resolved/missing facts.
+        const piExtensionsResolution = input.task.piExtensions
+            ? resolveDagPiExtensions({
+                repoRoot: input.cwd,
+                ids: input.task.piExtensions,
+            })
+            : undefined;
+        if (piExtensionsResolution) {
+            const piBackend = resolvePiBackend();
+            const cliDegraded = piBackend === "cli-only";
+            await writePiExtensionsArtifact(path.join(meta.runDir, input.task.id), input.task.piExtensions, cliDegraded ? [] : piExtensionsResolution.resolved, cliDegraded
+                ? input.task.piExtensions.map((id) => ({
+                    id,
+                    reason: "not-installed",
+                    detail: "cli backend does not load pi extensions (sdk-only v1)",
+                }))
+                : piExtensionsResolution.missing);
+        }
+        const piExtensionPaths = piExtensionsResolution && resolvePiBackend() !== "cli-only"
+            ? piExtensionsResolution.resolved.flatMap((entry) => entry.entryPaths)
+            : undefined;
         result = await piStepFn({
             attachedFiles: [],
             modelConfig: resolveDagPiModelConfig(input.model, input.thinking ? { thinking: input.thinking } : undefined),
@@ -563,7 +2632,13 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             timeoutMs: input.timeoutMs,
             stallTimeoutMs: input.stallTimeoutMs,
             abortGraceMs: input.abortGraceMs,
+            ...(input.task.contextBudget
+                ? { contextBudget: input.task.contextBudget }
+                : {}),
             ...(writerToolPolicy ? { writerToolPolicy } : {}),
+            ...(piExtensionPaths && piExtensionPaths.length > 0
+                ? { piExtensionPaths }
+                : {}),
             onActivity: bridgeActivity
                 ? (activity) => {
                     if (activity.kind === "lease" ||
@@ -608,9 +2683,128 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         persona,
         step,
     });
-    const mapped = mapPiResultToDagNodeResult(result, input.task.writerOutcomePolicy
-        ? WRITER_OUTCOME_PROTOCOL_LINE
-        : input.task.firstProtocolLine);
+    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, 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
+        }
+        // Read-burst guard: a plan that burned dozens of read/grep/ls/find
+        // calls (re-reading upstream outputs and source files it should trust
+        // from typed facts) blows up the context window and eventually fails
+        // with 400 request-too-large. Detect it deterministically from the
+        // session log and retry with a reduced-reading instruction.
+        const readBurstIssues = input.task.readBudget?.onExhaustion === "return-guidance"
+            ? []
+            : await detectPlanReadBurst({
+                runDir: meta.runDir,
+                nodeId: input.task.id,
+            });
+        if (readBurstIssues.length > 0) {
+            return {
+                ...mapped,
+                ok: false,
+                failureCategory: "read-burst",
+                stderr: [mapped.stderr, ...readBurstIssues].filter(Boolean).join("\n\n"),
+            };
+        }
+    }
     if (!isWriteTask) {
         return mapped;
     }
@@ -618,6 +2812,27 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     let writeGuardViolations = [];
     let changeManifestAfterStatus;
     let changeManifestChangedFiles;
+    let afterWorkspaceSnapshot;
+    if (filesystemOnly && beforeWorkspaceSnapshot) {
+        try {
+            afterWorkspaceSnapshot = await captureWorkspaceWriteSnapshot({
+                rootCwd: input.cwd,
+                paths: input.task.writeSet ?? input.task.allowedPaths,
+            });
+            changeManifestChangedFiles = diffWorkspaceWriteSnapshots(beforeWorkspaceSnapshot, afterWorkspaceSnapshot);
+            const guard = validateShellWriteGuardFromDiff({
+                changedFiles: changeManifestChangedFiles,
+                task: input.task,
+                concurrentSiblingWriteSets: meta.concurrentSiblingWriteSets,
+            });
+            writeGuardOk = guard.ok;
+            writeGuardViolations = guard.violations;
+        }
+        catch (error) {
+            writeGuardOk = false;
+            writeGuardViolations = [`workspace snapshot unavailable: ${error instanceof Error ? error.message : String(error)}`];
+        }
+    }
     if (beforeStatus !== undefined) {
         let recoveryEvidence;
         let removalPendingRecheck;
@@ -723,8 +2938,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");
@@ -774,8 +2988,65 @@ 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 { collectFrontendWriterFacts, deriveFrontendWriterStatus, computeFailureFingerprint, compareFactStatusToLegacyOutcome, } = await import("../workflows/dag/frontend-writer-status.js");
+                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: [],
+                    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";
         }
@@ -790,7 +3061,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
     }
     if (writeGuardOk &&
-        beforeStatus !== undefined &&
+        (beforeStatus !== undefined || beforeWorkspaceSnapshot !== undefined) &&
         changeManifestChangedFiles !== undefined) {
         await persistWriterChangeManifest({
             runDir: meta.runDir,
@@ -800,8 +3071,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             approvalSourceNodeId: input.task.resolvedFinalWriteSetApproval?.approvalSourceNodeId,
             approvalDigest: input.task.resolvedFinalWriteSetApproval?.approvalDigest,
             changedFiles: changeManifestChangedFiles,
-            beforeStatus,
-            afterStatus: changeManifestAfterStatus ?? "",
+            beforeStatus: beforeStatus ?? JSON.stringify(beforeWorkspaceSnapshot),
+            afterStatus: changeManifestAfterStatus ?? JSON.stringify(afterWorkspaceSnapshot),
         });
     }
     let completenessFailure;
@@ -885,31 +3156,48 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     if (meta.writeGuardAttribution === "best-effort") {
         stderrParts.push("write guard note: concurrent rank writers use best-effort per-node attribution; keep same-rank writeSet entries disjoint");
     }
-    // Pure provider stall/timeout with zero workspace side effects is eligible
-    // for a single writer transport retry (implement-pi flake resilience).
-    // Partial writes, tool calls, or write-guard failures keep raw `timeout`.
-    const writerCleanTimeout = !mapped.ok &&
-        mapped.failureCategory === "timeout" &&
-        writeGuardOk &&
+    const rawFailureCategory = mapped.failureCategory;
+    const writeToolCallCount = readWriterThinkingExhaustionEvidence(result).writeToolCallCount;
+    const zeroSideEffects = writeGuardOk &&
         !completenessFailure &&
         !writerThinkingExhausted &&
-        isWriterTransportRetryCandidate(input.task) &&
+        !writerOutcomeViolation &&
         changeManifestChangedFiles !== undefined &&
         changeManifestChangedFiles.length === 0 &&
-        readWriterThinkingExhaustionEvidence(result).writeToolCallCount === 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 &&
+        ["timeout", "network", "rate-limit", "unavailable"].includes(rawFailureCategory) &&
+        zeroSideEffects;
+    const frontendCleanTimeout = !mapped.ok &&
+        rawFailureCategory === "timeout" &&
+        isWriterTransportRetryCandidate(input.task) &&
+        !isTargetTemplateTransientRetryNode(input.task) &&
+        zeroSideEffects;
+    const writerCleanTimeout = targetCleanTransport || frontendCleanTimeout;
     return {
         ...mapped,
         ok: false,
         stderr: stderrParts.filter(Boolean).join("\n\n"),
+        ...(rawFailureCategory ? { rawFailureCategory } : {}),
         failureCategory: mapped.ok
             ? 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
@@ -926,17 +3214,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,
     };
 }