@tea-agent/loop-agent 0.44.0-next.7 → 0.44.0-next.9

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

@@ -1,3 +1,6 @@
+import { reviewFindingSchema } from "../workflows/dag/frontend-typed-event-store.js";
+import { authorizeRepairAssertions } from "../workflows/dag/frontend-repair-assertions.js";
+import { createFrontendPlanProgressGuard } from "../workflows/dag/frontend-plan-progress.js";
 import { classifyFrontendPlanRecovery } from "../workflows/dag/frontend-plan-recovery-policy.js";
 import { collectFrontendExecutionGroups, frontendExecutionSchema } from "../workflows/dag/frontend-execution-groups.js";
 import { FRONTEND_SCOPE_TARGET_BYTES, packFrontendInputUnits, parseFrontendInputBlock, projectFrontendContractPrompt, projectFrontendInputScope } from "../workflows/dag/frontend-input-projection.js";
@@ -5,7 +8,7 @@ import { createDurableFrontendTools } from "../workflows/dag/frontend-durable-to
 import { sha256OfCanonicalJson } from "../task/contract/hash.js";
 import { z } from "zod";
 import { createFrontendReviewScopeProtocol, loadFrontendReviewScopes } from "../workflows/dag/frontend-review-scopes.js";
-import { observeFrontendSession } from "../workflows/dag/frontend-session-budget.js";
+import { observeFrontendFinalization, observeFrontendSession } from "../workflows/dag/frontend-session-budget.js";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
@@ -852,6 +855,7 @@ export async function createFrontendReviewTerminalTools(input) {
         line: Type.Optional(Type.Integer({ minimum: 1 })),
         issue: Type.String({ minLength: 1 }),
         requiredChange: Type.Optional(Type.String({ minLength: 1 })),
+        repairAssertions: Type.Optional(Type.Unknown({ description: "Optional mechanical checks: file-absent/state-present {check,token,source}; vt-changed also requires expectedRequirementIds. Invalid items retain diagnostics and do not remove this finding." })),
     }, { additionalProperties: false });
     const scopeProtocol = createFrontendReviewScopeProtocol({ phase: "review", inventory: input.inventory, getStore: () => store, attemptId });
     const savedFindings = () => [...new Map(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "review-finding").map(r => [r.fact.id, r.fact.finding])).values()];
