@tea-agent/loop-agent 0.39.0-beta.12 → 0.39.0-beta.14

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

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { writeDagNodeJsonArtifact, writeTextArtifactFile, } from "../infrastructure/harness/artifact-store.js";
 import { writeJsonAtomic } from "../infrastructure/harness/atomic-write.js";
 import { mapContractBlockedOwner } from "../workflows/dag/frontend-human-decision.js";
@@ -15,6 +15,8 @@ import { parseLedgerJson } from "../task/source-prepare/ledger.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
+import { isSuspiciousVerificationSymbol } from "../workflows/dag/frontend-implementation-contract.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";
@@ -261,6 +263,45 @@ export function isFrontendScoutEvidenceNode(task) {
 export function isFrontendPlanLedgerNode(task) {
     return task.id === "frontend-plan-pi";
 }
+/** Facts-first nodes whose authoritative output is a committed typed terminal
+ * fact (not the assistant text). Downstream compilation reads the flushed
+ * `<nodeId>/<file>` store and never the node narrative, so a committed
+ * terminal means the work is done. */
+const TYPED_TERMINAL_FACT_NODES = {
+    "frontend-contract-pi": {
+        file: "contract-typed-facts.jsonl",
+        kind: "contract-finalized",
+    },
+    "frontend-plan-pi": {
+        file: "plan-typed-facts.jsonl",
+        kind: "finalize_plan",
+    },
+};
+/**
+ * Accept a facts-terminal node result whose final assistant text is blank
+ * when the typed terminal fact was committed successfully. Small-output
+ * models legitimately end after the terminal tool call; without this the
+ * empty assistantText fails the node as empty-output, the failure classifier
+ * phrase-scans the whole session stream and can mislabel the committed run
+ * as rate-limit/network, and the finished ledger is thrown away for a
+ * deterministic retry that burns the full prompt budget again. Fail-closed:
+ * acceptance requires a committed terminal record from the flushed typed
+ * facts store; provider-error attempts (non-empty stderr) are never accepted
+ * by the caller.
+ */
+export async function acceptCommittedTypedTerminalFact(runDir, nodeId) {
+    const binding = TYPED_TERMINAL_FACT_NODES[nodeId];
+    if (!binding)
+        return false;
+    try {
+        const { readCommittedOriginFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+        const records = await readCommittedOriginFacts(runDir, nodeId, binding.file);
+        return records.some((record) => record.fact.kind === binding.kind);
+    }
+    catch {
+        return false;
+    }
+}
 export function resolveDagPiToolNames(task) {
     if (isFrontendReviewTypedTerminalNode(task)) {
         return [
@@ -277,8 +318,11 @@ export function resolveDagPiToolNames(task) {
         ];
     }
     if (isFrontendContractTypedNode(task)) {
+        // Contract is an incremental-commit node: the source-fidelity ledger is
+        // compiled into the <frontend_contract_input> block (node-execution), so
+        // no read tools — mirrors the plan node. Omitting read tools prevents a
+        // contract from spending its output budget re-reading the raw source.
         return [
-            ...DAG_PI_READONLY_TOOLS,
             ...FRONTEND_CONTRACT_RECORD_TOOL_NAMES,
             ...FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES,
         ];
@@ -342,10 +386,6 @@ export function scanReviewTerminalKindsFromSessionEvents(content) {
     }
     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];
@@ -430,45 +470,6 @@ export async function detectNodeReadBudget(input) {
         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",
@@ -829,8 +830,9 @@ async function loadContractRequirementInheritance(runDir) {
 }
 /**
  * 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.
+ * planner starts. The planner names a frozen requirement id and one of its
+ * fragment ids; it never needs to re-read a PRD merely to recover a
+ * path/section/line triple.
  */
 async function resolveFrontendPlanNewComponentSourceReferences(input) {
     const binding = input.sourceBinding;
@@ -848,16 +850,17 @@ async function resolveFrontendPlanNewComponentSourceReferences(input) {
         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
+            const citations = requirement.sourceFragmentIds
                 .map((fragmentId) => fragmentsById.get(fragmentId))
-                .find((candidate) => candidate !== undefined);
-            if (!fragment)
-                continue;
-            references.set(requirement.id, {
+                .filter((fragment) => fragment !== undefined)
+                .map((fragment) => ({
+                fragmentId: fragment.id,
                 path: fragment.path,
                 section: fragment.headingPath,
                 line: fragment.lineRange.start,
-            });
+            }));
+            if (citations.length > 0)
+                references.set(requirement.id, citations);
         }
         return references;
     }
@@ -877,11 +880,27 @@ export async function createFrontendPlanLedgerTools(input) {
         import("typebox"),
         import("@earendil-works/pi-coding-agent"),
     ]);
-    const { readCommittedEvents, writeTypedEventStoreJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    const { loadTypedEventStore, readCommittedEvents, writeTypedEventStoreJsonl, } = await import("../workflows/dag/frontend-typed-event-store.js");
     const { adoptStagedFact, adoptTypedEventFact, stageTypedEventFact } = await import("../workflows/dag/frontend-typed-event-transaction.js");
     const { assemblePlanPatchFromCommittedFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
     const store = input.store;
     const attemptId = input.attemptId;
+    // A retry creates a fresh executor-local store, but the plan ledger is the
+    // cross-attempt authority. Restore the committed prefix before registering
+    // tools; otherwise the first flush of a retry can overwrite facts that the
+    // previous attempt had already committed. The on-disk file contains only
+    // committed records, so loading it is also fail-closed with respect to
+    // staged/quarantined facts.
+    const persisted = await loadTypedEventStore(path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"));
+    if (persisted.records.length > 0) {
+        const existingEventIds = new Set(store.records.map((record) => record.eventId));
+        for (const record of persisted.records) {
+            if (!existingEventIds.has(record.eventId)) {
+                store.records.push(record);
+            }
+        }
+        store.revision = Math.max(store.revision, persisted.revision);
+    }
     const stringArray = Type.Array(Type.String({}));
     const optionalString = Type.Optional(Type.String({}));
     const optionalStringArray = Type.Optional(stringArray);
@@ -924,7 +943,12 @@ export async function createFrontendPlanLedgerTools(input) {
         consumer: optionalString,
     }, { additionalProperties: false });
     const mockApiSchema = Type.Object({
-        strategy: Type.String({
+        strategy: Type.Union([
+            Type.Literal("native"),
+            Type.Literal("browser-intercept"),
+            Type.Literal("request-adapter"),
+            Type.Literal("not-needed"),
+        ], {
             description: "native | browser-intercept | request-adapter | not-needed",
         }),
         activation: Type.String({}),
@@ -935,11 +959,20 @@ export async function createFrontendPlanLedgerTools(input) {
         paths: stringArray,
         conflicts: stringArray,
     }, { additionalProperties: false });
+    // Enum fields use literal unions, not advisory strings: a soft Type.String
+    // lets the model commit values like type="behavior" that pass the tool
+    // boundary, flush into the ledger, and only fail the compile-time zod enum
+    // — a deterministic attempt failure the model could have fixed in-node.
+    const verificationTargetTypeSchema = Type.Union([
+        Type.Literal("static"),
+        Type.Literal("unit"),
+        Type.Literal("component"),
+        Type.Literal("integration"),
+        Type.Literal("mock"),
+    ]);
     const verificationTargetSchema = Type.Object({
         id: Type.String({}),
-        type: Type.String({
-            description: "static | unit | component | integration | mock",
-        }),
+        type: verificationTargetTypeSchema,
         commandLabel: Type.String({}),
         file: Type.String({}),
         symbol: Type.Optional(Type.String({
@@ -958,7 +991,11 @@ export async function createFrontendPlanLedgerTools(input) {
     const uiComponentChoiceSchema = Type.Object({
         purpose: Type.String({}),
         component: Type.String({}),
-        decision: Type.String({
+        decision: Type.Union([
+            Type.Literal("specified"),
+            Type.Literal("reuse-existing"),
+            Type.Literal("new"),
+        ], {
             description: "specified | reuse-existing | new",
         }),
         specReference: Type.Optional(Type.Object({
@@ -1033,7 +1070,7 @@ export async function createFrontendPlanLedgerTools(input) {
     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.",
+        description: "Record the route selection needed by this plan. Repository target surface and file ownership belong to Scout/runtime. Example: {\"routes\": [\"/<route>\"]}",
         promptSnippet: "Record the selected routes.",
         parameters: Type.Object({ routes: stringArray }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1045,11 +1082,12 @@ export async function createFrontendPlanLedgerTools(input) {
     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).",
+        description: "Record ONE component choice (origin=plan component-choice fact). Declare every UI purpose's component selection. For decision=new, pass sourceRequirementIds containing the frozen requirement ID(s) that mandate the component and sourceFragmentId selecting one frozen citation listed in the plan checklist; the runtime validates the relation and derives the exact PRD specReference. Do not read the PRD or invent a path/line. decision=reuse-existing is only for components that already exist in the repo (e.g. reusing ActiveRunBadge's styling convention). Omit rationale for reuse-existing; it is optional. Call up to 5 component choices per assistant message (batching reduces API round trips and rate-limit risk); never more than 5 per message. Optionally include stylingStrategy (set it once, on the first call). Example: {\"choice\": {\"purpose\": \"<interaction or UI state name>\", \"component\": \"<component name>\", \"decision\": \"new\"}, \"sourceRequirementIds\": [\"<AC-XXX mandating this component>\"], \"sourceFragmentId\": \"<REQ-SRC-...>\"}",
+        promptSnippet: "Record 1-5 component choices (up to 5 per message).",
         parameters: Type.Object({
             choice: uiComponentChoiceSchema,
             sourceRequirementIds: Type.Optional(stringArray),
+            sourceFragmentId: optionalString,
             stylingStrategy: optionalString,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1062,6 +1100,7 @@ export async function createFrontendPlanLedgerTools(input) {
                 });
             }
             const sourceRequirementIds = stringList(params?.sourceRequirementIds);
+            const sourceFragmentId = nonEmptyString(params?.sourceFragmentId);
             const choice = { ...rawChoice };
             if (choice.decision === "new") {
                 if (sourceRequirementIds.length === 0) {
@@ -1071,17 +1110,28 @@ export async function createFrontendPlanLedgerTools(input) {
                         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) {
+                if (!sourceFragmentId) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: "decision=new requires sourceFragmentId selecting a frozen task-source citation",
+                    });
+                }
+                const citation = sourceRequirementIds
+                    .flatMap((id) => input.componentNewSourceReferences?.get(id) ?? [])
+                    .find((candidate) => candidate.fragmentId === sourceFragmentId);
+                if (!citation) {
                     return planToolReceipt({
                         ok: false,
                         kind: "component-choice",
-                        error: `decision=new sourceRequirementIds have no frozen task-source citation: ${sourceRequirementIds.join(", ")}`,
+                        error: `decision=new sourceFragmentId ${sourceFragmentId} is not bound to sourceRequirementIds ${sourceRequirementIds.join(", ")}`,
                     });
                 }
-                choice.specReference = specReference;
+                choice.specReference = {
+                    path: citation.path,
+                    section: citation.section,
+                    ...(citation.line !== undefined ? { line: citation.line } : {}),
+                };
             }
             const components = typeof choice.component === "string" ? [choice.component] : [];
             const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
@@ -1093,13 +1143,22 @@ export async function createFrontendPlanLedgerTools(input) {
                     ? { stylingStrategy: params.stylingStrategy }
                     : {}),
             });
-            return planToolReceipt(result);
+            // Echo the frozen citation the runtime derived: the model sees the
+            // purpose↔citation mapping it just committed and can re-record the
+            // choice (last-wins per purpose at compile) when it mismatches.
+            const echo = {
+                ...result,
+                ...(choice.specReference
+                    ? { derivedSpecReference: choice.specReference }
+                    : {}),
+            };
+            return planToolReceipt(echo);
         },
     });
     const recordStateFlowTool = defineTool({
         name: "record_state_flow",
         label: "record_state_flow",
-        description: "Record UI states and interactions as an origin=plan state-flow fact.",
+        description: "Record UI states and interactions as an origin=plan state-flow fact. Example: {\"uiStates\": [{\"name\": \"<state>\", \"applicable\": true, \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}], \"interactions\": [{\"name\": \"<interaction>\", \"trigger\": \"<user event>\", \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}]}",
         promptSnippet: "Record the plan state-flow fact.",
         parameters: Type.Object({
             uiStates: Type.Array(uiStateSchema),
@@ -1177,6 +1236,26 @@ export async function createFrontendPlanLedgerTools(input) {
                         error: "record_state_flow requires non-empty interaction.name (id is accepted only as a legacy alias)",
                     });
                 }
+                // Interaction -> VT forward references are legal only against
+                // already-committed VT facts. In the segmented flow every VT
+                // commits in the coverage segment before state flows run, so a
+                // dangling reference here is a real defect (r20: *-BEHAVIOR
+                // refs reached the final review untraceable).
+                const interactionVtIds = stringList(interaction.verificationTargetIds);
+                const committedVtIds = new Set(readCommittedEvents(store, attemptId)
+                    .map((event) => event.fact)
+                    .filter((fact) => fact.kind === "plan-verification-target")
+                    .map((fact) => fact.entry
+                    ?.id)
+                    .filter((id) => typeof id === "string"));
+                const unknownVtIds = interactionVtIds.filter((id) => !committedVtIds.has(id));
+                if (unknownVtIds.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: `record_state_flow interaction "${resolvedName}" references verification targets that are not recorded yet: ${unknownVtIds.join(", ")}; record them with record_plan_verification_target first, then re-record this state flow`,
+                    });
+                }
                 interactions.push({ ...interaction, name: resolvedName });
             }
             const states = uiStates
@@ -1195,7 +1274,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordDataFlowTool = defineTool({
         name: "record_data_flow",
         label: "record_data_flow",
-        description: "Record interaction/endpoint data flow as an origin=plan data-flow fact.",
+        description: "Record interaction/endpoint data flow as an origin=plan data-flow fact. Example: {\"interactions\": [\"<interaction name>\"], \"endpoints\": [\"GET <path>\"]}",
         promptSnippet: "Record the plan data-flow fact.",
         parameters: Type.Object({ interactions: stringArray, endpoints: stringArray }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1211,7 +1290,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordMockApiTool = defineTool({
         name: "record_mock_api",
         label: "record_mock_api",
-        description: "Record the Mock/API strategy as an origin=plan mock-api fact.",
+        description: "Record the Mock/API strategy as an origin=plan mock-api fact. Example: {\"mockApi\": {\"strategy\": \"not-needed\", \"activation\": \"n/a\", \"endpoints\": []}}",
         promptSnippet: "Record the plan mock-api fact.",
         parameters: Type.Object({ mockApi: mockApiSchema }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1234,7 +1313,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordDesignDeviationTool = defineTool({
         name: "record_design_deviation",
         label: "record_design_deviation",
-        description: "Record design evidence conflicts as an origin=plan design-deviation fact.",
+        description: "Record design evidence conflicts as an origin=plan design-deviation fact. Example: {\"designEvidence\": {\"source\": \"<source>\", \"paths\": [\"<file>\"], \"conflicts\": [\"<conflicting requirement id>\"]}}",
         promptSnippet: "Record the plan design-deviation fact.",
         parameters: Type.Object({ designEvidence: designEvidenceSchema }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1246,7 +1325,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordDependencyTool = defineTool({
         name: "record_dependency",
         label: "record_dependency",
-        description: "Record the dependency policy as an origin=plan dependency fact.",
+        description: "Record the dependency policy as an origin=plan dependency fact. Example: {\"policy\": \"<dependency policy statement>\"}",
         promptSnippet: "Record the plan dependency fact.",
         parameters: Type.Object({ policy: Type.String({}) }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -1266,8 +1345,8 @@ export async function createFrontendPlanLedgerTools(input) {
     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).",
+        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: batch up to 5 record_* calls per assistant message (4-5 entries per message minimizes API round trips and rate-limit risk); never batch more than 5 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"id\": \"<AC-XXX>\", \"implementationTargets\": [\"<deliverable file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}}",
+        promptSnippet: "Commit 1-5 plan requirement entries (up to 5 per message).",
         parameters: Type.Object({
             entry: requirementSchema,
         }, { additionalProperties: false }),
@@ -1280,12 +1359,45 @@ export async function createFrontendPlanLedgerTools(input) {
                     error: "record_plan_requirement requires a non-empty entry object",
                 });
             }
-            const entry = rawEntry;
+            let entry = rawEntry;
+            // An embedded evidenceGap with a blank description means "no gap":
+            // small-output models emit the slot defensively with description ""
+            // on every requirement. The canonical contract schema requires a
+            // non-empty gap description (min 1 char), so passing the empty slot
+            // through would deterministically fail the plan compile with
+            // invalid-output and burn every retry. Drop the empty slot — the
+            // field is optional and the runtime derives real blocking gaps when
+            // a requirement has no proof.
+            const rawGap = isRecordObject(entry.evidenceGap)
+                ? entry.evidenceGap
+                : undefined;
+            if (rawGap &&
+                typeof rawGap.description === "string" &&
+                rawGap.description.trim() === "") {
+                const { evidenceGap: _omittedGap, ...rest } = entry;
+                void _omittedGap;
+                entry = rest;
+            }
+            // Canonical-identity check: a requirement id outside the frozen
+            // canonical list (e.g. a BR-* business rule picked up from the PRD
+            // prose) would commit an immutable fact that finalize's
+            // canonical-coverage gate rejects with no in-node cure. Reject here
+            // and name the allowed ids.
+            const id = typeof entry.id === "string" ? entry.id : "";
+            if (id &&
+                input.requirementIds &&
+                input.requirementIds.length > 0 &&
+                !input.requirementIds.includes(id)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-requirement",
+                    error: `record_plan_requirement id "${id}" is not a frozen canonical requirement; canonical ids are: ${input.requirementIds.join(", ")}`,
+                });
+            }
             // A requirement id is a canonical identity: recording it twice would
             // compile a duplicate requirements[] entry and fail design review.
             // Reject duplicates 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;
@@ -1310,8 +1422,8 @@ export async function createFrontendPlanLedgerTools(input) {
     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).",
+        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: batch up to 5 record_* calls per assistant message (4-5 entries per message minimizes API round trips and rate-limit risk); never batch more than 5 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"id\": \"<VT-XXX>\", \"type\": \"unit\", \"commandLabel\": \"<frozen command label>\", \"file\": \"<test file>\", \"requirementIds\": [\"<AC-XXX>\"], \"uiStates\": []}}",
+        promptSnippet: "Commit 1-5 plan verification target entries (up to 5 per message).",
         parameters: Type.Object({
             entry: verificationTargetSchema,
         }, { additionalProperties: false }),
@@ -1324,6 +1436,64 @@ export async function createFrontendPlanLedgerTools(input) {
                     error: "record_plan_verification_target requires a non-empty entry object",
                 });
             }
+            // Belt-and-braces for providers that do not strictly enforce the
+            // tool-schema enum: reject an invalid type here with the allowed
+            // values so the model can re-record in-node instead of the whole
+            // attempt dying at compile time on the strict zod enum.
+            const verificationTargetType = rawEntry.type;
+            if (typeof verificationTargetType !== "string" ||
+                !["static", "unit", "component", "integration", "mock"].includes(verificationTargetType)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target entry.type must be one of static | unit | component | integration | mock (received ${JSON.stringify(verificationTargetType ?? null)}); for a runtime behavior check use type=mock or type=integration`,
+                });
+            }
+            // Duplicate-id rejection: committed typed facts are immutable, so
+            // re-recording the same VT id would deadlock the compile with a
+            // duplicate-id error the model cannot fix in-node. Reject here so
+            // the model submits the correction under a fresh id.
+            const vtId = typeof rawEntry.id === "string" ? rawEntry.id : "";
+            if (vtId &&
+                readCommittedEvents(store, attemptId).some((event) => {
+                    const fact = event.fact;
+                    if (!fact || fact.kind !== "plan-verification-target")
+                        return false;
+                    const entryFact = fact.entry;
+                    return entryFact?.id === vtId;
+                })) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target duplicate: verification target ${vtId} is already recorded; submit the corrected target under a new id instead`,
+                });
+            }
+            // WriteSet containment at the boundary: a committed VT fact whose
+            // file is outside the task writeSet is immutable, and the finalize
+            // pre-validation would then fail the whole attempt with no in-node
+            // cure (r17 post-merge). Reject here with the allowed patterns.
+            if (typeof rawEntry.file === "string" &&
+                input.writeSetPatterns &&
+                input.writeSetPatterns.length > 0 &&
+                !input.writeSetPatterns.some((pattern) => pathMatchesPattern(rawEntry.file, pattern))) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target file is outside the writeSet patterns [${input.writeSetPatterns.join(", ")}]: ${rawEntry.file}; verification targets must point inside the task writeSet`,
+                });
+            }
+            // Symbol shape check at the boundary: a fabricated symbol committed
+            // here is immutable (duplicate ids are rejected), and while the
+            // compile drops it, catching it now lets the model fix the target
+            // in one receipt-free step.
+            if (typeof rawEntry.symbol === "string" &&
+                isSuspiciousVerificationSymbol(rawEntry.symbol)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target symbol "${rawEntry.symbol}" looks fabricated; use a real exported/describe/it symbol from ${rawEntry.file ?? "the target file"} or omit the symbol entirely (the trace gate verifies file+command)`,
+                });
+            }
             // 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.
@@ -1331,6 +1501,48 @@ export async function createFrontendPlanLedgerTools(input) {
                 ...rawEntry,
                 uiStates: stringList(rawEntry.uiStates),
             };
+            // Cross-reference integrity at the boundary: the compile gate
+            // rejects verification targets referencing UI states or
+            // requirements that were never declared. Validate against the
+            // facts already committed in this attempt so the model fixes the
+            // reference in-node instead of burning the attempt at compile time
+            // (r7: one full attempt lost to a single unknown UI state name).
+            const committedEvents = readCommittedEvents(store, attemptId);
+            const declaredUiStateNames = new Set(committedEvents.flatMap((event) => {
+                const fact = event.fact;
+                if (!fact || fact.kind !== "state-flow")
+                    return [];
+                return (Array.isArray(fact.uiStates) ? fact.uiStates : [])
+                    .map((state) => isRecordObject(state) && typeof state.name === "string"
+                    ? state.name
+                    : "")
+                    .filter(Boolean);
+            }));
+            const unknownUiStates = entry.uiStates.filter((name) => !declaredUiStateNames.has(name));
+            if (unknownUiStates.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target references UI states that were never declared: ${unknownUiStates.join(", ")}; declare every referenced UI state with record_state_flow first, or pass uiStates: [] for intentionally unbound targets`,
+                });
+            }
+            const declaredRequirementIds = new Set(committedEvents.flatMap((event) => {
+                const fact = event.fact;
+                if (!fact || fact.kind !== "plan-requirement")
+                    return [];
+                const requirementEntry = fact.entry;
+                return typeof requirementEntry?.id === "string"
+                    ? [requirementEntry.id]
+                    : [];
+            }));
+            const unknownRequirementIds = stringList(rawEntry.requirementIds).filter((id) => !declaredRequirementIds.has(id));
+            if (unknownRequirementIds.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target references unknown requirement ids: ${unknownRequirementIds.join(", ")}; record every referenced requirement with record_plan_requirement first`,
+                });
+            }
             const result = await adoptPlanFact("plan-verification-target", `${attemptId}:record_plan_verification_target:${randomUUID()}`, { kind: "plan-verification-target", origin: "plan", entry });
             return planToolReceipt(result);
         },
@@ -1338,8 +1550,8 @@ export async function createFrontendPlanLedgerTools(input) {
     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).",
+        description: "Commit one plan evidence gap entry (origin=plan plan-evidence-gap fact). Call once per gap; entry carries requirementId, description, blocking. IMPORTANT: batch up to 5 record_* calls per assistant message (4-5 entries per message minimizes API round trips and rate-limit risk); never batch more than 5 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"requirementId\": \"<AC-XXX>\", \"description\": \"<what evidence is missing and why>\", \"blocking\": false}}",
+        promptSnippet: "Commit 1-5 plan evidence gap entries (up to 5 per message).",
         parameters: Type.Object({
             entry: evidenceGapSchema,
         }, { additionalProperties: false }),
@@ -1353,6 +1565,18 @@ export async function createFrontendPlanLedgerTools(input) {
                 });
             }
             const entry = rawEntry;
+            // A standalone evidence gap IS the gap statement: a blank description
+            // would fail the canonical contract schema (min 1 char) after the
+            // whole attempt finished. Reject at the boundary so the model writes
+            // a real description in-node instead of burning the attempt.
+            if (typeof entry.description === "string" &&
+                entry.description.trim() === "") {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-evidence-gap",
+                    error: "record_plan_evidence_gap requires a non-empty description describing the gap",
+                });
+            }
             const result = await adoptPlanFact("plan-evidence-gap", `${attemptId}:record_plan_evidence_gap:${randomUUID()}`, { kind: "plan-evidence-gap", origin: "plan", entry });
             return planToolReceipt(result);
         },
@@ -1385,6 +1609,66 @@ export async function createFrontendPlanLedgerTools(input) {
                         ? { realIntegrationGap: params.realIntegrationGap }
                         : {}),
                 };
+                // Front-load the node's compile + policy gates into the finalize
+                // receipt (same pipeline the design-policy shell and the node
+                // self-check run: merge the patch onto the runtime skeleton,
+                // then the full analyze). A failing gate used to burn an entire
+                // attempt per finding (r8/r9: ui-design-coverage, verification
+                // targets, UI-state shape, one attempt each); surfaced here the
+                // model fixes the facts and re-calls finalize_plan in-node.
+                if (input.skeleton && input.sourceBinding) {
+                    // Front-load the exact pipeline the design-policy shell and
+                    // the node self-check run (patch ⊕ skeleton -> analyze ->
+                    // policy pre-checks) into the finalize receipt. Findings
+                    // come back as fixable receipt errors instead of burning
+                    // an attempt per gate (r8/r9: coverage, verification
+                    // targets, UI-state shape each cost a full attempt).
+                    const { analyzeFrontendPlanPatchCandidate, applyFrontendContractMergePatch, FrontendContractFailure, PlanPolicyPrecheckFailure, serializeDeterministicJson, } = await import("../workflows/dag/frontend-implementation-contract.js");
+                    try {
+                        const merged = applyFrontendContractMergePatch(input.skeleton, patch);
+                        await analyzeFrontendPlanPatchCandidate({
+                            runDir: input.runDir,
+                            rawContractText: serializeDeterministicJson(merged),
+                            sourceBinding: input.sourceBinding,
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof PlanPolicyPrecheckFailure) {
+                            // Template the fix: every uncovered interaction / state
+                            // maps to a ready-to-submit record_component_choice
+                            // call. One reuse-existing choice covers all
+                            // behavioural interactions.
+                            const suggestions = error.findings
+                                .filter((finding) => finding.code === "ui-design-coverage-missing" &&
+                                finding.path)
+                                .map((finding) => ({
+                                tool: "record_component_choice",
+                                args: {
+                                    choice: {
+                                        purpose: finding.path,
+                                        component: "<name the existing or new component>",
+                                        decision: "reuse-existing",
+                                    },
+                                },
+                            }));
+                            const suggestionBlock = suggestions.length > 0
+                                ? ` Suggested record_* calls (copy, fill component, submit): ${JSON.stringify(suggestions)}`
+                                : "";
+                            return planToolReceipt({
+                                ok: false,
+                                kind: "finalize_plan",
+                                error: `finalize_plan pre-validation failed (fix the listed plan facts with record_* tools, then call finalize_plan again): ${error.message}${suggestionBlock}`,
+                            });
+                        }
+                        if (!(error instanceof FrontendContractFailure))
+                            throw error;
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "finalize_plan",
+                            error: `finalize_plan pre-validation failed (fix the listed plan facts with record_* tools, then call finalize_plan again): ${error.message}`,
+                        });
+                    }
+                }
                 const patchResult = await adoptPlanFact("target-surface", `${attemptId}:finalize_plan:patch:${randomUUID()}`, { kind: "target-surface", origin: "plan", patch });
                 if (!patchResult.ok) {
                     return planToolReceipt({
@@ -1464,6 +1748,19 @@ export async function createFrontendPlanLedgerTools(input) {
             const committed = readCommittedEvents(store, attemptId);
             await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), committed);
         },
+        committedFactCount: () => readCommittedEvents(store, attemptId).length,
+        committedRequirementIds: () => {
+            const ids = new Set();
+            for (const event of readCommittedEvents(store, attemptId)) {
+                const fact = event.fact;
+                if (!fact || fact.kind !== "plan-requirement")
+                    continue;
+                const entryFact = fact.entry;
+                if (typeof entryFact?.id === "string")
+                    ids.add(entryFact.id);
+            }
+            return ids;
+        },
     };
 }
 function isRecordObject(value) {
@@ -1597,8 +1894,8 @@ export async function createFrontendContractTools(input) {
     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.`,
+        description: `Commit an origin=contract ${kind} fact. IMPORTANT: submit incrementally — batch up to 5 record_* calls per message, starting from the FIRST message; never attempt to emit the whole contract in one response (a single large dump will be truncated and rejected). Every message must make progress by committing at least one record_* fact.`,
+        promptSnippet: `Commit 1-5 origin=contract ${kind} facts (up to 5 per message).`,
         parameters: Type.Object({}, { additionalProperties: true }),
         async execute(_toolCallId, params) {
             const result = await adoptContractFact(kind, {
@@ -1753,6 +2050,22 @@ export async function createFrontendScoutEvidenceTools(input) {
                 continue;
             }
             try {
+                // Directories are legitimate named targets (greenfield smoke: the
+                // page directory exists while the files inside it are to be
+                // created). readFile on a directory throws EISDIR, which used to
+                // mark every directory path fresh=false and structurally fail the
+                // freshness gate for create-new surfaces. stat() first: a directory
+                // counts as fresh existence evidence; its content hash is a stable
+                // directory marker since there is no single file content to hash.
+                const info = await stat(absolute);
+                if (info.isDirectory()) {
+                    evidence.push({
+                        path: relative,
+                        sha256: createHash("sha256").update(`directory:${relative}`).digest("hex"),
+                        fresh: true,
+                    });
+                    continue;
+                }
                 const bytes = await readFile(absolute);
                 evidence.push({
                     path: relative,
@@ -1803,7 +2116,7 @@ export async function createFrontendScoutEvidenceTools(input) {
     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.",
+        description: "Commit an origin=scout target-surface fact with complete/blocked discovery status. A complete surface needs a proven target path and no unresolved paths; blocked surfaces name the unresolved paths instead of guessing. Example: {\"completeness\": \"complete\", \"entrypoint\": \"<file>\", \"implementationPaths\": [\"<dir or file>\"], \"testPaths\": [\"<file>\"], \"allowedPathConflicts\": [], \"unresolvedPaths\": []}",
         promptSnippet: "Commit an origin=scout target-surface fact.",
         parameters: Type.Object({
             completeness: scoutCompleteness,
@@ -1842,7 +2155,7 @@ export async function createFrontendScoutEvidenceTools(input) {
     const recordDesignEvidenceTool = defineTool({
         name: "record_design_evidence",
         label: "record_design_evidence",
-        description: "Commit an origin=scout design-evidence fact (source, paths, conflicts).",
+        description: "Commit an origin=scout design-evidence fact (source, paths, conflicts). Example: {\"source\": \"<source>\", \"paths\": [\"<file>\"], \"conflicts\": []}",
         promptSnippet: "Commit an origin=scout design-evidence fact.",
         parameters: Type.Object({ source: Type.String({}), paths: stringArray, conflicts: stringArray }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
@@ -2239,6 +2552,171 @@ async function runFrontendDesignTerminalShadow(input) {
     }
     return input.mapped;
 }
+/** Tool subsets for the three frontend plan sessions (r17 split design). */
+const FRONTEND_PLAN_SEGMENTS = [
+    {
+        id: "coverage",
+        toolNames: new Set([
+            "record_plan_requirement",
+            "record_plan_verification_target",
+            "adopt_staged_fact",
+        ]),
+        instruction: [
+            "PLAN SEGMENT 1/3 — coverage mapping only.",
+            "Your ONLY job: for every frozen requirement, emit record_plan_requirement (requirement → implementation files) and record_plan_verification_target (verification target bound to requirement ids and files). Do NOT record components, UI states, mock, dependency, or routes — a follow-up session owns those.",
+            "Do not call finalize_plan; it is not available in this segment.",
+        ].join(" "),
+    },
+    {
+        id: "ux-decisions",
+        toolNames: new Set([
+            "record_component_choice",
+            "record_state_flow",
+            "record_data_flow",
+            "record_mock_api",
+            "record_design_deviation",
+            "record_dependency",
+            "record_route_selection",
+            "adopt_staged_fact",
+        ]),
+        instruction: [
+            "PLAN SEGMENT 2/3 — UX decisions.",
+            "Requirements and verification targets are already committed in the ledger (do NOT re-record them; duplicates are rejected). Your ONLY job: record component choices (decision=new requires sourceRequirementIds per the citation table), state flows, data flow, mock strategy, design deviation, dependency policy, and route selection.",
+            "Do not call finalize_plan; it is not available in this segment.",
+        ].join(" "),
+    },
+    {
+        id: "finalize",
+        toolNames: null,
+        instruction: [
+            "PLAN SEGMENT 3/3 — finalize.",
+            "All record_* tools are available: if a finalize_plan receipt reports missing or invalid facts, fix them with the named record_* tool and call finalize_plan again. Otherwise call finalize_plan exactly once with no extra fields.",
+        ].join(" "),
+    },
+];
+/**
+ * Coverage-batch slicing for the frontend plan split (options 1+5): the
+ * coverage segment becomes one session per requirement slice (default 4
+ * requirements), so a small output budget can never be exhausted by
+ * upfront reasoning about the whole requirement list. Zero-progress
+ * batches are split in half and retried (option 5); single-requirement
+ * zero-progress failures short-circuit to the retry ladder.
+ */
+const FRONTEND_PLAN_COVERAGE_BATCH_SIZE = 4;
+const FRONTEND_PLAN_BATCH_MAX_SESSIONS = 32;
+export async function runFrontendPlanSegmentedSessions(input) {
+    const queue = [];
+    // An empty list means "ledger unreadable / unknown" and must fall back to
+    // one unscoped coverage session — only a non-empty list batches.
+    const requirementIdsProvided = input.requirementIds !== undefined && input.requirementIds.length > 0;
+    const pending = (input.requirementIds ?? []).filter((id) => !input.committedRequirementIds?.().has(id));
+    for (const segment of FRONTEND_PLAN_SEGMENTS) {
+        if (segment.id !== "coverage") {
+            queue.push({
+                id: segment.id,
+                toolNames: segment.toolNames,
+                prompt: `${input.basePrompt}\n\n${segment.instruction}`,
+            });
+            continue;
+        }
+        // No requirement list (unreadable ledger) -> one unscoped coverage
+        // session. A provided list with everything committed (resume) skips
+        // coverage entirely.
+        if (!requirementIdsProvided || pending.length > 0) {
+            if (!requirementIdsProvided) {
+                queue.push({
+                    id: segment.id,
+                    toolNames: segment.toolNames,
+                    prompt: `${input.basePrompt}\n\n${segment.instruction}`,
+                });
+                continue;
+            }
+            for (let i = 0; i < pending.length; i += FRONTEND_PLAN_COVERAGE_BATCH_SIZE) {
+                const slice = pending.slice(i, i + FRONTEND_PLAN_COVERAGE_BATCH_SIZE);
+                queue.push({
+                    id: `coverage-batch-${i / FRONTEND_PLAN_COVERAGE_BATCH_SIZE + 1}`,
+                    toolNames: segment.toolNames,
+                    coverageSlice: slice,
+                    prompt: `${input.basePrompt}\n\n${segment.instruction}\n\nCOVERAGE BATCH: process ONLY these requirements in this session: ${slice.join(", ")}. Other requirements are handled by separate sessions; do not record them.`,
+                });
+            }
+        }
+    }
+    let last;
+    let index = 0;
+    while (index < queue.length && index < FRONTEND_PLAN_BATCH_MAX_SESSIONS) {
+        const session = queue[index];
+        const remaining = (session.coverageSlice ?? []).filter((id) => !input.committedRequirementIds?.().has(id));
+        // Resume/earlier-batch commits may already cover this slice.
+        if (session.coverageSlice && remaining.length === 0) {
+            index += 1;
+            continue;
+        }
+        let prompt = session.prompt;
+        if (session.coverageSlice) {
+            prompt = prompt.replace(/COVERAGE BATCH: process ONLY these requirements in this session: .*/, `COVERAGE BATCH: process ONLY these requirements in this session: ${remaining.join(", ")}. Other requirements are handled by separate sessions; do not record them.`);
+        }
+        const committedBefore = input.committedFactCount();
+        const customTools = input.segmentCustomTools(session.toolNames);
+        const result = await input.piStepFn({
+            ...input.sessionOptions,
+            prompt,
+            ...(customTools.length > 0
+                ? {
+                    writerToolPolicy: {
+                        requireSdk: true,
+                        customTools,
+                    },
+                }
+                : {}),
+        });
+        last = result;
+        try {
+            await input.flushLedger();
+        }
+        catch {
+            // best-effort: the node-level flush runs again after the attempt
+        }
+        const committedAfter = input.committedFactCount();
+        if (result.ok) {
+            index += 1;
+            continue;
+        }
+        const committedFactsOnlySuccess = session.id !== "finalize" &&
+            !(result.assistantText ?? "").trim() &&
+            !result.stderr.trim() &&
+            !result.timedOut &&
+            committedAfter > committedBefore;
+        if (committedFactsOnlySuccess) {
+            // The session died but banked facts: keep the progress and move on.
+            index += 1;
+            continue;
+        }
+        // Option 5: a multi-requirement coverage batch that failed with ZERO
+        // new facts and no provider stderr is the upfront-reasoning burn —
+        // halve the slice and retry instead of failing the attempt.
+        const coverageSlice = session.coverageSlice;
+        const zeroProgressBurn = coverageSlice !== undefined &&
+            coverageSlice.length > 1 &&
+            committedAfter === committedBefore &&
+            !(result.assistantText ?? "").trim() &&
+            !result.stderr.trim() &&
+            !result.timedOut;
+        if (zeroProgressBurn && coverageSlice) {
+            const half = Math.ceil(coverageSlice.length / 2);
+            queue.splice(index, 1, { ...session, coverageSlice: coverageSlice.slice(0, half) }, { ...session, coverageSlice: coverageSlice.slice(half) });
+            continue;
+        }
+        return result;
+    }
+    return (last ?? {
+        ok: false,
+        stdout: "",
+        stderr: "frontend plan segmentation produced no session",
+        failureCategory: "empty-output",
+        durationMs: 0,
+    });
+}
 export async function executeDagPiNode(input, meta, piStepFn = executePiStep, writeGuardDependencies = DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES) {
     const started = Date.now();
     const persona = resolveDagPiPersona(input.task);
@@ -2524,6 +3002,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 runDir: meta.runDir,
                 nodeId: input.task.id,
                 skeleton: input.task.structuredContractOutput?.skeleton,
+                sourceBinding: meta.spec.sourceBinding,
+                writeSetPatterns: input.task.writeSet,
                 componentNewSourceReferences: await resolveFrontendPlanNewComponentSourceReferences({
                     cwd: input.cwd,
                     sourceBinding: meta.spec.sourceBinding,
@@ -2619,10 +3099,9 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         const piExtensionPaths = piExtensionsResolution && resolvePiBackend() !== "cli-only"
             ? piExtensionsResolution.resolved.flatMap((entry) => entry.entryPaths)
             : undefined;
-        result = await piStepFn({
+        const piSessionOptions = {
             attachedFiles: [],
             modelConfig: resolveDagPiModelConfig(input.model, input.thinking ? { thinking: input.thinking } : undefined),
-            prompt: input.prompt,
             repoRoot: input.cwd,
             step,
             toolNames: resolveDagPiToolNames(input.task),
@@ -2635,7 +3114,6 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             ...(input.task.contextBudget
                 ? { contextBudget: input.task.contextBudget }
                 : {}),
-            ...(writerToolPolicy ? { writerToolPolicy } : {}),
             ...(piExtensionPaths && piExtensionPaths.length > 0
                 ? { piExtensionPaths }
                 : {}),
@@ -2648,7 +3126,55 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     bridgeActivity(activity.kind, activity.at);
                 }
                 : undefined,
-        });
+        };
+        if (isFrontendPlanLedgerNode(input.task) && planLedgerTools) {
+            // Frontend-only split: three sequential sessions with independent
+            // output budgets (coverage -> UX decisions -> finalize), mirroring the
+            // backend-test template's module sharding. Every other template keeps
+            // the single-session path below.
+            let planRequirementIds = [];
+            try {
+                const { readCommittedOriginFacts } = await import("../workflows/dag/frontend-shadow-dual-write.js");
+                const contractFacts = await readCommittedOriginFacts(meta.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl");
+                // Only requirement facts: the contract ledger also carries
+                // constraints (CON-*), evidence expectations (EV-*), handoff
+                // intents (HND-*), open questions (OQ-*) and split proposals
+                // (SPLIT-*) that all have ids — feeding those into the coverage
+                // batches made the model record non-frozen plan-requirement ids
+                // that finalize's canonical-coverage gate then rejected (r-ext2).
+                planRequirementIds = contractFacts
+                    .filter((record) => record.fact
+                    ?.kind === "requirement")
+                    .map((record) => record.fact?.id)
+                    .filter((id) => typeof id === "string")
+                    .sort();
+            }
+            catch {
+                // Unreadable ledger falls back to a single coverage session.
+            }
+            result = await runFrontendPlanSegmentedSessions({
+                piStepFn,
+                sessionOptions: piSessionOptions,
+                basePrompt: input.prompt,
+                attempt: input.attempt ?? 1,
+                committedFactCount: () => planLedgerTools.committedFactCount(),
+                requirementIds: planRequirementIds,
+                committedRequirementIds: () => planLedgerTools.committedRequirementIds(),
+                segmentCustomTools: (toolNames) => toolNames === null
+                    ? planLedgerTools.customTools
+                    : planLedgerTools.customTools.filter((tool) => typeof tool === "object" &&
+                        tool !== null &&
+                        toolNames.has(tool.name)),
+                flushLedger: () => planLedgerTools.flush(),
+            });
+        }
+        else {
+            result = await piStepFn({
+                ...piSessionOptions,
+                prompt: input.prompt,
+                ...(writerToolPolicy ? { writerToolPolicy } : {}),
+            });
+        }
     }
     catch (error) {
         if (playwrightToolContext) {
@@ -2785,27 +3311,28 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         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"),
-            };
-        }
+        // NOTE: the legacy plan read-burst guard lived here. It is dead code
+        // since the plan node went tool-only (resolveDagPiToolNames grants no
+        // read/grep/ls/find), so a read burst is structurally impossible; the
+        // read-budget path (scout etc.) keeps its own guard.
     }
     if (!isWriteTask) {
+        if (!mapped.ok &&
+            !(mapped.assistantText ?? "").trim() &&
+            !mapped.stderr.trim()) {
+            // Terminal-fact acceptance: the run finished with every fact committed
+            // (including the terminal) but no final narrative text. A timeout or
+            // provider error always leaves supervision/provider stderr, so a
+            // blank stderr here means the only "failure" is the empty text.
+            const terminalAccepted = await acceptCommittedTypedTerminalFact(meta.runDir, input.task.id);
+            if (terminalAccepted) {
+                return {
+                    ...mapped,
+                    ok: true,
+                    failureCategory: undefined,
+                };
+            }
+        }
         return mapped;
     }
     let writeGuardOk = true;