@tea-agent/loop-agent 0.43.0-next.4 → 0.43.0-next.6

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

@@ -1,3 +1,6 @@
+import { collectFrontendPlanMissingFacts, collectFrontendPlanPhaseMissingFacts, committedFactFromPlanRecord, planFactStringList, planFactScopeIntersects } from "../workflows/dag/frontend-plan-completeness.js";
+export { collectFrontendPlanMissingFacts, collectFrontendPlanPhaseMissingFacts } from "../workflows/dag/frontend-plan-completeness.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";
 import { createDurableFrontendTools } from "../workflows/dag/frontend-durable-tools.js";
@@ -592,6 +595,7 @@ export function resolveDagPiToolNames(task) {
             ...FRONTEND_PLAN_RECORD_TOOL_NAMES,
             ...FRONTEND_PLAN_TERMINAL_TOOL_NAMES,
             ...FRONTEND_PLAN_ADOPT_TOOL_NAMES,
+            "read_plan_facts",
         ];
     }
     if ((task.readSet?.length ?? 0) > 0) {
@@ -1811,6 +1815,44 @@ export async function createFrontendPlanLedgerTools(input) {
                     });
                 }
             }
+            // Named entries are last-wins at assembly. A scoped correction may
+            // replace its own bindings, but must retain other scopes' coverage.
+            const scope = new Set(scopedRequirementIds());
+            const committed = readCommittedEvents(store, attemptId).map(event => event.fact);
+            const targetOwners = new Map();
+            for (const fact of committed) {
+                if (fact.kind === "plan-verification-target" && isRecordObject(fact.entry) && typeof fact.entry.id === "string") {
+                    targetOwners.set(fact.entry.id, stringList(fact.entry.requirementIds));
+                }
+            }
+            for (const [field, removals] of [["uiStates", removeUiStateNames], ["interactions", removeInteractionNames]]) {
+                const live = new Map();
+                for (const fact of committed) {
+                    if (fact.kind !== "state-flow")
+                        continue;
+                    for (const name of stringList(fact[field === "uiStates" ? "removeUiStateNames" : "removeInteractionNames"]))
+                        live.delete(name);
+                    for (const entry of Array.isArray(fact[field]) ? fact[field] : []) {
+                        if (isRecordObject(entry) && typeof entry.name === "string")
+                            live.set(entry.name, entry);
+                    }
+                }
+                const foreignBindings = (entry) => scope.size === 0 ? [] : stringList(entry.verificationTargetIds).filter(id => {
+                    const owners = targetOwners.get(id);
+                    return !owners?.length || owners.some(owner => !scope.has(owner));
+                });
+                for (const name of removals) {
+                    const previous = live.get(name);
+                    if (previous && foreignBindings(previous).length)
+                        return planToolReceipt({ ok: false, kind: "state-flow",
+                            error: `Cannot remove shared ${name} from this requirement scope; retain it and update its scoped bindings instead` });
+                }
+                for (const entry of field === "uiStates" ? uiStates : interactions) {
+                    const previous = live.get(String(entry.name));
+                    if (previous)
+                        entry.verificationTargetIds = [...new Set([...foreignBindings(previous), ...stringList(entry.verificationTargetIds)])];
+                }
+            }
             const result = await adoptPlanFact("state-flow", `${attemptId}:record_state_flow:${randomUUID()}`, {
                 kind: "state-flow",
                 origin: "plan",
@@ -2415,6 +2457,74 @@ export async function createFrontendPlanLedgerTools(input) {
             }
         },
     });