@@ -859,9 +863,11 @@ export async function createFrontendReviewTerminalTools(input) {
     const recordFindingTool = defineTool({
         name: "record_review_finding", label: "record_review_finding",
         description: "Save one finding with a stable id. Submit findings incrementally, then finalize without repeating the findings array. Saved blocking findings cannot be omitted from approval; correct a finding explicitly with replace:true.",
-        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema }, { additionalProperties: false }),
+        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema, replace: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
         async execute(_callId, params) {
-            const fact = { kind: "review-finding", id: params.id, finding: params.finding };
+            const previous = readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "review-finding" && r.fact.id === params.id).at(-1);
+            const scopeIds = scopeProtocol.findingScopeIds(previous?.fact.scopeIds);
+            const fact = { kind: "review-finding", id: params.id, finding: reviewFindingSchema.parse(params.finding), ...(scopeIds ? { scopeIds } : {}) };
             const requestId = `${attemptId}:finding:${randomUUID()}`;
             const staged = stageTypedEventFact({ store, requestId, attemptId, fact });
             const adopted = await adoptTypedEventFact({ store, requestId, attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
@@ -1003,6 +1009,7 @@ export async function createFrontendDesignTerminalTools(input) {
         line: Type.Optional(Type.Integer({ minimum: 1 })),
         issue: Type.String({ minLength: 1 }),
         requiredChange: Type.Optional(Type.String({ minLength: 1 })),
+        repairAssertions: Type.Optional(Type.Unknown({ description: "Optional mechanical checks: file-absent/state-present {check,token,source}; vt-changed also requires expectedRequirementIds. Invalid items retain diagnostics and do not remove this finding." })),
     }, { additionalProperties: false });
     const scopeProtocol = createFrontendReviewScopeProtocol({ phase: "design", inventory: input.inventory, getStore: () => store, attemptId });
     const savedFindings = () => [...new Map(readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "design-finding").map(r => [r.fact.id, r.fact.finding])).values()];
@@ -1010,9 +1017,11 @@ export async function createFrontendDesignTerminalTools(input) {
     const recordFindingTool = defineTool({
         name: "record_design_finding", label: "record_design_finding",
         description: "Save one finding with a stable id. Submit findings incrementally, then finalize without repeating the findings array. Saved blocking findings cannot be omitted from approval; correct a finding explicitly with replace:true.",
-        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema }, { additionalProperties: false }),
+        parameters: Type.Object({ id: Type.String({ minLength: 1 }), finding: findingSchema, replace: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
         async execute(_callId, params) {
-            const fact = { kind: "design-finding", id: params.id, finding: params.finding };
+            const previous = readCommittedEvents(store, attemptId).filter(r => r.fact.kind === "design-finding" && r.fact.id === params.id).at(-1);
+            const scopeIds = scopeProtocol.findingScopeIds(previous?.fact.scopeIds);
+            const fact = { kind: "design-finding", id: params.id, finding: reviewFindingSchema.parse(params.finding), ...(scopeIds ? { scopeIds } : {}) };
             const requestId = `${attemptId}:finding:${randomUUID()}`;
             const staged = stageTypedEventFact({ store, requestId, attemptId, fact });
             const adopted = await adoptTypedEventFact({ store, requestId, attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
@@ -2700,7 +2709,9 @@ export async function createFrontendPlanLedgerTools(input) {
                 nextOffset: offset + items.length < values.length ? offset + items.length : null });
         },
     });
+    const planControl = createFrontendPlanProgressGuard();
     const durable = await createDurableFrontendTools({
+        planControl,
         file: path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), attemptId, store: input.store,
         setWorkingStore: next => { store = next; },
         binding: { sourceBinding: input.sourceBinding, skeleton: input.skeleton, requirementIds: input.requirementIds, writeSet: input.writeSetPatterns, declaredUiStateIds: input.declaredUiStateIds, citations: input.componentNewSourceReferences, contractInheritance },
@@ -2726,6 +2737,7 @@ export async function createFrontendPlanLedgerTools(input) {
     if (!durableFinalizePlanTool)
         throw new Error("frontend plan durable finalize tool unavailable");
     return {
+        planControl,
         customTools: [...durable.customTools, { ...readPlanFactsTool, execute: async (...args) => { await durable.flush(); return readPlanFactsTool.execute(...args); } }],
         adoptCommittedFacts: async (records) => durable.commitExternal(async () => {
             for (const record of records) {
@@ -2836,8 +2848,7 @@ export function translateDecisionPatchFindings(message, decision) {
             const base = row
                 ? `record_reuse_decision purpose "${row.purpose}" (component ${row.symbol}, decision ${row.decision}): ${issue}`
                 : `record_reuse_decision row ${choice[1]}: ${issue}`;
-            const field = choice[2];
-            return field?.startsWith("specReference")
+            return choice[2]?.startsWith("specReference") === true
                 ? `${base} — pass specSection (the AC id / task-source section it implements) on that entry, or use decision "reuse-existing"`
                 : base;
         }
@@ -2872,7 +2883,7 @@ export function translateDecisionPatchFindings(message, decision) {
 }
 /** Read the recovery child's read-only parent decision snapshot (written by
  * the recovery continuation). Absent file → undefined (fresh plan). */
-export async function readParentDecisionSnapshot(runDir, nodeId) {
+export async function readParentDecisionSnapshot(runDir, nodeId, context) {
     const snapshotPath = path.join(runDir, nodeId, "parent-decision-snapshot.json");
     let raw;
     try {
@@ -2884,8 +2895,45 @@ export async function readParentDecisionSnapshot(runDir, nodeId) {
         throw error;
     }
     const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed.facts))
+    if (parsed.schemaVersion !== 1 || parsed.schemaId !== "frontend-plan-parent-decision-snapshot-v1" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(parsed.parentRunId) || !/^[a-f0-9]{64}$/.test(parsed.parentLedgerSha256) || !Array.isArray(parsed.facts) || parsed.facts.some(fact => !fact || typeof fact.kind !== "string" || !fact.entry || typeof fact.entry !== "object" || Array.isArray(fact.entry)))
         throw new Error(`parent decision snapshot malformed: ${snapshotPath}`);
+    delete parsed.resolvedParentRunDir;
+    if (context) {
+        const { locateDagRun, readDagRunState, readDagRunSpec } = await import("../workflows/dag/lifecycle.js");
+        const state = await readDagRunState(runDir);
+        if (state.frontendRecoveryState?.parentRunId !== parsed.parentRunId || state.frontendRecoveryState.resetRootNodeId !== "frontend-plan-pi")
+            throw new Error("parent decision snapshot recovery lineage mismatch");
+        const located = await locateDagRun(context.workspaceRoot, parsed.parentRunId);
+        if (!located)
+            throw new Error("parent decision snapshot source run unavailable");
+        const parentSpec = await readDagRunSpec(located.runDir);
+        const sourceHash = sha256OfCanonicalJson(context.sourceBinding ?? null);
+        if (parsed.sourceBindingSha256 !== sourceHash || sha256OfCanonicalJson(parentSpec.sourceBinding ?? null) !== sourceHash)
+            throw new Error("parent decision snapshot source binding mismatch");
+        const ledgerPath = path.join(located.runDir, "frontend-plan-pi", "plan-decision-facts.jsonl");
+        const rawLedger = await readFile(ledgerPath, "utf8");
+        if (createHash("sha256").update(rawLedger).digest("hex") !== parsed.parentLedgerSha256)
+            throw new Error("parent decision snapshot ledger hash mismatch");
+        const { readTypedEventStoreFromJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+        const { assembleDecisionContractFromFacts } = await import("../workflows/dag/frontend-plan-decision-contract.js");
+        const records = (await readTypedEventStoreFromJsonl(ledgerPath)).filter(record => record.phase === "committed");
+        if (records.some(record => record.payloadSha256 !== sha256OfCanonicalJson(record.fact)))
+            throw new Error("parent decision snapshot ledger payload hash mismatch");
+        const actual = assembleDecisionContractFromFacts(records.map(record => record.fact));
+        if (sha256OfCanonicalJson(assembleDecisionContractFromFacts(parsed.facts)) !== sha256OfCanonicalJson(actual))
+            throw new Error("parent decision snapshot facts differ from bound ledger");
+        const { readCurrentFrontendRepairFindings } = await import("../workflows/dag/rerun-feedback.js");
+        const feedback = await readCurrentFrontendRepairFindings(located.runDir);
+        const feedbackBinding = feedback ? { sourceNodeId: feedback.sourceNodeId, ledgerSha256: feedback.ledgerSha256, terminalEventId: feedback.terminalEventId } : undefined;
+        if (sha256OfCanonicalJson(parsed.feedbackBinding ?? null) !== sha256OfCanonicalJson(feedbackBinding ?? null) || sha256OfCanonicalJson(parsed.designFindings ?? []) !== sha256OfCanonicalJson(feedback?.verdict === "request" ? feedback.findings : []))
+            throw new Error("parent decision snapshot finding source mismatch");
+        if (parsed.parentCanonicalSha256) {
+            const canonical = await readFile(path.join(located.runDir, "contracts/frontend-implementation-contract.json"), "utf8");
+            if (createHash("sha256").update(canonical).digest("hex") !== parsed.parentCanonicalSha256)
+                throw new Error("parent canonical hash mismatch");
+        }
+        parsed.resolvedParentRunDir = located.runDir;
+    }
     return parsed;
 }
 const decisionKindToToolName = (kind) => `record_${kind.replaceAll("-", "_")}`;
@@ -3287,7 +3335,7 @@ export async function createFrontendPlanDecisionTools(input) {
                 return planToolReceipt({
                     ok: false,
                     kind: "finalize_decision",
-                    code: "DECISION_SAFETY_FINDINGS",
+                    code: "DECISION_SAFETY_FINDINGS", validationStage: "safety", completedValidationStages: [],
                     error: `decision safety projection failed: ${derived.findings.join("; ")}`,
                 });
             }
@@ -3296,7 +3344,7 @@ export async function createFrontendPlanDecisionTools(input) {
                 return planToolReceipt({
                     ok: false,
                     kind: "finalize_decision",
-                    code: "DECISION_PREVALIDATION_FAILED",
+                    code: "DECISION_PREVALIDATION_FAILED", validationStage: "canonical", completedValidationStages: ["safety"],
                     error: prevalidation.error,
                 });
             }
@@ -3310,7 +3358,7 @@ export async function createFrontendPlanDecisionTools(input) {
             if (input.parentDecisionSnapshot) {
                 const { readParentCanonical, parentCanonicalContentSha256 } = await import("../workflows/dag/frontend-implementation-contract.js");
                 const { extractRepairAssertions, evaluateRepairClosure, decisionIdentitySha256 } = await import("../workflows/dag/frontend-plan-decision-contract.js");
-                const parentRunDir = path.join(input.runDir, "..", input.parentDecisionSnapshot.parentRunId);
+                const parentRunDir = input.parentDecisionSnapshot.resolvedParentRunDir ?? path.join(input.runDir, "..", input.parentDecisionSnapshot.parentRunId);
                 const parentCanonical = await readParentCanonical(parentRunDir);
                 // 1. identical-plan guard. Decisions, not prose: a rationale-only
                 // rewrite is not a repair (smoke r27 cleared a raw byte-hash guard
@@ -3328,21 +3376,26 @@ export async function createFrontendPlanDecisionTools(input) {
                     return planToolReceipt({
                         ok: false,
                         kind: "finalize_decision",
-                        code: "DECISION_REPAIR_NO_CHANGE",
+                        code: "DECISION_REPAIR_NO_CHANGE", validationStage: "recovery", completedValidationStages: input.skeleton && input.sourceBinding ? ["safety", "canonical"] : ["safety"],
                         error: "recovery finalize blocked: every structured decision row is identical to the parent run's (rationale-only edits do not count as a repair), but the review findings require changes. Correct the flagged rows (same identity, replace:true), then call finalize_decision again.",
                     });
                 }
                 // 2. per-finding closure: every deterministic assertion extracted
                 // from the parent findings must hold on the child canonical.
                 const findings = input.parentDecisionSnapshot.designFindings ?? [];
+                if (!parentCanonical && findings.some(finding => Array.isArray(finding.repairAssertions) && finding.repairAssertions.length > 0))
+                    return planToolReceipt({ ok: false, kind: "finalize_decision", code: "DECISION_REPAIR_PARENT_UNAVAILABLE", error: "Repair assertions require the bound parent canonical contract", validationStage: "recovery", completedValidationStages: input.skeleton && input.sourceBinding ? ["safety", "canonical"] : ["safety"] });
                 if (parentCanonical && findings.length > 0) {
                     const assertions = extractRepairAssertions(findings, parentCanonical);
+                    const unauthorized = authorizeRepairAssertions(assertions, { parent: parentCanonical, requirementIds: authority.requirements.map(r => r.id), stateIds: authority.behaviorGroups.flatMap(group => group.requiredStates ?? []), requiredDeliverables: (prevalidation.canonical.targets?.requiredDeliverables ?? []) });
+                    if (unauthorized.length)
+                        return planToolReceipt({ ok: false, kind: "finalize_decision", code: "DECISION_REPAIR_ASSERTION_UNAUTHORIZED", error: unauthorized.join("; "), validationStage: "recovery", completedValidationStages: input.skeleton && input.sourceBinding ? ["safety", "canonical"] : ["safety"] });
                     const closure = evaluateRepairClosure(assertions, prevalidation.canonical, parentCanonical);
                     if (!closure.closed) {
                         return planToolReceipt({
                             ok: false,
                             kind: "finalize_decision",
-                            code: "DECISION_REPAIR_NOT_CLOSED",
+                            code: "DECISION_REPAIR_NOT_CLOSED", validationStage: "recovery", completedValidationStages: input.skeleton && input.sourceBinding ? ["safety", "canonical"] : ["safety"],
                             error: `recovery finalize blocked: ${closure.unmet.length} finding(s) are still not closed — ${closure.unmet.join("; ")}. Correct the flagged rows (same identity, replace:true), then call finalize_decision again.`,
                         });
                     }
@@ -3352,7 +3405,9 @@ export async function createFrontendPlanDecisionTools(input) {
             return planToolReceipt(result);
         },
     });
+    const planControl = createFrontendPlanProgressGuard();
     const durable = await createDurableFrontendTools({
+        planControl,
         file: path.join(input.runDir, input.nodeId, "plan-decision-facts.jsonl"),
         attemptId,
         store: input.store,
@@ -3374,6 +3429,7 @@ export async function createFrontendPlanDecisionTools(input) {
     if (!durableFinalizeDecisionTool)
         throw new Error("frontend plan decision durable finalize tool unavailable");
     return {
+        planControl,
         customTools: durable.customTools,
         flush: durable.flush,
         committedFacts: () => readCommittedEvents(store, attemptId),
@@ -5610,27 +5666,6 @@ function buildFrontendPlanWorkload(input) {
             countFrontendPlanTargetSurfaces(input.basePrompt) === 1,
     };
 }
-/**
- * Requirement ids the plan coverage layout must own, in first-commit order.
- *
- * The contract ledger is append-only and `record_requirement` is incremental, so
- * the same id can legitimately be committed more than once. Deduplicating here is
- * load-bearing: `buildFrontendPlanWorkload` seeds one `unclassified` work group per
- * list entry without re-checking membership, so a repeated id produced two groups,
- * `buildWorkBatches` emitted the id twice, and the coverage-layout validator then
- * rejected the layout the runtime had derived itself (members 8 !== owners 7) as
- * FRONTEND_PLAN_LAYOUT_INVALID with failureCategory tool-policy - killing the run
- * at the plan node over a completely ordinary ledger.
- */
-export function collectFrontendPlanRequirementIds(contractFacts) {
-    return [
-        ...new Set(contractFacts
-            .filter((record) => record.fact?.kind ===
-            "requirement")
-            .map((record) => record.fact?.id)
-            .filter((id) => typeof id === "string")),
-    ];
-}
 const frontendPlanCoverageLayoutSchema = z.object({
     schemaVersion: z.literal(1),
     bindingSha256: z.string(),
@@ -5914,9 +5949,9 @@ export async function runFrontendPlanSegmentedSessions(input) {
             }
         }
         const work = [...domains.values()];
-        const scaffoldBytes = Buffer.byteLength(input.basePrompt.replace(/<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/, JSON.stringify({ ...compiledInput, requirements: [] }))) + Buffer.byteLength(JSON.stringify(input.segmentCustomTools(globalMockDataSegment.toolNames)));
+        // Work-unit packing and full provider envelope capacity have separate budgets.
         return packFrontendInputUnits(work, {
-            targetBytes: Math.max(1, (input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES) - scaffoldBytes),
+            targetBytes: input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES,
             maxUnits: input.sessionOptions.frontendExecutionPolicy?.maxScopeUnits ?? 4,
             maxCost: FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS,
             cost: (group) => group.estimatedCalls,
@@ -6170,7 +6205,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
         };
         const customTools = input.segmentCustomTools(atomicFocus ? new Set([atomicTools[atomicFocus.kind]]) : session.toolNames);
         const result = await observeFrontendSession({
-            ...input.observation, phase: `plan/${session.id}`, scopeIds: session.requirementSlice ?? session.coverageSlice ?? allRequirementIds,
+            ...input.observation, phase: `plan/${session.id}`, dispatchReason: (session.retryCount ?? 0) > 0 || !!session.missingFacts?.length || /capacity|recovery|split/.test(session.id) ? "correction" : "initial", scopeIds: session.requirementSlice ?? session.coverageSlice ?? allRequirementIds,
             prompt, userMessage: input.sessionOptions.userMessage, customTools, committedCount: input.committedFactCount, durableCommittedCount: () => lastDurableCount,
             artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-${invocationCount}.json` : undefined,
         }, async (observer) => {
@@ -6274,7 +6309,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 });
             }
         }
-        const promptForMissingPhase = (missing) => `Actionable completeness findings (repair only these facts; preserve unrelated committed facts):\n${missing.map((item) => `- fact=${item.kind}${item.id ? `/${item.id}` : ""}; requirements=${item.requirementIds.join(",")}; reason=${item.reason}; owner=${item.owner ?? "Plan"}; repairScope=${item.repairScope ?? "fact"}; next=${item.nextAction ?? "replace-fact-and-finalize"}`).join("\n")}\n\n` + (session.coverageOnly
+        const promptForMissingPhase = (missing) => session.coverageOnly
             ? buildCoveragePrompt(session.coverageSlice ?? [], missing)
             : isCompactLocalSession
                 ? buildCompactLocalPrompt(missing)
@@ -6282,7 +6317,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
                     ? buildUxRegistryPrompt(missing)
                     : isUxLocalSession
                         ? buildUxPrompt(session.requirementSlice ?? [], missing)
-                        : buildPhasePrompt(globalMockDataSegment, missing, session.requirementSlice ?? allRequirementIds));
+                        : buildPhasePrompt(globalMockDataSegment, missing, session.requirementSlice ?? allRequirementIds);
         const recovery = classifyFrontendPlanRecovery({ ...result, stopReason: readWriterThinkingExhaustionEvidence(result).stopReason });
         if (recovery === "stop")
             return { ...result, ok: false };
@@ -6530,7 +6565,12 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 optionalPlanFields.realIntegrationGap = fact.realIntegrationGap;
             }
         }
-        let finalizeResult = await input.finalizePlan(optionalPlanFields);
+        let finalizationCount = 0;
+        const finalize = () => observeFrontendFinalization({
+            ...input.observation,
+            artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-runtime-finalize-${++finalizationCount}.json` : undefined,
+        }, () => input.finalizePlan(optionalPlanFields));
+        let finalizeResult = await finalize();
         const finalizeDetails = finalizeResult && typeof finalizeResult === "object"
             ? (finalizeResult.details ?? finalizeResult)
             : finalizeResult;
@@ -6551,20 +6591,30 @@ export async function runFrontendPlanSegmentedSessions(input) {
             ].filter(Boolean).join("\n\n");
             input.setActiveRequirementScope?.([]);
             const correctionTools = input.segmentCustomTools(null);
-            const correction = await input.piStepFn({
-                ...input.sessionOptions,
-                prompt: correctionPrompt,
-                writerToolPolicy: { requireSdk: true, customTools: correctionTools },
+            const correction = await observeFrontendSession({
+                ...input.observation, phase: "plan/finalize-correction", dispatchReason: "correction",
+                scopeIds: input.requirementIds, prompt: correctionPrompt, userMessage: input.sessionOptions.userMessage,
+                customTools: correctionTools, committedCount: input.committedFactCount, durableCommittedCount: () => lastDurableCount,
+                artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-finalize-correction.json` : undefined,
+            }, async (observer) => {
+                const result = await input.piStepFn({
+                    ...input.sessionOptions, onAttemptObservation: observer, prompt: correctionPrompt,
+                    writerToolPolicy: { requireSdk: true, customTools: correctionTools },
+                });
+                try {
+                    await input.flushLedger();
+                    lastDurableCount = input.committedFactCount();
+                }
+                catch { /* node-level flush retries below */ }
+                return result;
             });
-            try {
-                await input.flushLedger();
-            }
-            catch { /* node-level flush retries below */ }
             accumulated = accumulated
                 ? combineSequentialPiResults(accumulated, correction)
                 : correction;
+            if (!correction.ok && !["invalid-output", "empty-output", "success"].includes(correction.failureCategory))
+                return { ...accumulated, ok: false, failureCategory: correction.failureCategory };
             if (correction.ok) {
-                finalizeResult = await input.finalizePlan(optionalPlanFields);
+                finalizeResult = await finalize();
             }
             const retriedDetails = finalizeResult && typeof finalizeResult === "object"
                 ? (finalizeResult.details ?? finalizeResult)
@@ -6657,7 +6707,7 @@ async function runFrontendScoutParallelSessions(input) {
             toolName: "record_target_surface",
             instruction: [
                 "PARALLEL SCOUT SHARD — target surface only.",
-                "Inspect routes, entrypoints, implementation ownership, data source, and applicable test paths.",
+                "Inspect routes, entrypoints, implementation ownership, data source, and existing test entrypoints. Inspect project source/config first; do not recursively explore dependency internals merely to reconfirm standard test-runner behavior. If a concrete required capability cannot be established from project evidence, report the precise gap.",
                 "Call record_target_surface exactly once with the complete runtime-evidenced surface. Do not call record_design_evidence.",
             ].join(" "),
         },
@@ -6666,12 +6716,16 @@ async function runFrontendScoutParallelSessions(input) {
             toolName: "record_design_evidence",
             instruction: [
                 "PARALLEL SCOUT SHARD — design evidence only.",
-                "Inspect the frontend framework, styling/theme conventions, reusable components, and relevant design/spec files.",
+                "Inspect project-owned frontend framework, styling/theme conventions, reusable components, and relevant design/spec files. The surface shard owns test-runner/environment discovery; do not duplicate its Vitest/happy-dom investigation. Stop discovery once the design evidence is sufficient and commit it.",
                 "Call record_design_evidence for the evidence you actually read. Do not call record_target_surface.",
             ].join(" "),
         },
     ];
     const outcomes = await Promise.all(shards.map(async (shard) => {
+        const cacheKey = JSON.stringify([input.runDir, input.nodeId, shard.id, input.sessionOptions.modelConfig, input.observation?.model, input.observation?.sourceDigest, input.sourceDeclaredPaths]);
+        const cached = input.completedShards?.get(cacheKey);
+        if (cached)
+            return { shard, facts: cached.facts, result: { ...cached.result, durationMs: 0, tokensUsed: 0, parsedEvents: 0, attemptedModels: [], fallbackUsed: false } };
         let shardTools;
         let shardResult;
         try {
@@ -6714,7 +6768,12 @@ async function runFrontendScoutParallelSessions(input) {
                 },
             }));
             await shardTools.flush();
-            return { shard, result: shardResult, tools: shardTools };
+            const facts = shardTools.committedFacts();
+            const expectedKind = shard.id === "design" ? "design-evidence" : "target-surface";
+            if (shardResult.ok && facts.some(record => { const fact = record.fact; return fact.kind === expectedKind && (shard.id !== "surface" || fact.completeness === "complete"); })) {
+                input.completedShards?.set(cacheKey, { result: structuredClone(shardResult), facts: structuredClone(facts) });
+            }
+            return { shard, result: shardResult, tools: shardTools, facts };
         }
         catch (error) {
             const crashMessage = `frontend scout parallel shard ${shard.id} crashed: ${error instanceof Error ? error.message : String(error)}`;
@@ -6754,8 +6813,8 @@ async function runFrontendScoutParallelSessions(input) {
     const ordered = [...outcomes].sort((left, right) => left.shard.id.localeCompare(right.shard.id));
     try {
         for (const outcome of ordered) {
-            if (outcome.result.ok && outcome.tools) {
-                await input.mainTools.adoptCommittedFacts(outcome.tools.committedFacts());
+            if (outcome.result.ok) {
+                await input.mainTools.adoptCommittedFacts(outcome.facts ?? outcome.tools?.committedFacts() ?? []);
             }
         }
     }
@@ -6782,7 +6841,7 @@ async function runFrontendScoutParallelSessions(input) {
             stderr: `${aggregate.stderr}\nfrontend scout parallel shard failed: ${failed.shard.id}`.trim(),
         };
     }
-    const committedKinds = new Set(ordered.flatMap((outcome) => (outcome.tools?.committedFacts() ?? [])
+    const committedKinds = new Set(ordered.flatMap((outcome) => (outcome.facts ?? outcome.tools?.committedFacts() ?? [])
         .map((record) => record.fact?.kind)
         .filter((kind) => typeof kind === "string")));
     const missing = ["target-surface", "design-evidence"].filter((kind) => !committedKinds.has(kind));
@@ -6987,7 +7046,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             const { createTypedEventStore } = await import("../workflows/dag/frontend-typed-event-store.js");
             const store = createTypedEventStore();
             reviewTerminalTools = await createFrontendReviewTerminalTools({
-                inventory: reviewInventory = await loadFrontendReviewScopes(meta.runDir, "review", meta.spec?.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES),
+                inventory: reviewInventory = await loadFrontendReviewScopes(meta.runDir, "review", meta.spec?.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES, input.cwd),
                 inputDigest: reviewInventory?.digest ?? createHash("sha256").update(input.prompt).digest("hex"),
                 attemptId: `${meta.runId}:${input.task.id}`,
                 store,
@@ -7144,7 +7203,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 if (useDecisionPlan) {
                     // Recovery child: read the parent snapshot before the tools so
                     // the replay and the identical-plan finalize guard share it.
-                    parentDecisionSnapshot = await readParentDecisionSnapshot(meta.runDir, input.task.id);
+                    parentDecisionSnapshot = await readParentDecisionSnapshot(meta.runDir, input.task.id, { workspaceRoot: input.cwd, sourceBinding: meta.spec.sourceBinding });
                 }
                 decisionPlanTools = await createFrontendPlanDecisionTools({
                     attemptId: `${meta.runId}:${input.task.id}`,
@@ -7334,6 +7393,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             scoutEvidenceTools &&
             input.task.complexity !== "LOW") {
             result = await runFrontendScoutParallelSessions({
+                completedShards: input.scoutCompletedShards,
                 piStepFn,
                 sessionOptions: piSessionOptions,
                 basePrompt: input.prompt,
@@ -7412,46 +7472,86 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     return base;
                 })()
                 : input.prompt;
-            const decisionResult = await piStepFn({
-                ...piSessionOptions,
-                prompt: decisionPrompt,
-                writerToolPolicy: { requireSdk: true, customTools: decisionPlanTools.customTools },
+            let decisionDurableCount = decisionPlanTools.committedFacts().length;
+            const decisionResult = await observeFrontendSession({
+                artifactPath: path.join(meta.runDir, input.task.id, "session-budget", `attempt-${input.attempt ?? 1}-decision.json`),
+                phase: "plan/decision", dispatchReason: "initial",
+                runId: meta.runId, nodeId: input.task.id, taskId: meta.spec?.sourceBinding?.taskId,
+                attempt: input.attempt ?? 1, model: input.model,
+                sourceDigest: meta.spec?.sourceBinding?.schemaVersion === 2 ? meta.spec.sourceBinding.inputDigest : undefined,
+                prompt: decisionPrompt, userMessage: piSessionOptions.userMessage, customTools: decisionPlanTools.customTools,
+                committedCount: () => decisionPlanTools.committedFacts().length,
+                durableCommittedCount: () => decisionDurableCount,
+            }, async (observer) => {
+                const result = await piStepFn({
+                    ...piSessionOptions, frontendPlanControl: decisionPlanTools.planControl, onAttemptObservation: observer, prompt: decisionPrompt,
+                    writerToolPolicy: { requireSdk: true, customTools: decisionPlanTools.customTools },
+                });
+                try {
+                    await decisionPlanTools.flush();
+                    decisionDurableCount = decisionPlanTools.committedFacts().length;
+                }
+                catch { /* node-level flush retries below */ }
+                return result;
             });
-            try {
-                await decisionPlanTools.flush();
+            if ((!decisionResult.ok && !["empty-output", "invalid-output", "unknown"].includes(decisionResult.failureCategory)) || decisionPlanTools.planControl.readStop()) {
+                const stopped = decisionPlanTools.planControl.readStop();
+                result = decisionResult.ok && stopped ? { ...decisionResult, ok: false, failureCategory: "invalid-output", stderr: `${stopped.code}: ${stopped.error}` } : decisionResult;
             }
-            catch { /* node-level flush retries below */ }
-            const finalizeResult = await decisionPlanTools.finalizeDecision();
-            const finalizeDetails = finalizeResult && typeof finalizeResult === "object"
-                ? (finalizeResult.details ?? finalizeResult)
-                : finalizeResult;
-            if (finalizeDetails && typeof finalizeDetails === "object" && finalizeDetails.ok === true) {
-                // Bridge the finalized decisions into the relationship-shaped plan
-                // ledger. The node-level R1 self-check and all downstream shells
-                // compile ONLY plan-typed-facts.jsonl; without this write the whole
-                // decision run fails "frontend plan ledger missing" at R1 on every
-                // attempt. Validation failures surface as invalid-output so the
-                // retry ladder restarts the session with the diagnostics.
-                try {
-                    const bridge = await bridgeFrontendPlanDecisionToRelationshipLedger({
-                        runDir: meta.runDir,
-                        nodeId: input.task.id,
-                        attemptId: `${meta.runId}:${input.task.id}`,
-                        facts: decisionPlanTools.committedFacts(),
-                        authority: decisionPlanAuthority,
-                        skeleton: input.task.structuredContractOutput?.skeleton,
-                        sourceBinding: meta.spec.sourceBinding,
-                    });
-                    if (!bridge.ok) {
-                        throw new Error(bridge.error);
+            else {
+                const finalizeResult = await observeFrontendFinalization({
+                    artifactPath: path.join(meta.runDir, input.task.id, "session-budget", `attempt-${input.attempt ?? 1}-runtime-finalize.json`),
+                    runId: meta.runId, nodeId: input.task.id, taskId: meta.spec?.sourceBinding?.taskId, attempt: input.attempt ?? 1,
+                }, () => decisionPlanTools.finalizeDecision());
+                const finalizeDetails = finalizeResult && typeof finalizeResult === "object"
+                    ? (finalizeResult.details ?? finalizeResult)
+                    : finalizeResult;
+                if (finalizeDetails && typeof finalizeDetails === "object" && finalizeDetails.ok === true) {
+                    // Bridge the finalized decisions into the relationship-shaped plan
+                    // ledger. The node-level R1 self-check and all downstream shells
+                    // compile ONLY plan-typed-facts.jsonl; without this write the whole
+                    // decision run fails "frontend plan ledger missing" at R1 on every
+                    // attempt. Validation failures surface as invalid-output so the
+                    // retry ladder restarts the session with the diagnostics.
+                    try {
+                        const bridge = await bridgeFrontendPlanDecisionToRelationshipLedger({
+                            runDir: meta.runDir,
+                            nodeId: input.task.id,
+                            attemptId: `${meta.runId}:${input.task.id}`,
+                            facts: decisionPlanTools.committedFacts(),
+                            authority: decisionPlanAuthority,
+                            skeleton: input.task.structuredContractOutput?.skeleton,
+                            sourceBinding: meta.spec.sourceBinding,
+                        });
+                        if (!bridge.ok) {
+                            throw new Error(bridge.error);
+                        }
+                        result = decisionResult;
+                    }
+                    catch (error) {
+                        result = {
+                            ok: false,
+                            stdout: decisionResult.stdout ?? "",
+                            stderr: `${decisionResult.stderr ?? ""}\n${error instanceof Error ? error.message : String(error)}`.trim(),
+                            failureCategory: "invalid-output",
+                            durationMs: Date.now() - started,
+                            modelDisplay: decisionResult.modelDisplay,
+                            parsedEvents: decisionResult.parsedEvents,
+                            timedOut: decisionResult.timedOut,
+                            attemptedModels: decisionResult.attemptedModels,
+                            fallbackUsed: decisionResult.fallbackUsed,
+                            tokensUsed: decisionResult.tokensUsed,
+                            assistantText: decisionResult.assistantText ?? "",
+                            command: decisionResult.command ?? [],
+                            exitCode: decisionResult.exitCode,
+                        };
                     }
-                    result = decisionResult;
                 }
-                catch (error) {
+                else {
                     result = {
                         ok: false,
                         stdout: decisionResult.stdout ?? "",
-                        stderr: `${decisionResult.stderr ?? ""}\n${error instanceof Error ? error.message : String(error)}`.trim(),
+                        stderr: `${decisionResult.stderr ?? ""}\nfrontend decision finalize failed: ${String(finalizeDetails?.error ?? "decision finalize rejected")}`.trim(),
                         failureCategory: "invalid-output",
                         durationMs: Date.now() - started,
                         modelDisplay: decisionResult.modelDisplay,
@@ -7466,24 +7566,6 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     };
                 }
             }
-            else {
-                result = {
-                    ok: false,
-                    stdout: decisionResult.stdout ?? "",
-                    stderr: `${decisionResult.stderr ?? ""}\nfrontend decision finalize failed: ${String(finalizeDetails?.error ?? "decision finalize rejected")}`.trim(),
-                    failureCategory: "invalid-output",
-                    durationMs: Date.now() - started,
-                    modelDisplay: decisionResult.modelDisplay,
-                    parsedEvents: decisionResult.parsedEvents,
-                    timedOut: decisionResult.timedOut,
-                    attemptedModels: decisionResult.attemptedModels,
-                    fallbackUsed: decisionResult.fallbackUsed,
-                    tokensUsed: decisionResult.tokensUsed,
-                    assistantText: decisionResult.assistantText ?? "",
-                    command: decisionResult.command ?? [],
-                    exitCode: decisionResult.exitCode,
-                };
-            }
         }
         else if (isFrontendPlanLedgerNode(input.task) && planLedgerTools) {
             // Frontend-only split: independent coverage map sessions feed a single
@@ -7496,14 +7578,12 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             try {
                 const { readCommittedOriginFacts } = await import("../workflows/dag/frontend-committed-facts.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 = collectFrontendPlanRequirementIds(contractFacts);
-                for (const fact of resolveFrontendContractRequirements(contractFacts.map((record) => record.fact))) {
+                // Read current requirements, not append-only revisions introduced when
+                // Contract attaches execution metadata. Coverage and costs must share
+                // the same identity projection as the rendered Plan input.
+                const requirements = resolveFrontendContractRequirements(contractFacts.map(record => record.fact));
+                planRequirementIds = requirements.map(fact => fact.id);
+                for (const fact of requirements) {
                     if (fact.evidence.behavior === "required")
                         behaviorRequiredRequirementIds.push(fact.id);
                     planRequirementCosts.set(fact.id, estimateFrontendPlanRequirementRecordCalls(fact));
@@ -7529,7 +7609,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     contractDigest: meta.spec?.taskContractBinding?.canonicalHash,
                 },
                 piStepFn,
-                sessionOptions: options.sessionOptions,
+                sessionOptions: { ...options.sessionOptions, frontendPlanControl: options.ledgerTools.planControl },
                 basePrompt: options.basePrompt ?? input.prompt,
                 attempt: input.attempt ?? 1,
                 committedFactCount: () => options.ledgerTools.committedFactCount(),

package/dist/executors/pi-executor.js

@@ -790,7 +790,7 @@ export async function executePiStep(options) {
             reuseRuntimeActive,
         });
     }
-    if (options.reserveProviderRequest || !shouldFallbackSdkToCli(sdkResult, validationIssues, options)) {
+    if (options.frontendPlanControl || options.reserveProviderRequest || !shouldFallbackSdkToCli(sdkResult, validationIssues, options)) {
         const failureCategory = validationIssues.length > 0
             ? "invalid-output"
             : sdkResult.failureCategory;
@@ -1104,6 +1104,11 @@ export function classifyPiFailure(input) {
     // Provider/transport verdicts read error-shaped channels only; the raw stdout
     // stream embeds assistant text, tool arguments and findings verbatim.
     const combined = `${input.stderr}\n${extractProviderFailureText(input.stdout)}`.toLowerCase();
+    // An explicit spend-budget stop is terminal even if a transport wrapper also
+    // reports a closed connection. Read only the error channels above, never
+    // assistant/tool prose; generic quota and context limits keep their categories.
+    if (/(?<![\w-])(?:frontend_provider_budget_exhausted|budget_exhausted|budget_breach|budget exhausted)(?![\w-])/.test(combined))
+        return "budget_breach";
     // Context overflow (400 request-too-large / context window exceeded).
     // Must be detected BEFORE the generic rate-limit/quota phrases: an overflow
     // error often contains "too many tokens" / "maximum context" which would