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

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

@@ -16,6 +16,7 @@ import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation
 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";
@@ -236,16 +237,6 @@ 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) {
@@ -395,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];
@@ -483,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",
@@ -932,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);
@@ -1127,7 +1091,6 @@ export async function createFrontendPlanLedgerTools(input) {
             stylingStrategy: optionalString,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
-            await sleepRecordThrottle();
             const rawChoice = params?.choice;
             if (!isRecordObject(rawChoice)) {
                 return planToolReceipt({
@@ -1180,7 +1143,16 @@ 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({
@@ -1264,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
@@ -1359,7 +1351,6 @@ export async function createFrontendPlanLedgerTools(input) {
             entry: requirementSchema,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
-            await sleepRecordThrottle();
             const rawEntry = params?.entry;
             if (!isRecordObject(rawEntry)) {
                 return planToolReceipt({
@@ -1387,11 +1378,26 @@ export async function createFrontendPlanLedgerTools(input) {
                 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;
@@ -1422,7 +1428,6 @@ export async function createFrontendPlanLedgerTools(input) {
             entry: verificationTargetSchema,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
-            await sleepRecordThrottle();
             const rawEntry = params?.entry;
             if (!isRecordObject(rawEntry)) {
                 return planToolReceipt({
@@ -1477,6 +1482,18 @@ export async function createFrontendPlanLedgerTools(input) {
                     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.
@@ -1539,7 +1556,6 @@ export async function createFrontendPlanLedgerTools(input) {
             entry: evidenceGapSchema,
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
-            await sleepRecordThrottle();
             const rawEntry = params?.entry;
             if (!isRecordObject(rawEntry)) {
                 return planToolReceipt({
@@ -1732,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) {
@@ -1869,7 +1898,6 @@ export async function createFrontendContractTools(input) {
         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",
@@ -2524,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);
@@ -2906,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),
@@ -2922,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 }
                 : {}),
@@ -2935,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) {
@@ -3072,25 +3311,10 @@ 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 &&

package/dist/task/contract/adopt.js

@@ -90,6 +90,10 @@ export async function adoptTaskContract(input) {
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(state.ref?.sourceHashes.requirementLedgerSha256 &&
+                bytes.requirementLedgerBytes !== null
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({

package/dist/task/contract/import-revision.js

@@ -45,6 +45,10 @@ export async function refreshManagedContractAfterImport(input) {
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(state2.ref.sourceHashes.requirementLedgerSha256 &&
+                bytes.requirementLedgerBytes !== null
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -539,6 +539,18 @@ export const frontendImplementationContractSchema = z
                     message: `unknown verification target ${targetId}`,
                     path: ["requirements"],
                 });
+        // Interactions bind to VTs too: an interaction whose behavior
+        // verification points at an unmaterialized VT is untraceable —
+        // r20 review finding (dangling *-BEHAVIOR references sailed
+        // through plan/design/implement to the final review).
+        for (const interaction of value.interactions)
+            for (const targetId of interaction.verificationTargetIds)
+                if (!verificationIds.includes(targetId))
+                    ctx.addIssue({
+                        code: "custom",
+                        message: `interaction "${interaction.name}" references unknown verification target ${targetId}`,
+                        path: ["interactions"],
+                    });
         // Source fidelity ledger binding (AC-005/AC-006): 绑定携带
         // requirementToFragments（ledger v2）时，每个 requirement 必须携带
         // 非空 sourceFragmentIds，否则 fail closed（防引用伪造/缺失）。
@@ -570,12 +582,23 @@ export const frontendImplementationContractSchema = z
         if (state.applicable &&
             (!state.expectedBehavior ||
                 !state.implementationTargets?.length ||
-                !state.verificationTargetIds?.length))
+                !state.verificationTargetIds?.length)) {
+            // Name the state and the exact missing fields: the fixer is a
+            // model iterating on finalize receipts — it cannot fix a
+            // defect it cannot locate (r18: 39 blind finalize retries).
+            const missing = [];
+            if (!state.expectedBehavior)
+                missing.push("expectedBehavior");
+            if (!state.implementationTargets?.length)
+                missing.push("implementationTargets");
+            if (!state.verificationTargetIds?.length)
+                missing.push("verificationTargetIds");
             ctx.addIssue({
                 code: "custom",
-                message: "applicable UI state requires behavior, implementation, and verification",
+                message: `applicable UI state "${state.name}" is missing: ${missing.join(", ")} — record_state_flow it again with those fields filled`,
                 path: ["uiStates"],
             });
+        }
         if (!state.applicable && !state.notApplicableReason)
             ctx.addIssue({
                 code: "custom",
@@ -1826,12 +1849,25 @@ export async function analyzeFrontendImplementationContract(input) {
     if (parsedTargetFiles.some((file) => file.startsWith("/") || file.includes("\\")))
         fail("blocked", "invalid-output: frontend contract target paths must be relative POSIX paths", candidateJsonSha256);
     const parsedStates = asRecord(parsed)?.uiStates;
-    if (Array.isArray(parsedStates) && parsedStates.some((item) => {
-        const state = asRecord(item);
-        return state?.applicable === true &&
-            (!asString(state.expectedBehavior) || asStringArray(state.implementationTargets).length === 0 || asStringArray(state.verificationTargetIds).length === 0);
-    }))
-        fail("retryable-invalid", "invalid-output: applicable UI state requires behavior, implementation, and verification", candidateJsonSha256);
+    if (Array.isArray(parsedStates)) {
+        const incompleteStates = [];
+        for (const item of parsedStates) {
+            const state = asRecord(item);
+            if (!state || state.applicable !== true)
+                continue;
+            const missing = [];
+            if (!asString(state.expectedBehavior))
+                missing.push("expectedBehavior");
+            if (asStringArray(state.implementationTargets).length === 0)
+                missing.push("implementationTargets");
+            if (asStringArray(state.verificationTargetIds).length === 0)
+                missing.push("verificationTargetIds");
+            if (missing.length > 0)
+                incompleteStates.push(`"${asString(state.name)}": missing ${missing.join(", ")}`);
+        }
+        if (incompleteStates.length > 0)
+            fail("retryable-invalid", `invalid-output: applicable UI states incomplete — re-record each with record_state_flow filling the named fields: ${incompleteStates.join("; ")}`, candidateJsonSha256);
+    }
     const parsedMockApi = asRecord(parsed)?.mockApi;
     if (asRecord(parsedMockApi) &&
         typeof asRecord(parsedMockApi)?.strategy === "string" &&
@@ -2079,7 +2115,7 @@ const VERIFICATION_SYMBOL_MAX_CHARS = 60;
  * loading") and `describe(...)` / `it(...)` forms stay valid — a real symbol
  * may be a function name, a dotted path, or a describe/it title.
  */
-function isSuspiciousVerificationSymbol(symbol) {
+export function isSuspiciousVerificationSymbol(symbol) {
     const trimmed = symbol.trim();
     if (!trimmed)
         return false;
@@ -2126,6 +2162,17 @@ export class PlanPolicyPrecheckFailure extends Error {
  */
 export async function analyzeFrontendPlanPatchCandidate(input) {
     const analysis = await analyzeFrontendImplementationContract(input);
+    // A committed VT with a fabricated symbol is an immutable ledger fact —
+    // the record boundary rejects duplicate ids, so the model cannot overwrite
+    // it and throwing here deadlocks the receipt loop (r19: VT-AC006-BEHAVIOR).
+    // Drop suspicious symbols deterministically instead: the VT stays valid and
+    // the deterministic trace gate verifies file+command (and resolvability)
+    // after verification. Mirrors the shell materialization's drop semantics.
+    for (const target of analysis.canonical.verificationTargets) {
+        if (target.symbol && isSuspiciousVerificationSymbol(target.symbol)) {
+            target.symbol = undefined;
+        }
+    }
     // Front-load the verification-symbol shape check so fabricated symbols
     // are fixed by the plan retry ladder in-node instead of failing the
     // verify trace gate at the end of the run.