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

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,7 @@ import { parseLedgerJson } from "../task/source-prepare/ledger.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
+import { pathMatchesPattern } from "../shared/git-progress.js";
 import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
@@ -235,6 +236,16 @@ export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
 ];
 export const FRONTEND_PLAN_TERMINAL_TOOL_NAMES = ["finalize_plan"];
 export const FRONTEND_PLAN_ADOPT_TOOL_NAMES = ["adopt_staged_fact"];
+/**
+ * Inter-call delay for high-frequency frontend record_* tools. Incremental
+ * submission (one model response per 1-5 entries) means dozens of sequential
+ * API round trips in a few minutes; third-party gateways (huu.dqy.ink) trip
+ * rate limits whose windows exceed normal API RPM even at ~13 calls/min. A
+ * short fixed delay before each tool body keeps the sustained rate under
+ * typical thresholds while batching cuts the total call count.
+ */
+const FRONTEND_RECORD_TOOL_THROTTLE_MS = 1000;
+const sleepRecordThrottle = () => new Promise((resolve) => setTimeout(resolve, FRONTEND_RECORD_TOOL_THROTTLE_MS));
 /** M5: `frontend-review-pi` emits its authoritative terminal verdict through
  * committed typed tools instead of the legacy JSON verdict parse. */
 export function isFrontendReviewTypedTerminalNode(task) {
@@ -261,6 +272,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 +327,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,
         ];
@@ -829,8 +882,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 +902,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;
     }
@@ -924,7 +979,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 +995,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 +1027,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 +1106,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,14 +1118,16 @@ 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) {
+            await sleepRecordThrottle();
             const rawChoice = params?.choice;
             if (!isRecordObject(rawChoice)) {
                 return planToolReceipt({
@@ -1062,6 +1137,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 +1147,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()}`, {
@@ -1099,7 +1186,7 @@ export async function createFrontendPlanLedgerTools(input) {
     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),
@@ -1195,7 +1282,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 +1298,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 +1321,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 +1333,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,12 +1353,13 @@ 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 }),
         async execute(_toolCallId, params) {
+            await sleepRecordThrottle();
             const rawEntry = params?.entry;
             if (!isRecordObject(rawEntry)) {
                 return planToolReceipt({
@@ -1280,7 +1368,25 @@ 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;
+            }
             // 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
@@ -1310,12 +1416,13 @@ 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 }),
         async execute(_toolCallId, params) {
+            await sleepRecordThrottle();
             const rawEntry = params?.entry;
             if (!isRecordObject(rawEntry)) {
                 return planToolReceipt({
@@ -1324,6 +1431,52 @@ 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`,
+                });
+            }
             // 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 +1484,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,12 +1533,13 @@ 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 }),
         async execute(_toolCallId, params) {
+            await sleepRecordThrottle();
             const rawEntry = params?.entry;
             if (!isRecordObject(rawEntry)) {
                 return planToolReceipt({
@@ -1353,6 +1549,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 +1593,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({
@@ -1597,10 +1865,11 @@ 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) {
+            await sleepRecordThrottle();
             const result = await adoptContractFact(kind, {
                 kind,
                 origin: "contract",
@@ -1753,6 +2022,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 +2088,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 +2127,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) {
@@ -2524,6 +2809,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,
@@ -2806,6 +3093,22 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         }
     }
     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;