+    const readPlanFactsTool = defineTool({
+        name: "read_plan_facts",
+        label: "read_plan_facts",
+        description: "Read the LIVE committed plan ledger without repository access. Filter by kind and optional entryId or eventId. Use field (dot path, e.g. entry.requirementIds or uiStates) to page large arrays/strings. offset/limit paginate results; follow nextOffset until null before replacing any full-array fact. expectedRevision pins all pages to one ledger revision; restart if it changes. No writes.",
+        parameters: Type.Object({
+            kind: Type.String(), entryId: Type.Optional(Type.String()), eventId: Type.Optional(Type.String()),
+            field: Type.Optional(Type.String()), offset: Type.Optional(Type.Integer({ minimum: 0 })),
+            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+            stringOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+            expectedRevision: Type.Optional(Type.Integer({ minimum: 0 })),
+        }, { additionalProperties: false }),
+        async execute(_id, params) {
+            const reply = (details) => ({ content: [{ type: "text", text: JSON.stringify(details) }], details });
+            if (params.expectedRevision !== undefined && params.expectedRevision !== store.revision) {
+                return reply({ ok: false, revision: store.revision, error: "ledger revision changed; restart pagination" });
+            }
+            let records = readCommittedEvents(store, attemptId).filter(record => {
+                const fact = record.fact;
+                return fact.kind === params.kind && (!params.eventId || record.eventId === params.eventId) &&
+                    (!params.entryId || fact.entry?.id === params.entryId);
+            });
+            // Full-entry corrections and registries are last-wins. Other kinds
+            // remain an ordered event log (state removals must remain visible).
+            if (params.entryId || params.kind === "state-registry")
+                records = records.slice(-1);
+            let values = records.map(record => ({ eventId: record.eventId, ...record.fact }));
+            if (params.field) {
+                values = records.flatMap(record => {
+                    let value = record.fact;
+                    for (const key of params.field.split(".")) {
+                        if (!value || typeof value !== "object" || !Object.hasOwn(value, key))
+                            return [];
+                        value = value[key];
+                    }
+                    return Array.isArray(value) ? value : [value];
+                });
+            }
+            const offset = params.offset ?? 0;
+            if (params.stringOffset !== undefined) {
+                const value = values[offset];
+                if (typeof value !== "string")
+                    return reply({ ok: false, error: "stringOffset requires a string field item" });
+                // Unicode code points prevent a page boundary splitting a surrogate pair.
+                const characters = Array.from(value);
+                const chunk = characters.slice(params.stringOffset, params.stringOffset + 1000).join("");
+                const next = params.stringOffset + Array.from(chunk).length;
+                return reply({ ok: true, revision: store.revision, offset, stringOffset: params.stringOffset,
+                    chunk, totalCharacters: characters.length, nextStringOffset: next < characters.length ? next : null });
+            }
+            const items = [];
+            let bytes = 0;
+            for (const value of values.slice(offset, offset + (params.limit ?? 10))) {
+                const size = Buffer.byteLength(JSON.stringify(value));
+                if (bytes + size > 12_000)
+                    break;
+                bytes += size;
+                items.push(value);
+            }
+            if (!items.length && offset < values.length)
+                return reply({
+                    ok: false, revision: store.revision, total: values.length, offset,
+                    error: "item exceeds the page budget; select an eventId/entryId and a narrower field path; for a string item set stringOffset: 0 and follow nextStringOffset",
+                    fields: typeof values[offset] === "object" && values[offset] !== null ? Object.keys(values[offset]) : [],
+                });
+            return reply({ ok: true, revision: store.revision, total: values.length, offset, items,
+                nextOffset: offset + items.length < values.length ? offset + items.length : null });
+        },
+    });
     const durable = await createDurableFrontendTools({
         file: path.join(input.runDir, input.nodeId, "plan-typed-facts.jsonl"), attemptId, store: input.store,
         setWorkingStore: next => { store = next; },
@@ -2438,7 +2548,7 @@ export async function createFrontendPlanLedgerTools(input) {
         ],
     });
     return {
-        customTools: durable.customTools,
+        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) {
                 if (record.phase !== "committed")
@@ -3694,174 +3804,6 @@ const FRONTEND_PLAN_SEGMENTS = [
         ].join(" "),
     },
 ];
-function committedFactFromPlanRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const record = value;
-    if (record.phase !== undefined && record.phase !== "committed")
-        return undefined;
-    const fact = record.fact;
-    return fact && typeof fact === "object" && !Array.isArray(fact)
-        ? fact
-        : typeof record.kind === "string"
-            ? record
-            : undefined;
-}
-function planFactStringList(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
-}
-function planFactScopeIntersects(fact, requirementIds) {
-    return planFactStringList(fact.scopeRequirementIds).some((id) => requirementIds.has(id));
-}
-/** Compute the authoritative coverage queue from the committed plan ledger. */
-export function collectFrontendPlanMissingFacts(input) {
-    const requirements = new Map();
-    const standaloneEvidenceGaps = new Set();
-    const verificationTargetIds = new Set();
-    const verificationTargetRequirements = new Map();
-    for (const value of input.committedFacts) {
-        const fact = committedFactFromPlanRecord(value);
-        if (!fact || fact.origin !== "plan")
-            continue;
-        if (fact.kind === "plan-requirement" && fact.entry && typeof fact.entry === "object") {
-            const entry = fact.entry;
-            if (typeof entry.id === "string" && entry.id.trim())
-                requirements.set(entry.id, entry);
-        }
-        if (fact.kind === "plan-verification-target" && fact.entry && typeof fact.entry === "object") {
-            const entry = fact.entry;
-            const id = entry.id;
-            if (typeof id === "string" && id.trim()) {
-                verificationTargetIds.add(id);
-                verificationTargetRequirements.set(id, new Set(Array.isArray(entry.requirementIds)
-                    ? entry.requirementIds.filter((value) => typeof value === "string")
-                    : []));
-            }
-        }
-        if (fact.kind === "plan-evidence-gap" && fact.entry && typeof fact.entry === "object") {
-            const entry = fact.entry;
-            const requirementId = entry.requirementId;
-            const description = entry.description;
-            if (typeof requirementId === "string" && requirementId.trim() && typeof description === "string" && description.trim()) {
-                standaloneEvidenceGaps.add(requirementId);
-            }
-        }
-    }
-    const missing = [];
-    for (const id of input.requirementIds) {
-        const entry = requirements.get(id);
-        if (!entry) {
-            missing.push({
-                kind: "plan-requirement",
-                id,
-                requirementIds: [id],
-                reason: `requirement ${id} has no committed plan-requirement fact`,
-            });
-            continue;
-        }
-        const targetIds = Array.isArray(entry.verificationTargetIds)
-            ? entry.verificationTargetIds.filter((value) => typeof value === "string" && value.trim().length > 0)
-            : [];
-        const gap = entry.evidenceGap && typeof entry.evidenceGap === "object"
-            ? entry.evidenceGap
-            : undefined;
-        const hasEvidenceGap = (typeof gap?.description === "string" && gap.description.trim().length > 0) ||
-            standaloneEvidenceGaps.has(id);
-        if (targetIds.length === 0 && !hasEvidenceGap) {
-            missing.push({
-                kind: "plan-verification-target",
-                requirementIds: [id],
-                reason: `requirement ${id} declares neither a verification target nor a non-empty evidenceGap`,
-            });
-            continue;
-        }
-        for (const targetId of targetIds) {
-            if (!verificationTargetIds.has(targetId) ||
-                !verificationTargetRequirements.get(targetId)?.has(id)) {
-                missing.push({
-                    kind: "plan-verification-target",
-                    id: targetId,
-                    requirementIds: [id],
-                    reason: `requirement ${id} references verification target ${targetId}, but that target is not committed`,
-                });
-            }
-        }
-    }
-    return missing;
-}
-/** Completeness checks for phases whose facts are committed incrementally. */
-export function collectFrontendPlanPhaseMissingFacts(input) {
-    const facts = input.committedFacts
-        .map(committedFactFromPlanRecord)
-        .filter((fact) => Boolean(fact && fact.origin === "plan"));
-    if (input.phase === "ux-registry") {
-        return facts.some((fact) => fact.kind === "state-registry")
-            ? []
-            : [
-                {
-                    kind: "state-registry",
-                    requirementIds: [...input.requirementIds],
-                    reason: "global UX vocabulary phase has no committed state-registry fact",
-                },
-            ];
-    }
-    if (input.phase === "ux-local") {
-        const needsUx = input.requirementIds.some((id) => input.behaviorRequiredRequirementIds?.includes(id));
-        if (!needsUx)
-            return [];
-        const requirementSlice = new Set(input.requirementIds);
-        const scopedFacts = facts.filter((fact) => planFactScopeIntersects(fact, requirementSlice));
-        const hasChoice = scopedFacts.some((fact) => fact.kind === "component-choice" &&
-            Array.isArray(fact.uiComponentChoices) &&
-            fact.uiComponentChoices.length > 0);
-        const canonicalStateFlow = collectCanonicalStateFlowNames(scopedFacts);
-        const hasStateFlow = canonicalStateFlow.uiStateNames.size > 0 ||
-            canonicalStateFlow.interactionNames.size > 0;
-        const missing = [];
-        if (!hasChoice) {
-            missing.push({
-                kind: "component-choice",
-                requirementIds: [...input.requirementIds],
-                reason: "behaviour-required UX slice has no committed component-choice fact",
-            });
-        }
-        if (!hasStateFlow) {
-            missing.push({
-                kind: "state-flow",
-                requirementIds: [...input.requirementIds],
-                reason: "behaviour-required UX slice has no committed state-flow fact",
-            });
-        }
-        return missing;
-    }
-    const hasMockApi = facts.some((fact) => fact.kind === "mock-api");
-    const allInteractions = collectCanonicalStateFlowNames(input.committedFacts).interactionNames;
-    const liveInteractions = new Set([...collectCanonicalStateFlowNames(facts.filter(f => !planFactStringList(f.scopeRequirementIds).length || planFactScopeIntersects(f, new Set(input.requirementIds)))).interactionNames].filter(name => allInteractions.has(name)));
-    const coveredInteractions = new Set(facts
-        .filter((fact) => fact.kind === "data-flow")
-        .flatMap((fact) => planFactStringList(fact.interactions)));
-    const missing = [];
-    if (!hasMockApi) {
-        missing.push({
-            kind: "mock-api",
-            requirementIds: [...input.requirementIds],
-            reason: "global Mock/data phase has no committed mock-api fact",
-        });
-    }
-    for (const interaction of liveInteractions) {
-        if (coveredInteractions.has(interaction))
-            continue;
-        missing.push({
-            kind: "data-flow",
-            id: interaction,
-            requirementIds: [...input.requirementIds],
-            reason: `interaction ${interaction} has no committed data-flow fact`,
-        });
-    }
-    return missing;
-}
 /** Estimate calls conservatively: requirement + one VT, with a second VT
  * reserved for behaviour-required requirements. Explicit declarations win. */
 export function estimateFrontendPlanRequirementRecordCalls(fact) {
@@ -3903,9 +3845,8 @@ export function batchFrontendPlanRequirements(input) {
 }
 const FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS = 10;
 const FRONTEND_PLAN_COVERAGE_MAX_CONCURRENCY = 4;
-// A large requirement set creates parallel coverage shards; UX remains one
-// global decision session so behavior names and component/state facts are not
-// reinvented per AC batch. Keep a safety bound for adaptive coverage retries
+// A single registry owns global names; large UX work uses bounded serial
+// scopes against that registry. Keep a safety bound for adaptive retries
 // without letting the old 32-session ceiling skip finalize.
 const FRONTEND_PLAN_BATCH_MAX_SESSIONS = 128;
 const FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS = 8;
@@ -4046,26 +3987,28 @@ export function compactFrontendPlanPromptForRequirementSlice(basePrompt, require
                 if (!value || typeof value !== "object" || Array.isArray(value))
                     return [];
                 const target = value;
-                const targetRequirementIds = compactPromptStringArray(target.requirementIds, 20, 80);
+                if (options.verificationTargetIds && !options.verificationTargetIds.includes(String(target.id)))
+                    return [];
+                const targetRequirementIds = planFactStringList(target.requirementIds);
                 const relatedRequirementIds = targetRequirementIds.filter((id) => sliceSet.has(id));
                 if (relatedRequirementIds.length === 0)
                     return [];
                 return [
                     {
-                        ...(compactPromptString(target.id, 80)
-                            ? { id: compactPromptString(target.id, 80) }
+                        ...(typeof target.id === "string"
+                            ? { id: target.id }
                             : {}),
-                        ...(compactPromptString(target.commandId, 80)
-                            ? { commandId: compactPromptString(target.commandId, 80) }
+                        ...(typeof target.commandId === "string"
+                            ? { commandId: target.commandId }
                             : {}),
                         ...(compactPromptString(target.commandLabel, 180)
                             ? { commandLabel: compactPromptString(target.commandLabel, 180) }
                             : {}),
-                        ...(compactPromptString(target.file, 180)
-                            ? { file: compactPromptString(target.file, 180) }
+                        ...(typeof target.file === "string"
+                            ? { file: target.file }
                             : {}),
                         requirementIds: relatedRequirementIds,
-                        uiStates: compactPromptStringArray(target.uiStates, 12, 100),
+                        uiStates: planFactStringList(target.uiStates),
                     },
                 ];
             })
@@ -4117,7 +4060,7 @@ export function compactFrontendPlanPromptForRequirementSlice(basePrompt, require
             if (!value || typeof value !== "object" || Array.isArray(value))
                 return [];
             const state = value;
-            const id = compactPromptString(state.id, 80);
+            const id = typeof state.id === "string" ? state.id : undefined;
             if (!id)
                 return [];
             return [{
@@ -4217,9 +4160,9 @@ function compactFrontendPlanLedgerContext(input) {
             compactFacts.push({
                 kind: fact.kind,
                 entry: {
-                    id: compactPromptString(entry.id, 80),
-                    implementationTargets: compactPromptStringArray(entry.implementationTargets, 12, 180),
-                    verificationTargetIds: compactPromptStringArray(entry.verificationTargetIds, 12, 80),
+                    id: entry.id,
+                    implementationTargets: planFactStringList(entry.implementationTargets).slice(0, 12),
+                    verificationTargetIds: planFactStringList(entry.verificationTargetIds).slice(0, 12),
                     ...(compactPromptString(entry.expectedOutcome, 240)
                         ? { expectedOutcome: compactPromptString(entry.expectedOutcome, 240) }
                         : {}),
@@ -4233,17 +4176,19 @@ function compactFrontendPlanLedgerContext(input) {
         if (fact.kind === "plan-verification-target") {
             if (!entry)
                 continue;
-            const requirementIds = compactPromptStringArray(entry.requirementIds, 20, 80);
-            if (!requirementIds.some((id) => slice.has(id)))
+            // Scope against the complete canonical binding before compacting.
+            // A shared target may bind a late requirement beyond the preview cap.
+            const requirementIds = planFactStringList(entry.requirementIds).filter((id) => slice.has(id));
+            if (requirementIds.length === 0)
                 continue;
             compactFacts.push({
                 kind: fact.kind,
                 entry: {
-                    id: compactPromptString(entry.id, 80),
-                    commandId: compactPromptString(entry.commandId, 80),
-                    file: compactPromptString(entry.file, 180),
+                    id: entry.id,
+                    commandId: entry.commandId,
+                    file: entry.file,
                     requirementIds,
-                    uiStates: compactPromptStringArray(entry.uiStates, 12, 100),
+                    uiStates: planFactStringList(entry.uiStates).slice(0, 12),
                 },
             });
             continue;
@@ -4270,8 +4215,8 @@ function compactFrontendPlanLedgerContext(input) {
         if (fact.kind === "state-registry") {
             compactFacts.push({
                 kind: fact.kind,
-                uiStateNames: compactPromptStringArray(fact.uiStateNames, 40, 100),
-                interactionNames: compactPromptStringArray(fact.interactionNames, 60, 120),
+                uiStateNames: planFactStringList(fact.uiStateNames).slice(0, 40),
+                interactionNames: planFactStringList(fact.interactionNames).slice(0, 60),
             });
             continue;
         }
@@ -4323,13 +4268,21 @@ function compactFrontendPlanLedgerContext(input) {
         return "";
     const priorityFacts = compactFacts.filter((fact) => fact.kind === "plan-requirement" || fact.kind === "plan-verification-target");
     const otherFacts = compactFacts.filter((fact) => fact.kind !== "plan-requirement" && fact.kind !== "plan-verification-target");
+    let previewBytes = 0;
     const boundedFacts = [
-        ...priorityFacts,
-        ...otherFacts,
-    ];
+        ...priorityFacts.slice(0, 64),
+        ...otherFacts.slice(-32),
+    ].slice(0, 96).filter(fact => {
+        const bytes = Buffer.byteLength(JSON.stringify(fact));
+        if (previewBytes + bytes > 24_000)
+            return false;
+        previewBytes += bytes;
+        return true;
+    });
     return [
         "<frontend_plan_ledger>",
-        "Committed plan facts from earlier sessions. Treat these as authoritative; correct them only with the allowed replacement/removal fields.",
+        "Preview of committed plan facts; not a replacement payload. Fields and lists may be omitted or shortened. Use read_plan_facts with kind, entryId/eventId and optional field to retrieve complete values in bounded pages before corrections; preserve all other bindings. Absence from this preview is not absence from the ledger.",
+        JSON.stringify({ complete: false, matchingFacts: compactFacts.length, omittedFacts: compactFacts.length - boundedFacts.length }),
         JSON.stringify(boundedFacts),
         "</frontend_plan_ledger>",
     ].join("\n");
@@ -4707,7 +4660,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
                     "component-choice",
                     "state-flow",
                 ],
-                scopedKinds: ["state-flow"],
+                // Include shared state bindings from other scopes; page full values before correcting.
             })
             : "";
         return [
@@ -4926,6 +4879,27 @@ export async function runFrontendPlanSegmentedSessions(input) {
     let lastDurableCount = input.committedFactCount();
     while (index < queue.length) {
         const session = queue[index];
+        if (input.attempt > 1 && input.committedFacts && session.id === "ux-registry" &&
+            collectFrontendPlanPhaseMissingFacts({ phase: "ux-registry", requirementIds: allRequirementIds, committedFacts: input.committedFacts() }).length === 0) {
+            index += 1;
+            continue;
+        }
+        // Reuse complete UX scopes on node retry. Require explicit per-requirement
+        // ownership; an unrelated/global fact must not prove a slice complete.
+        if (input.attempt > 1 && input.committedFacts && session.id.startsWith("ux-local-") && session.requirementSlice?.length) {
+            const facts = input.committedFacts();
+            const ownedIds = new Set(facts.flatMap(value => {
+                const fact = committedFactFromPlanRecord(value);
+                return fact ? planFactStringList(fact.scopeRequirementIds) : [];
+            }));
+            const complete = session.requirementSlice.every(id => ownedIds.has(id)) &&
+                collectFrontendPlanPhaseMissingFacts({ phase: "ux-local", requirementIds: session.requirementSlice,
+                    committedFacts: facts, behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds }).length === 0;
+            if (complete) {
+                index += 1;
+                continue;
+            }
+        }
         const remaining = (session.coverageOnly ? session.coverageSlice ?? [] : []).filter((id) => !input.committedRequirementIds?.().has(id));
         const preexistingMissing = session.coverageOnly && session.coverageSlice && input.committedFacts
             ? collectFrontendPlanMissingFacts({
@@ -4971,12 +4945,30 @@ export async function runFrontendPlanSegmentedSessions(input) {
                         : buildPhasePrompt(segment, session.missingFacts, session.requirementSlice ?? allRequirementIds);
             }
         }
+        const atomicFocus = session.atomicRecovery ? session.missingFacts?.[0] : undefined;
+        if (atomicFocus) {
+            prompt = [
+                compactFrontendPlanPromptForRequirementSlice(input.basePrompt, atomicFocus.requirementIds, {
+                    includeChecklist: false,
+                    ...(atomicFocus.kind === "plan-verification-target" && atomicFocus.id
+                        ? { verificationTargetIds: [atomicFocus.id] } : {}),
+                }),
+                `ATOMIC FACT: ${atomicFocus.kind}${atomicFocus.id ? ` ${atomicFocus.id}` : ""}`,
+                atomicFocus.reason,
+                "Commit ONLY this missing fact with one record_* call, then end this session. Other facts are queued separately. Preserve canonical IDs and shared bindings; use read_plan_facts for existing values. Do not summarize or plan the entire requirement. Capacity exhaustion is not evidence of a requirement gap.",
+            ].join("\n\n");
+        }
         const committedBefore = input.committedFactCount();
         input.setActiveRequirementScope?.(session.coverageOnly ? session.coverageSlice ?? [] : session.requirementSlice ?? []);
         if (invocationCount >= FRONTEND_PLAN_BATCH_MAX_SESSIONS)
             break;
         invocationCount += 1;
-        const customTools = input.segmentCustomTools(session.toolNames);
+        const atomicTools = {
+            "plan-requirement": "record_plan_requirement", "plan-verification-target": "record_plan_verification_target",
+            "state-registry": "record_state_registry", "component-choice": "record_component_choice",
+            "state-flow": "record_state_flow", "data-flow": "record_data_flow", "mock-api": "record_mock_api",
+        };
+        const customTools = input.segmentCustomTools(atomicFocus ? new Set([atomicTools[atomicFocus.kind]]) : session.toolNames);
         const scopeForPacking = session.coverageSlice ?? session.requirementSlice;
         const envelopeBytes = Buffer.byteLength(prompt) + Buffer.byteLength(input.sessionOptions.userMessage ?? "") + Buffer.byteLength(JSON.stringify(customTools));
         if (envelopeBytes > (input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES) && scopeForPacking && session.id !== "compact-local") {
@@ -5105,9 +5097,47 @@ export async function runFrontendPlanSegmentedSessions(input) {
                         : isUxLocalSession
                             ? buildUxPrompt(session.requirementSlice ?? [], missing)
                             : buildPhasePrompt(globalMockDataSegment, missing, session.requirementSlice ?? allRequirementIds);
-        if (result.timedOut || /interrupt|termination-unconfirmed|budget_breach/.test(result.failureCategory))
+        const recovery = classifyFrontendPlanRecovery({ ...result, stopReason: readWriterThinkingExhaustionEvidence(result).stopReason });
+        if (recovery === "stop")
             return { ...result, ok: false };
-        const capacityExhausted = readWriterThinkingExhaustionEvidence(result).stopReason === "length" || ["context-overflow", "context-budget-exhausted"].includes(result.failureCategory);
+        if ((recovery === "output" || (session.atomicRecovery && result.ok)) && input.committedFacts &&
+            !(missingPhaseFacts.length === 1 && missingPhaseFacts[0].kind === "plan-requirement") &&
+            (session.coverageOnly || isUxRegistrySession || isUxLocalSession || session.id.startsWith("global-mock-data"))) {
+            if (missingPhaseFacts.length === 0) {
+                // A complete validated slice does not need a successful prose turn.
+                // This never accepts finalize or bypasses the final contract validator.
+                accumulated = { ...accumulated, ok: true, failureCategory: "success" };
+                index += 1;
+                continue;
+            }
+            const missingIds = [...new Set(missingPhaseFacts.flatMap(item => item.requirementIds))];
+            const scope = session.coverageSlice ?? session.requirementSlice;
+            if (scope && missingIds.length < scope.length) {
+                queue[index] = { ...session, missingFacts: missingPhaseFacts,
+                    ...(session.coverageOnly ? { coverageSlice: missingIds } : { requirementSlice: missingIds }),
+                    retryCount: 0 };
+                continue;
+            }
+            if (scope && missingIds.length > 1 && (session.coverageOnly || isUxLocalSession)) {
+                const half = Math.ceil(missingIds.length / 2);
+                queue.splice(index, 1, ...[missingIds.slice(0, half), missingIds.slice(half)].map(ids => ({
+                    ...session, retryCount: 0,
+                    ...(session.coverageOnly ? { coverageSlice: ids } : { requirementSlice: ids }),
+                    missingFacts: missingPhaseFacts.filter(item => item.requirementIds.some(id => ids.includes(id))),
+                })));
+                continue;
+            }
+            const focusStillMissing = atomicFocus && missingPhaseFacts.some(item => item.kind === atomicFocus.kind && item.id === atomicFocus.id &&
+                item.requirementIds.join("\0") === atomicFocus.requirementIds.join("\0"));
+            const retries = focusStillMissing ? (session.retryCount ?? 0) + 1 : 0;
+            if (retries < 2) {
+                queue[index] = { ...session, atomicRecovery: true, missingFacts: missingPhaseFacts, retryCount: retries };
+                continue;
+            }
+            return { ...accumulated, ok: false, failureCategory: OUTPUT_LIMIT_RETRY_CATEGORY,
+                stderr: `${accumulated.stderr}\nfrontend plan capacity recovery exhausted: preserve committed facts; phase=${session.id}; scope=${missingIds.join(",")}; strategy=atomic-fact; missing=${JSON.stringify(missingPhaseFacts)}`.trim() };
+        }
+        const capacityExhausted = recovery === "output" || recovery === "context";
         if (capacityExhausted && !result.timedOut) {
             const failure = () => mapPlannerExhaustion({ ...result, ok: false, stderr: `${result.stderr}\nFRONTEND_INPUT_UNIT_TOO_LARGE: ${session.id}; no smaller complete scope can finish; unchanged retries are disabled` }, committedAfter > committedBefore);
             const missingCoverageIds = input.committedFacts ? [...new Set(collectFrontendPlanMissingFacts({ requirementIds: session.coverageSlice ?? session.requirementSlice ?? allRequirementIds, committedFacts: input.committedFacts() }).flatMap(f => f.requirementIds))] : [...(session.coverageSlice ?? session.requirementSlice ?? allRequirementIds)];
@@ -5213,7 +5243,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 : undefined;
         const zeroProgressBurn = coverageSlice !== undefined &&
             coverageSlice.length > 1 &&
-            (readWriterThinkingExhaustionEvidence(result).stopReason === "length" || ["context-overflow", "context-budget-exhausted"].includes(result.failureCategory) || (committedAfter === committedBefore && !(result.assistantText ?? "").trim() && !result.stderr.trim())) &&
+            (capacityExhausted || (["empty-output", "unknown"].includes(result.failureCategory) && committedAfter === committedBefore && !(result.assistantText ?? "").trim() && !result.stderr.trim())) &&
             !result.timedOut;
         if (zeroProgressBurn && coverageSlice) {
             const missingIds = input.committedFacts ? new Set(collectFrontendPlanMissingFacts({ requirementIds: coverageSlice, committedFacts: input.committedFacts() }).flatMap(f => f.requirementIds)) : undefined;
@@ -5933,6 +5963,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             frontendExecutionPolicy: meta.spec?.frontendExecutionPolicy,
             attachedFiles: [],
             modelConfig,
+            outputLimitRecovery: { terminalToolNames: ["finalize_plan", "finalize_contract", "approve_design", "request_design_changes", "approve_review", "request_review_changes"] },
             repoRoot: input.cwd,
             step,
             toolNames,
@@ -6051,7 +6082,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     ? options.ledgerTools.customTools
                     : options.ledgerTools.customTools.filter((tool) => typeof tool === "object" &&
                         tool !== null &&
-                        toolNames.has(tool.name)),
+                        (toolNames.has(tool.name) || tool.name === "read_plan_facts")),
                 flushLedger: () => options.ledgerTools.flush(),
             });
             if (planRequirementIds.length > 1) {

package/dist/executors/pi-executor.js

@@ -707,6 +707,8 @@ function shouldFallbackSdkToCli(sdkResult, validationIssues, options) {
         return true;
     if (!sdkResult.ok &&
         (sdkResult.failureCategory === "auth" ||
+            sdkResult.failureCategory === "output-limit" ||
+            sdkResult.failureCategory === "cancelled" ||
             sdkResult.failureCategory === "timeout" ||
             sdkResult.failureCategory === "termination-unconfirmed")) {
         return false;