@tea-agent/loop-agent 0.44.0-next.10 → 0.44.0-next.11

package/dist/executors/dag-pi/sessions/segmented-plan.js

@@ -0,0 +1,1184 @@
+/** DAG Pi plan 分段会话执行器：顺序执行、预算与缺失事实修复次序、terminal 行为。副作用集中于此。 */
+import { classifyFrontendPlanRecovery } from "../../../workflows/dag/frontend-plan-recovery-policy.js";
+import { collectFrontendExecutionGroups } from "../../../workflows/dag/frontend-execution-groups.js";
+import { FRONTEND_SCOPE_TARGET_BYTES, packFrontendInputUnits, parseFrontendInputBlock, projectFrontendContractPrompt, projectFrontendInputScope } from "../../../workflows/dag/frontend-input-projection.js";
+import { observeFrontendFinalization, observeFrontendSession } from "../../../workflows/dag/frontend-session-budget.js";
+import { collectFrontendPlanMissingFacts, collectFrontendPlanPhaseMissingFacts, committedFactFromPlanRecord, planFactStringList } from "../plan/facts.js";
+import { OUTPUT_LIMIT_RETRY_CATEGORY } from "../../../workflows/dag/retry-policy.js";
+import { FRONTEND_PLAN_BATCH_MAX_SESSIONS, FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS, FRONTEND_PLAN_SEGMENTS, buildFrontendPlanWorkload, collectFrontendVerificationCommandFiles } from "./plan-batches.js";
+import { compactFrontendPlanLedgerContext, compactFrontendPlanPromptForRequirementSlice } from "./plan-prompts.js";
+import { isPlannerThinkingExhausted, readWriterThinkingExhaustionEvidence } from "./writer-evidence.js";
+import { combineSequentialPiResults } from "./scout-parallel.js";
+export async function runFrontendReviewSegmentedSessions(input) {
+    const protocol = input.tools.scopeProtocol;
+    const terminalKinds = input.phase === "review" ? ["approve_review", "request_review_changes"] : ["approve_design", "request_design_changes"];
+    const terminal = () => protocol.committedFacts().some(r => terminalKinds.includes(String(r.fact.kind)));
+    const targetBytes = input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES;
+    const queue = packFrontendInputUnits(input.inventory.scopes.filter(s => !protocol.completedScopeIds().has(s.id)), { targetBytes, maxUnits: input.sessionOptions.frontendExecutionPolicy?.maxScopeUnits }).map(scopes => ({ scopes, repairs: 0 }));
+    if (!queue.length)
+        queue.push({ scopes: [], repairs: 0 });
+    let calls = 0;
+    let last = { ok: true, assistantText: "", command: [], durationMs: 0, exitCode: 0, failureCategory: "success", modelDisplay: "unknown", parsedEvents: 0, stderr: "", stdout: "", timedOut: false, attemptedModels: [], fallbackUsed: false, tokensUsed: 0 };
+    for (let index = 0; index < queue.length; index++) {
+        await input.tools.flush();
+        await input.inventory.validate();
+        if (terminal()) {
+            protocol.assertComplete();
+            return last;
+        }
+        const item = queue[index];
+        const scopes = item.scopes.filter(s => !protocol.completedScopeIds().has(s.id));
+        protocol.setActiveScope(scopes.map(s => s.id));
+        const finalScope = input.inventory.scopes.every(s => protocol.completedScopeIds().has(s.id) || scopes.some(current => current.id === s.id));
+        const customTools = finalScope ? input.customTools : input.customTools.filter(t => !terminalKinds.includes(String(t.name)));
+        const prompt = `${input.basePrompt}\n<frontend_review_authority>\nThe Contract acceptance criteria, constraints, required deliverables, UI-state declarations, and verification expectations in the supplied input are authoritative. Review the actual diff and evidence against those facts; do not replace them with a Plan-derived interpretation.\n</frontend_review_authority>\n<frontend_review_scope>\n${JSON.stringify({ semantics: "full", inventoryDigest: input.inventory.digest, scopes, previouslyCompleted: [...protocol.completedScopeIds()], savedFindings: protocol.committedFacts().filter(r => String(r.fact.kind).endsWith("-finding")).map(r => ({ id: r.fact.id, finding: r.fact.finding })) })}\n</frontend_review_scope>\nReview the complete supplied scopes, saving each finding immediately. Call complete_review_scope for each exact id only after all its independent permissions, thresholds, errors and evidence have been checked. ${finalScope ? "After every scope is complete, make one independent overall approve/request_changes decision; persisted findings cannot be omitted." : "More scopes remain. Do not finalize or reread already completed scopes unless resolving a cross-scope issue."}`;
+        if (Buffer.byteLength(prompt) > targetBytes && scopes.length > 1) {
+            const at = Math.ceil(scopes.length / 2);
+            queue.splice(index, 1, { scopes: scopes.slice(0, at), repairs: 0 }, { scopes: scopes.slice(at), repairs: 0 });
+            index--;
+            continue;
+        }
+        const completionInstruction = `${item.repairs ? "REPAIR: the prior session did not commit all required checkpoints/verdict. Do not repeat the review narrative. " : ""}Complete these exact runtime scope IDs using complete_review_scope: ${JSON.stringify(scopes.map(scope => scope.id))}. These are scope IDs, not node IDs. ${finalScope ? `After those checkpoints succeed, call exactly one terminal tool: ${terminalKinds.join(" or ")}. A prose conclusion is not a committed verdict.` : "More scopes remain; do not submit an overall verdict yet."}`;
+        const userMessage = `${input.sessionOptions.userMessage}\n\n${completionInstruction}`;
+        if (++calls > 128)
+            return { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: "FRONTEND_REVIEW_RECOVERY_EXHAUSTED: session quota reached" };
+        last = await observeFrontendSession({ ...input.observation, phase: `${input.phase}/scope`, scopeIds: scopes.map(s => s.id), prompt, userMessage, customTools,
+            artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-${calls}.json` : undefined,
+            committedCount: () => protocol.committedFacts().length, durableCommittedCount: () => protocol.committedFacts().length,
+        }, observer => input.piStepFn({ ...input.sessionOptions, prompt, userMessage, onAttemptObservation: observer, writerToolPolicy: { requireSdk: true, customTools } }));
+        await input.tools.flush();
+        await input.inventory.validate();
+        if (last.timedOut || /interrupt|termination-unconfirmed|budget_breach/.test(last.failureCategory))
+            return { ...last, ok: false };
+        const capacity = readWriterThinkingExhaustionEvidence(last).stopReason === "length" || ["context-overflow", "context-budget-exhausted"].includes(last.failureCategory);
+        const missing = scopes.filter(s => !protocol.completedScopeIds().has(s.id));
+        if (capacity && (missing.length || !terminal() && finalScope)) {
+            if (missing.length === 1 && scopes.length === 1 || !missing.length && !scopes.length)
+                return { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: "FRONTEND_INPUT_UNIT_TOO_LARGE: complete review unit or terminal exhausted" };
+            const at = Math.ceil(missing.length / 2);
+            const smaller = missing.length ? [missing.slice(0, at), missing.slice(at)].filter(s => s.length) : [[]];
+            queue.splice(index, 1, ...smaller.map(scopes => ({ scopes, repairs: 0 })));
+            index--;
+            continue;
+        }
+        if (!last.ok && !capacity) {
+            // Terminal-only completion: this protocol finishes through durable
+            // tools (complete_review_scope -> approve_review/request_review_changes),
+            // so the model can end its turn with no closing prose and the step
+            // classifies as empty-output even though the review is complete
+            // (smoke r27/r31/r32 committed the terminal and still reported
+            // empty-output; the node then replayed the committed fact in an
+            // extra attempt). Accept the segment here instead, so a completed
+            // review neither spends a replay attempt nor depends on the retry
+            // ladder, and a misclassified category (smoke r28 read a finding id
+            // containing UNAUTHORIZED as an auth error, which is not retryable)
+            // can no longer turn a committed review into a node failure.
+            if (last.failureCategory === "empty-output" && terminal() && !missing.length) {
+                try {
+                    await input.tools.flush();
+                    protocol.assertComplete();
+                    return { ...last, ok: true, failureCategory: "success" };
+                }
+                catch {
+                    // Unfinished scope checkpoints still fail this segment.
+                }
+            }
+            return last;
+        }
+        if (missing.length || finalScope && !terminal()) {
+            if (item.repairs >= 1)
+                return { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: "FRONTEND_REVIEW_SCOPE_INCOMPLETE: required checkpoint or verdict missing" };
+            queue.splice(index, 1, { scopes: missing, repairs: item.repairs + 1 });
+            index--;
+        }
+    }
+    protocol.assertComplete();
+    return terminal() ? { ...last, ok: true, failureCategory: "success" } : { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: "FRONTEND_REVIEW_SCOPE_INCOMPLETE: missing independent verdict" };
+}
+export async function runFrontendScoutSegmentedSessions(input) {
+    const inventory = parseFrontendInputBlock(input.basePrompt, "scout");
+    if (!inventory)
+        throw Error("FRONTEND_INPUT_MISSING: Scout compiled inventory unavailable");
+    const units = collectFrontendExecutionGroups(inventory.payload.requirements).map(group => ({ ...group, id: `${group.kind === "unclassified" ? "requirement" : "group"}:${group.id}`, requirements: inventory.payload.requirements.filter(r => group.requirementIds.includes(r.id)) }));
+    const targetBytes = input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes ?? FRONTEND_SCOPE_TARGET_BYTES;
+    const queue = packFrontendInputUnits(units, { targetBytes, maxUnits: input.sessionOptions.frontendExecutionPolicy?.maxScopeUnits }).map(batch => ({ groups: batch, repairs: 0 }));
+    let last = { ok: true, assistantText: "", command: [], durationMs: 0, exitCode: 0, failureCategory: "success", modelDisplay: input.sessionOptions.modelConfig?.model ?? "unknown", parsedEvents: 0, stderr: "", stdout: "", timedOut: false, attemptedModels: [], fallbackUsed: false, tokensUsed: 0 };
+    let calls = 0;
+    for (let index = 0; index < queue.length; index++) {
+        await input.tools.flush();
+        const item = queue[index];
+        const completed = input.tools.completedRequirementIds();
+        const groups = item.groups.filter(g => g.requirementIds.some(id => !completed.has(id)));
+        if (!groups.length)
+            continue;
+        const ids = groups.flatMap(g => g.requirementIds);
+        const scopeId = input.tools.setActiveScope(ids);
+        const prompt = input.basePrompt.replace(inventory.block, `<frontend_scout_input>\n${JSON.stringify(projectFrontendInputScope(inventory.payload, ids))}\n</frontend_scout_input>`) +
+            `\nSCOUT SCOPE ${scopeId}: discover the related surfaces for exactly these complete obligations: ${ids.join(", ")}. Reuse proven paths from completed scope navigation; do not reread their content unless relevant new evidence is needed. Submit record_target_surface with scopeId="${scopeId}" after all discovery/design evidence for this scope. completeness=complete closes only this scope; runtime merges all scopes.\n` +
+            JSON.stringify({ completedScopePaths: input.tools.completedScopeFacts().map(f => ({ id: f.id, requirementIds: f.requirementIds, paths: f.surface?.implementationPaths })) });
+        const envelopeBytes = Buffer.byteLength(prompt + input.sessionOptions.userMessage + JSON.stringify(input.customTools.map(t => { const tool = t; return { name: tool.name, description: tool.description, parameters: tool.parameters }; })));
+        if (envelopeBytes > targetBytes && groups.length > 1) {
+            const at = Math.ceil(groups.length / 2);
+            queue.splice(index, 1, { groups: groups.slice(0, at), repairs: 0 }, { groups: groups.slice(at), repairs: 0 });
+            index--;
+            continue;
+        }
+        if (++calls > 128)
+            return { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: "SCOUT_RECOVERY_EXHAUSTED: shared session quota reached" };
+        last = await observeFrontendSession({ ...input.observation, phase: "scout/scope", scopeIds: ids, prompt, userMessage: input.sessionOptions.userMessage, customTools: input.customTools,
+            artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-${calls}.json` : undefined,
+            committedCount: () => input.tools.committedFacts().length, durableCommittedCount: () => input.tools.committedFacts().length,
+        }, observer => input.piStepFn({ ...input.sessionOptions, prompt, onAttemptObservation: observer, writerToolPolicy: { requireSdk: true, customTools: input.customTools } }));
+        await input.tools.flush();
+        const missing = groups.filter(g => g.requirementIds.some(id => !input.tools.completedRequirementIds().has(id)));
+        if (last.timedOut || /interrupt|termination-unconfirmed|budget_breach/.test(last.failureCategory))
+            return { ...last, ok: false };
+        const capacity = readWriterThinkingExhaustionEvidence(last).stopReason === "length" || ["context-overflow", "context-budget-exhausted"].includes(last.failureCategory);
+        if (capacity && missing.length) {
+            if (missing.length === 1 && groups.length === 1)
+                return { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: `${last.stderr}\nFRONTEND_INPUT_UNIT_TOO_LARGE: Scout ${missing[0].id}; refine the complete source unit; unchanged retries disabled` };
+            const at = Math.ceil(missing.length / 2);
+            queue.splice(index, 1, ...[missing.slice(0, at), missing.slice(at)].filter(batch => batch.length).map(batch => ({ groups: batch, repairs: 0 })));
+            index--;
+            continue;
+        }
+        if (!last.ok && !capacity)
+            return last;
+        if (missing.length) {
+            if (item.repairs >= 1)
+                return { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: "SCOUT_SCOPE_INCOMPLETE: unresolved discovery remains after local correction" };
+            queue.splice(index, 1, { groups: missing, repairs: item.repairs + 1 });
+            index--;
+            continue;
+        }
+    }
+    await input.tools.flush();
+    const { readCompleteScoutTargetSurface } = await import("../../../workflows/dag/frontend-committed-facts.js");
+    const closure = readCompleteScoutTargetSurface(input.tools.committedFacts());
+    return closure.ok ? { ...last, ok: true, failureCategory: "success" } : { ...last, ok: false, failureCategory: "frontend-input-exhausted", stderr: closure.reason };
+}
+export async function runFrontendContractSegmentedSessions(input) {
+    // Requirement identity, text, and source fragments are frozen in the
+    // runtime ledger. Seed those facts once; model sessions spend their budget
+    // on execution grouping, evidence expectations, and genuine decisions.
+    await input.tools.seedCanonicalRequirements();
+    // Build from the frozen runtime inventory if the caller has not rendered it yet.
+    const basePrompt = parseFrontendInputBlock(input.basePrompt, "contract") ? input.basePrompt : input.basePrompt +
+        `\n<frontend_contract_input>\nFrozen complete source obligations.\n${JSON.stringify({ requirements: input.tools.inputRequirements() })}\n</frontend_contract_input>`;
+    const inventory = parseFrontendInputBlock(basePrompt, "contract");
+    const pending = inventory.payload.requirements.filter(r => !input.tools.completedScopeRequirementIds().has(r.id));
+    const batches = packFrontendInputUnits(pending, { targetBytes: input.sessionOptions.frontendExecutionPolicy?.scopeTargetBytes, maxUnits: input.sessionOptions.frontendExecutionPolicy?.maxScopeUnits });
+    if (!batches.length)
+        batches.push([]);
+    let last;
+    let invocation = 0;
+    const maxSessions = batches.length * 3 + 2;
+    const terminal = () => input.tools.committedFacts().some(r => r.fact.kind === "contract-finalized");
+    try {
+        for (let index = 0; index < batches.length; index += 1) {
+            let scopeIds = batches[index].map(r => r.id);
+            const finalScope = index === batches.length - 1;
+            for (let repair = 0; repair < 2; repair += 1) {
+                // Confirmed IDs remain visible until the model commits a scope checkpoint.
+                const completed = input.tools.completedScopeRequirementIds();
+                scopeIds = scopeIds.filter(id => !completed.has(id));
+                input.tools.setActiveRequirementScope(scopeIds);
+                const groupIndex = collectFrontendExecutionGroups(input.tools.committedFacts().filter(r => r.fact.kind === "requirement").map(r => ({ id: String(r.fact.id), execution: r.fact.execution })));
+                const shared = input.tools.committedFacts().filter(r => !["requirement", "contract-finalized", "contract-scope-completed"].includes(String(r.fact.kind))).map(r => r.fact);
+                const prompt = projectFrontendContractPrompt(basePrompt, scopeIds) +
+                    `\nCONTRACT SCOPE: analyze only ${scopeIds.join(", ") || "(all scopes complete; verify global facts and terminal)"}. Requirement identity/text/source fragments are already committed by runtime; do not call record_requirement. Use record_requirement_execution for model-owned execution grouping, then submit decisions and evidence records. Call complete_contract_scope after ALL decisions for this scope. ` +
+                    (finalScope ? "After complete scope coverage and source-bound deliverables, call finalize_contract. Correct rejected calls and retry." : "Do not finalize; subsequent complete scopes remain.") +
+                    `\n<committed_contract_facts>\n${JSON.stringify({ facts: shared, executionGroups: groupIndex })}\n</committed_contract_facts>`;
+                const customTools = input.tools.customTools.filter(t => finalScope || t.name !== "finalize_contract");
+                invocation += 1;
+                if (invocation > maxSessions)
+                    return { ...last, ok: false, failureCategory: "invalid-output", stderr: "CONTRACT_RECOVERY_EXHAUSTED: session quota exceeded" };
+                const committedBefore = input.tools.committedFacts().length;
+                last = await observeFrontendSession({
+                    ...input.observation, phase: "contract/scope", scopeIds, prompt, userMessage: input.sessionOptions.userMessage, customTools,
+                    artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-${invocation}.json` : undefined,
+                    committedCount: () => input.tools.committedFacts().length, durableCommittedCount: () => input.tools.committedFacts().length,
+                }, observer => input.piStepFn({ ...input.sessionOptions, prompt, onAttemptObservation: observer, writerToolPolicy: { requireSdk: true, customTools } }));
+                await input.tools.flush();
+                if (last.timedOut || /interrupt|termination-unconfirmed|budget_breach/.test(last.failureCategory))
+                    return { ...last, ok: false };
+                const capacityExhausted = readWriterThinkingExhaustionEvidence(last).stopReason === "length" || ["context-overflow", "context-budget-exhausted"].includes(last.failureCategory);
+                if (capacityExhausted && !last.timedOut) {
+                    const missing = scopeIds.filter(id => !input.tools.completedScopeRequirementIds().has(id));
+                    if (!missing.length) {
+                        if (finalScope && !terminal()) {
+                            if (!scopeIds.length)
+                                return { ...last, ok: false, failureCategory: "invalid-output", stderr: `${last.stderr}\nFRONTEND_INPUT_UNIT_TOO_LARGE: contract terminal exhausted; unchanged retry disabled` };
+                            batches.push([]);
+                        }
+                        break;
+                    }
+                    if (missing.length === 1 && scopeIds.length > 1) {
+                        batches.splice(index, 1, inventory.payload.requirements.filter(r => missing.includes(r.id)));
+                        index -= 1;
+                        break;
+                    }
+                    if (missing.length <= 1)
+                        return { ...last, ok: false, stderr: `${last.stderr}\nFRONTEND_INPUT_UNIT_TOO_LARGE: ${missing[0] ?? "contract terminal"}; atom could not complete; refine the source without dropping conditions` };
+                    const smaller = packFrontendInputUnits(inventory.payload.requirements.filter(r => missing.includes(r.id)), { maxUnits: Math.ceil(missing.length / 2) });
+                    batches.splice(index, 1, ...smaller);
+                    index -= 1;
+                    break;
+                }
+                // A session that ends with blank assistant text but committed new
+                // facts is not a node failure: small-output models legitimately
+                // stop after their tool calls. Continue so the scope/repair checks
+                // below decide, instead of burning a full node retry.
+                const committedFactsOnlySuccess = !(last.assistantText ?? "").trim() &&
+                    !last.stderr.trim() &&
+                    input.tools.committedFacts().length > committedBefore;
+                if (!last.ok && !committedFactsOnlySuccess)
+                    return last;
+                if (committedFactsOnlySuccess)
+                    last = { ...last, ok: true, failureCategory: "success" };
+                const missing = scopeIds.filter(id => !input.tools.completedScopeRequirementIds().has(id));
+                if (!missing.length && (!finalScope || terminal()))
+                    break;
+                if (repair === 1)
+                    return { ...last, ok: false, failureCategory: "invalid-output", stderr: `CONTRACT_SCOPE_INCOMPLETE: ${missing.join(", ") || "missing finalize_contract"}` };
+            }
+        }
+        return last;
+    }
+    finally {
+        input.tools.setActiveRequirementScope(null);
+    }
+}
+export async function runFrontendPlanSegmentedSessions(input) {
+    const queue = [];
+    const coverageSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "coverage");
+    const uxRegistrySegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "ux-registry");
+    const uxSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "ux-local");
+    const globalMockDataSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "global-mock-data");
+    const allRequirementIds = input.requirementIds ?? [];
+    const buildPhasePrompt = (segment, missing = [], scopeIds = allRequirementIds) => {
+        const compact = allRequirementIds.length > 0
+            ? compactFrontendPlanPromptForRequirementSlice(input.basePrompt, scopeIds, {
+                includeRequirementText: segment.id === "global-mock-data" || segment.id === "finalize",
+                includeVerificationTargets: false,
+                includeDesignEvidence: segment.id === "global-dependency-deviation" || segment.id === "finalize",
+                includeChecklist: false,
+            })
+            : input.basePrompt;
+        const kinds = segment.id === "global-route"
+            ? ["target-surface"]
+            : segment.id === "global-mock-data"
+                ? ["plan-requirement", "plan-verification-target", "state-flow", "data-flow", "mock-api"]
+                : segment.id === "global-dependency-deviation"
+                    ? ["dependency", "design-deviation"]
+                    : ["plan-requirement", "plan-verification-target", "state-registry", "component-choice", "state-flow", "data-flow", "mock-api", "design-deviation", "dependency", "target-surface"];
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: scopeIds,
+                kinds,
+                ...(segment.id === "global-mock-data" ? { scopedKinds: ["state-flow"] } : {}),
+            })
+            : "";
+        return [
+            compact,
+            segment.instruction,
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: repair ONLY these items, then re-check the phase:",
+                    ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const buildCoveragePrompt = (slice, missing = []) => [
+        compactFrontendPlanPromptForRequirementSlice(input.basePrompt, slice),
+        coverageSegment.instruction,
+        `COVERAGE BATCH: process ONLY these requirements in this session: ${slice.join(", ")}. Other requirements are handled by separate sessions; do not record them. Finish the whole list before concluding: commit every listed requirement's coverage facts (verification targets or an evidence gap), batching up to 4 record_* calls per message; an early stop re-queues the remainder as a MISSING-FACT repair session.`,
+        ...(missing.length > 0
+            ? [
+                "MISSING-FACT QUEUE: the previous session did not establish complete coverage. Repair ONLY these items, then re-check the slice:",
+                ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+            ]
+            : []),
+    ].join("\n\n");
+    const buildUxPrompt = (slice, missing = []) => {
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: slice,
+                kinds: [
+                    "plan-requirement",
+                    "plan-verification-target",
+                    "state-registry",
+                    "component-choice",
+                    "state-flow",
+                ],
+                // Include shared state bindings from other scopes; page full values before correcting.
+            })
+            : "";
+        return [
+            compactFrontendPlanPromptForRequirementSlice(input.basePrompt, slice),
+            uxSegment.instruction,
+            `UX SCOPE: process these complete behavior groups together: ${slice.join(", ")}. Reuse shared registry/component ownership; do not rename a behavior by requirement id. Constraint/exclusion groups do not create UI; preserve genuine verification gaps.`,
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: repair ONLY these items, then re-check this UX slice:",
+                    ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const buildUxRegistryPrompt = (missing = []) => {
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: allRequirementIds,
+                kinds: [
+                    "plan-requirement",
+                    "plan-verification-target",
+                    "state-registry",
+                ],
+            })
+            : "";
+        const compact = allRequirementIds.length > 0
+            ? compactFrontendPlanPromptForRequirementSlice(input.basePrompt, allRequirementIds, {
+                includeRequirementText: false,
+                includeVerificationTargets: false,
+                includeDesignEvidence: false,
+                includeChecklist: false,
+            })
+            : input.basePrompt;
+        return [
+            compact,
+            uxRegistrySegment.instruction,
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: commit the global UX registry, then re-check this phase:",
+                    ...missing.map((item) => `- ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const buildCompactLocalPrompt = (missing = []) => {
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: allRequirementIds,
+                kinds: [
+                    "plan-requirement",
+                    "plan-verification-target",
+                    "state-registry",
+                    "component-choice",
+                    "state-flow",
+                ],
+            })
+            : "";
+        return [
+            compactFrontendPlanPromptForRequirementSlice(input.basePrompt, allRequirementIds),
+            "PLAN PHASE — compact local planning for a small frontend request.",
+            "Review all listed requirements together and record_state_registry first with one global UX vocabulary. Then record every plan-requirement and verification-target fact, followed by component/state-flow facts and the minimal route, Mock/data, dependency, and design-deviation policy facts needed by the observable behavior. Do not read the repository or task source; use only the committed input above. Do not call finalize_plan in this session.",
+            "TOOL-FIRST: your first assistant actions must be record_* tool calls, at most 2-3 facts per message. Do not draft the whole analysis before recording; if a fact is uncertain, record it with an evidence gap instead of reasoning longer.",
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: repair ONLY these items, then re-check the compact local phase:",
+                    ...missing.map((item) => `- ${item.kind}${item.id ? ` ${item.id}` : ""} for ${item.requirementIds.join(", ")}: ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
+    const mapPlannerExhaustion = (r, committedAnyFacts) => isPlannerThinkingExhausted(r, committedAnyFacts)
+        ? {
+            ...r,
+            failureCategory: OUTPUT_LIMIT_RETRY_CATEGORY,
+            stderr: `${r.stderr}\n${OUTPUT_LIMIT_RETRY_CATEGORY}: stopReason=length ended the turn before the next typed fact; preserve committed facts and retry only the unfinished phase`.trim(),
+        }
+        : r;
+    // An empty list means "ledger unreadable / unknown" and falls back to one
+    // unscoped coverage session; a non-empty list enables deterministic sharding.
+    const requirementIdsProvided = input.requirementIds !== undefined && input.requirementIds.length > 0;
+    const pending = (input.requirementIds ?? []).filter((id) => !input.committedRequirementIds?.().has(id));
+    const initialMissing = requirementIdsProvided && input.committedFacts
+        ? collectFrontendPlanMissingFacts({
+            requirementIds: input.requirementIds,
+            committedFacts: input.committedFacts(),
+        })
+        : [];
+    const incompleteRequirementIds = new Set(initialMissing.flatMap((item) => item.requirementIds));
+    const coverageWorkIds = (input.requirementIds ?? []).filter((id) => pending.includes(id) || incompleteRequirementIds.has(id));
+    if (input.parallelCoverageOnly === true &&
+        requirementIdsProvided &&
+        coverageWorkIds.length === 0) {
+        // A retry may reopen a shard whose committed facts are already complete.
+        // Treat that shard as an idempotent no-op; returning the normal empty
+        // session failure would make a partially failed map impossible to resume.
+        return {
+            ok: true,
+            assistantText: "",
+            command: [],
+            durationMs: 0,
+            exitCode: 0,
+            failureCategory: "success",
+            modelDisplay: "reused-coverage-facts",
+            parsedEvents: 0,
+            stderr: "",
+            stdout: "",
+            timedOut: false,
+            attemptedModels: [],
+            fallbackUsed: false,
+            tokensUsed: 0,
+        };
+    }
+    const compiledInput = parseFrontendInputBlock(input.basePrompt, "plan")?.payload;
+    const fullUnits = new Map(compiledInput?.requirements.map(r => [r.id, r]) ?? []);
+    const workCost = (ids) => 1 + ids.reduce((total, id) => total + Math.max(1, (input.requirementCosts?.get(id) ?? 2) - 1), 0);
+    const { workGroups, buildWorkBatches, compactEligible } = buildFrontendPlanWorkload({
+        basePrompt: input.basePrompt, requirementIds: allRequirementIds,
+        requirementCosts: input.requirementCosts, sessionOptions: input.sessionOptions,
+    });
+    // Data decisions are grouped by observable data domain. Requirements that
+    // mention the same endpoint/resource or execution group share one session;
+    // unrelated domains remain isolated. This prevents the old requirement-by-
+    // requirement repetition while preserving the packer's size bound.
+    const buildDataBatches = (ids) => {
+        const selected = new Set(ids);
+        const domains = new Map();
+        for (const [index, group] of workGroups.entries()) {
+            const members = group.requirementIds.filter((id) => selected.has(id));
+            if (!members.length)
+                continue;
+            const texts = members.map((id) => String(fullUnits.get(id)?.text ?? ""));
+            const endpoint = texts
+                .map((text) => text.match(/\b(?:GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s,;.)]+)/i)?.[1])
+                .find(Boolean);
+            const resource = endpoint
+                ? endpoint.split("/").filter(Boolean).slice(0, 2).join("/")
+                : undefined;
+            const domain = resource ? `endpoint:${resource}` : `group:${group.id}`;
+            const current = domains.get(domain);
+            if (current) {
+                current.requirementIds.push(...members);
+                current.requirements.push(...members.map((id) => fullUnits.get(id) ?? { id }));
+                current.estimatedCalls = workCost(current.requirementIds);
+            }
+            else {
+                domains.set(domain, {
+                    id: `${index}:${domain}`,
+                    requirementIds: [...members],
+                    requirements: members.map((id) => fullUnits.get(id) ?? { id }),
+                    estimatedCalls: workCost(members),
+                });
+            }
+        }
+        const work = [...domains.values()];
+        // Work-unit packing and full provider envelope capacity have separate budgets.
+        return packFrontendInputUnits(work, {
+            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,
+        }).map((batch) => batch.flatMap((group) => group.requirementIds));
+    };
+    // Dependency/deviation is optional policy. For a pure local UI request with
+    // no dependency, package, design-conflict, or OpenSpec signal, opening a
+    // dedicated model session only produces an empty policy fact. Keep the
+    // session when the prompt or ledger contains any such signal so this is a
+    // conservative skip, not a blanket removal of the gate.
+    const dependencyDeviationNeeded = /(?:dependenc|package\.json|npm\s+(?:install|i)|yarn\s+add|pnpm\s+add|openspec|design\s+conflict|规范冲突|依赖)/i.test(input.basePrompt) ||
+        Boolean(input.committedFacts?.().some((record) => {
+            const fact = committedFactFromPlanRecord(record);
+            return fact?.kind === "dependency" || fact?.kind === "design-deviation";
+        }));
+    const globalPolicyToolNames = new Set([
+        "record_route_selection",
+        "record_dependency",
+        "record_design_deviation",
+        "adopt_staged_fact",
+    ]);
+    const globalPolicyPrompt = [
+        "PLAN PHASE — global implementation policy.",
+        "Use the Scout target surface to record the selected route(s), then record dependency policy and design-evidence conflicts only when they are relevant. Do not record requirement-local UX or Mock/data facts. Do not call finalize_plan.",
+        dependencyDeviationNeeded
+            ? "Dependency/design policy signals are present; inspect them and commit the minimal policy facts needed."
+            : "No dependency/design-conflict signal was found; do not invent a policy fact.",
+    ].join(" ");
+    let globalPolicyQueued = false;
+    // Small, single-surface requests do not benefit from six isolated Pi
+    // sessions. Keep the typed ledger as the authority, but let one local
+    // session establish requirement/UX facts and one final session establish
+    // cross-cutting policy + finalize. The old sharded ladder remains available
+    // for larger plans and for the unscoped compatibility path.
+    const useCompactSmallPlan = requirementIdsProvided &&
+        input.compactSmallPlan === true &&
+        compactEligible;
+    if (useCompactSmallPlan) {
+        const compactLocalTools = new Set([
+            "record_plan_requirement",
+            "record_plan_group_coverage",
+            "record_plan_verification_target",
+            "record_plan_evidence_gap",
+            "record_state_registry",
+            "record_component_choice",
+            "record_state_flow",
+            "record_route_selection",
+            "record_data_flow",
+            "record_mock_api",
+            "record_mock_endpoint",
+            "record_dependency",
+            "record_design_deviation",
+            "adopt_staged_fact",
+        ]);
+        queue.push({
+            id: "compact-local",
+            toolNames: compactLocalTools,
+            requirementSlice: [...allRequirementIds],
+            prompt: buildCompactLocalPrompt(),
+        });
+    }
+    else if (!requirementIdsProvided) {
+        queue.push({
+            id: "coverage",
+            toolNames: coverageSegment.toolNames,
+            prompt: `${input.basePrompt}\n\n${coverageSegment.instruction}`,
+        });
+    }
+    else if (coverageWorkIds.length > 0) {
+        const completeBatches = buildWorkBatches(coverageWorkIds);
+        completeBatches.forEach((slice, batchIndex) => queue.push({
+            id: `coverage-batch-${batchIndex + 1}`,
+            toolNames: coverageSegment.toolNames,
+            coverageSlice: slice,
+            coverageOnly: true,
+            prompt: buildCoveragePrompt(slice),
+        }));
+    }
+    if (useCompactSmallPlan) {
+        // Compact mode already queued both sessions above.
+    }
+    else if (!input.parallelCoverageOnly) {
+        if (requirementIdsProvided) {
+            queue.push({
+                id: uxRegistrySegment.id,
+                toolNames: uxRegistrySegment.toolNames,
+                prompt: buildUxRegistryPrompt(),
+            });
+        }
+        const uxWorkIds = workGroups.filter(g => !["constraint", "exclusion"].includes(g.kind) || g.requirementIds.some(id => input.behaviorRequiredRequirementIds?.includes(id))).flatMap(g => g.requirementIds);
+        const uxBatches = requirementIdsProvided ? buildWorkBatches(uxWorkIds) : [[]];
+        uxBatches.forEach((slice, batchIndex) => queue.push({
+            id: `ux-local-${batchIndex + 1}`,
+            toolNames: requirementIdsProvided ? uxSegment.toolNames : new Set([...(uxSegment.toolNames ?? []), "record_state_registry"]),
+            ...(slice.length ? { requirementSlice: slice } : {}),
+            prompt: slice.length ? buildUxPrompt(slice) : buildPhasePrompt(uxSegment),
+        }));
+        for (const segment of FRONTEND_PLAN_SEGMENTS) {
+            if (["coverage", "ux-registry", "ux-local"].includes(segment.id))
+                continue;
+            if (segment.id === "global-dependency-deviation" && !dependencyDeviationNeeded)
+                continue;
+            if (segment.id === "global-route") {
+                if (globalPolicyQueued)
+                    continue;
+                globalPolicyQueued = true;
+                queue.push({
+                    id: "global-policy",
+                    toolNames: globalPolicyToolNames,
+                    prompt: `${buildPhasePrompt(segment)}\n\n${globalPolicyPrompt}`,
+                });
+                continue;
+            }
+            if (segment.id === "global-dependency-deviation")
+                continue;
+            if (segment.id === "global-mock-data" && requirementIdsProvided) {
+                buildDataBatches(allRequirementIds).forEach((slice, i) => queue.push({ id: `global-mock-data-${i + 1}`, toolNames: segment.toolNames, requirementSlice: slice, prompt: buildPhasePrompt(segment, [], slice) }));
+            }
+            else {
+                queue.push({
+                    id: segment.id,
+                    toolNames: segment.toolNames,
+                    prompt: buildPhasePrompt(segment),
+                });
+            }
+        }
+    }
+    let accumulated;
+    let index = 0;
+    let invocationCount = 0;
+    let lastDurableCount = input.committedFactCount();
+    while (index < queue.length) {
+        const session = queue[index];
+        if (!session)
+            break;
+        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({
+                requirementIds: session.coverageSlice,
+                committedFacts: input.committedFacts(),
+            })
+            : [];
+        // Resume/earlier-batch commits may already cover this slice.
+        if (session.coverageOnly &&
+            session.coverageSlice &&
+            remaining.length === 0 &&
+            preexistingMissing.length === 0) {
+            index += 1;
+            continue;
+        }
+        // Resume only unfinished UX scopes. The registry and local decisions are
+        // durable facts; replaying a completed scope wastes a model session and
+        // can make a previously valid shared decision look like a duplicate.
+        if (session.id === "ux-registry" &&
+            input.committedFacts &&
+            !collectFrontendPlanPhaseMissingFacts({
+                phase: "ux-registry",
+                requirementIds: allRequirementIds,
+                committedFacts: input.committedFacts(),
+            }).length) {
+            index += 1;
+            continue;
+        }
+        if (session.id.startsWith("ux-local-") &&
+            session.requirementSlice &&
+            (input.behaviorRequiredRequirementIds?.length ?? 0) > 0 &&
+            input.committedFacts &&
+            !collectFrontendPlanPhaseMissingFacts({
+                phase: "ux-local",
+                requirementIds: session.requirementSlice,
+                committedFacts: input.committedFacts(),
+                behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
+            }).length) {
+            index += 1;
+            continue;
+        }
+        let prompt = session.prompt;
+        if (session.coverageOnly && session.coverageSlice) {
+            const promptSlice = [...new Set([...remaining, ...preexistingMissing.flatMap(item => item.requirementIds)])];
+            prompt = buildCoveragePrompt(promptSlice, session.missingFacts ?? preexistingMissing);
+        }
+        else if (session.id === "compact-local") {
+            prompt = buildCompactLocalPrompt(session.missingFacts);
+        }
+        else if (session.id === "ux-registry") {
+            prompt = buildUxRegistryPrompt(session.missingFacts);
+        }
+        else if (session.id.startsWith("ux-local-")) {
+            // Build this at execution time: coverage facts are committed by the
+            // preceding sessions and must be visible to the UX-local model.
+            prompt = session.requirementSlice
+                ? buildUxPrompt(session.requirementSlice, session.missingFacts)
+                : buildPhasePrompt(uxSegment, session.missingFacts);
+        }
+        else {
+            // Global phases consume the latest committed ledger;
+            // constructing their prompt only when the session starts prevents a
+            // stale queue entry from dropping facts written by earlier phases.
+            const segment = FRONTEND_PLAN_SEGMENTS.find((candidate) => candidate.id === session.id || (candidate.id === "global-mock-data" && session.id.startsWith("global-mock-data-")));
+            if (session.id === "global-policy") {
+                const routePrompt = buildPhasePrompt(FRONTEND_PLAN_SEGMENTS.find((candidate) => candidate.id === "global-route"));
+                prompt = `${routePrompt}\n\n${globalPolicyPrompt}`;
+            }
+            else if (segment) {
+                prompt = 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 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 result = await observeFrontendSession({
+            ...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) => {
+            const result = await input.piStepFn({
+                ...input.sessionOptions,
+                onAttemptObservation: observer,
+                prompt,
+                ...(customTools.length > 0
+                    ? {
+                        writerToolPolicy: {
+                            requireSdk: true,
+                            customTools,
+                        },
+                    }
+                    : {}),
+            });
+            try {
+                await input.flushLedger();
+                lastDurableCount = input.committedFactCount();
+            }
+            catch {
+                // best-effort: the node-level flush runs again after the attempt
+            }
+            return result;
+        });
+        accumulated = accumulated
+            ? combineSequentialPiResults(accumulated, result)
+            : result;
+        const committedAfter = input.committedFactCount();
+        const committedFactsOnlySuccess = !(result.assistantText ?? "").trim() &&
+            !result.stderr.trim() &&
+            !result.timedOut &&
+            committedAfter > committedBefore;
+        const missingCoverage = session.coverageOnly && session.coverageSlice && input.committedFacts
+            ? collectFrontendPlanMissingFacts({
+                requirementIds: session.coverageSlice,
+                committedFacts: input.committedFacts(),
+            })
+            : [];
+        const isCompactLocalSession = session.id === "compact-local";
+        const isUxRegistrySession = session.id === "ux-registry";
+        const isUxLocalSession = session.id.startsWith("ux-local-");
+        const missingPhase = isCompactLocalSession && input.committedFacts
+            ? [
+                ...collectFrontendPlanMissingFacts({
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                }),
+                ...collectFrontendPlanPhaseMissingFacts({
+                    phase: "ux-registry",
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                }),
+                ...collectFrontendPlanPhaseMissingFacts({
+                    phase: "ux-local",
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                    behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
+                }),
+            ]
+            : isUxRegistrySession && input.committedFacts
+                ? collectFrontendPlanPhaseMissingFacts({
+                    phase: "ux-registry",
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                })
+                : isUxLocalSession && session.requirementSlice && input.committedFacts
+                    ? collectFrontendPlanPhaseMissingFacts({
+                        phase: "ux-local",
+                        requirementIds: session.requirementSlice,
+                        committedFacts: input.committedFacts(),
+                        behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
+                    })
+                    : session.id.startsWith("global-mock-data") && allRequirementIds.length > 0 && input.committedFacts
+                        ? collectFrontendPlanPhaseMissingFacts({
+                            phase: "global-mock-data",
+                            requirementIds: session.requirementSlice ?? allRequirementIds,
+                            committedFacts: input.committedFacts(),
+                        })
+                        : [];
+        const missingPhaseFacts = [...missingCoverage, ...missingPhase];
+        // Frozen verification commands must operate on files the planner has
+        // committed verification targets for; otherwise the admission writeSet
+        // cannot authorize the file and verify-shell deterministically fails.
+        const verificationCommandFiles = collectFrontendVerificationCommandFiles(input.basePrompt);
+        if (verificationCommandFiles.length > 0 && allRequirementIds.length > 0 && input.committedFacts) {
+            const coveredVerificationFiles = new Set(input
+                .committedFacts()
+                .map(committedFactFromPlanRecord)
+                .filter((fact) => Boolean(fact && fact.origin === "plan" && fact.kind === "plan-verification-target"))
+                .map((fact) => fact.entry?.file)
+                .filter((file) => typeof file === "string"));
+            for (const file of verificationCommandFiles) {
+                if (coveredVerificationFiles.has(file))
+                    continue;
+                missingPhaseFacts.push({
+                    kind: "plan-verification-target",
+                    id: file,
+                    requirementIds: allRequirementIds.slice(0, 1),
+                    reason: `frozen verification command references ${file} but no committed verification target covers it; record a static verification target for this file so it joins the writeSet`,
+                });
+            }
+        }
+        const promptForMissingPhase = (missing) => session.coverageOnly
+            ? buildCoveragePrompt(session.coverageSlice ?? [], missing)
+            : isCompactLocalSession
+                ? buildCompactLocalPrompt(missing)
+                : isUxRegistrySession
+                    ? buildUxRegistryPrompt(missing)
+                    : isUxLocalSession
+                        ? buildUxPrompt(session.requirementSlice ?? [], missing)
+                        : buildPhasePrompt(globalMockDataSegment, missing, session.requirementSlice ?? allRequirementIds);
+        const recovery = classifyFrontendPlanRecovery({ ...result, stopReason: readWriterThinkingExhaustionEvidence(result).stopReason });
+        if (recovery === "stop")
+            return { ...result, ok: false };
+        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)];
+            const splitScope = (ids, allowMemberSplit) => {
+                const groups = workGroups.map(g => g.requirementIds.filter(id => ids.includes(id))).filter(g => g.length);
+                if (groups.length > 1) {
+                    const half = Math.ceil(groups.length / 2);
+                    return [groups.slice(0, half).flat(), groups.slice(half).flat()];
+                }
+                if (allowMemberSplit && ids.length > 1) {
+                    const half = Math.ceil(ids.length / 2);
+                    return [ids.slice(0, half), ids.slice(half)];
+                }
+                return [];
+            };
+            if (isCompactLocalSession) {
+                let scopes = splitScope(missingCoverageIds, true);
+                if (!scopes.length && missingCoverageIds.length) {
+                    if (missingCoverageIds.length === allRequirementIds.length && committedAfter === committedBefore)
+                        return failure();
+                    scopes = [missingCoverageIds];
+                }
+                // UX ownership is independent of coverage completion. Preserve all groups.
+                const recovery = scopes.map((slice, i) => ({ id: `coverage-capacity-${invocationCount}-${i}`, coverageOnly: true, coverageSlice: slice, toolNames: coverageSegment.toolNames, prompt: buildCoveragePrompt(slice) }));
+                recovery.push({ id: "ux-registry", toolNames: uxRegistrySegment.toolNames, prompt: buildUxRegistryPrompt() });
+                recovery.push(...buildWorkBatches([...allRequirementIds]).map((slice, i) => ({ id: `ux-local-capacity-${invocationCount}-${i}`, requirementSlice: slice, toolNames: uxSegment.toolNames, prompt: buildUxPrompt(slice) })));
+                queue.splice(index, 1, ...recovery);
+                continue;
+            }
+            if (session.coverageOnly || isUxLocalSession) {
+                const missingIds = session.coverageOnly ? missingCoverageIds : [...new Set(missingPhase.flatMap(f => f.requirementIds))];
+                if (!missingIds.length) {
+                    index += 1;
+                    continue;
+                }
+                const scopes = splitScope(missingIds, Boolean(session.coverageOnly));
+                if (scopes.length) {
+                    queue.splice(index, 1, ...scopes.map(slice => ({ ...session, ...(session.coverageOnly ? { coverageSlice: slice } : { requirementSlice: slice }), missingFacts: missingPhaseFacts.filter(f => f.requirementIds.some(id => slice.includes(id))), retryCount: 0 })));
+                    continue;
+                }
+                const originalIds = session.coverageSlice ?? session.requirementSlice ?? [];
+                if ((missingIds.length < originalIds.length || committedAfter > committedBefore) && (session.retryCount ?? 0) < 2) {
+                    queue[index] = { ...session, ...(session.coverageOnly ? { coverageSlice: missingIds } : { requirementSlice: missingIds }), missingFacts: missingPhaseFacts, retryCount: (session.retryCount ?? 0) + 1 };
+                    continue;
+                }
+            }
+            return failure();
+        }
+        if (result.ok) {
+            if (missingPhaseFacts.length === 0) {
+                index += 1;
+                continue;
+            }
+            if ((session.retryCount ?? 0) < 2) {
+                queue[index] = {
+                    ...session,
+                    retryCount: (session.retryCount ?? 0) + 1,
+                    missingFacts: missingPhaseFacts,
+                    prompt: promptForMissingPhase(missingPhaseFacts),
+                };
+                continue;
+            }
+            return {
+                ...accumulated,
+                ok: false,
+                stderr: `${accumulated.stderr}\nfrontend plan completeness check failed: ${missingPhaseFacts.map((item) => item.reason).join("; ")}`.trim(),
+                failureCategory: "invalid-output",
+            };
+        }
+        if (committedFactsOnlySuccess) {
+            // The session died but banked facts: keep the progress and move on.
+            if (missingPhaseFacts.length > 0 && (session.retryCount ?? 0) < 2) {
+                queue[index] = {
+                    ...session,
+                    retryCount: (session.retryCount ?? 0) + 1,
+                    missingFacts: missingPhaseFacts,
+                    prompt: promptForMissingPhase(missingPhaseFacts),
+                };
+                continue;
+            }
+            if (missingPhaseFacts.length > 0) {
+                return {
+                    ...accumulated,
+                    ok: false,
+                    stderr: `${accumulated.stderr}\nfrontend plan completeness check failed: ${missingPhaseFacts.map((item) => item.reason).join("; ")}`.trim(),
+                    failureCategory: "invalid-output",
+                };
+            }
+            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. The compact
+        // local session participates through its requirementSlice so a
+        // thinking-burned small plan degrades into smaller batched sessions
+        // instead of replaying one full-scope prompt until the repair budget
+        // runs out.
+        const coverageSlice = session.coverageOnly
+            ? session.coverageSlice
+            : isCompactLocalSession
+                ? session.requirementSlice
+                : undefined;
+        const zeroProgressBurn = coverageSlice !== undefined &&
+            coverageSlice.length > 1 &&
+            (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;
+            const unfinished = coverageSlice.filter(id => !missingIds || missingIds.has(id));
+            if (unfinished.length <= 1)
+                return mapPlannerExhaustion({ ...result, ok: false, stderr: `${result.stderr}\nFRONTEND_INPUT_UNIT_TOO_LARGE: ${unfinished[0] ?? session.id}; no smaller complete scope can finish` }, committedAfter > committedBefore);
+            const half = Math.ceil(unfinished.length / 2);
+            const firstSlice = unfinished.slice(0, half);
+            const secondSlice = unfinished.slice(half);
+            if (isCompactLocalSession) {
+                queue.splice(index + 1, 0, { id: "ux-registry", toolNames: uxRegistrySegment.toolNames, prompt: buildUxRegistryPrompt() }, ...buildWorkBatches([...firstSlice, ...secondSlice]).map((slice, i) => ({ id: `ux-local-recovery-${i}`, toolNames: uxSegment.toolNames, requirementSlice: slice, prompt: buildUxPrompt(slice) })));
+                // The split halves leave compact mode: continue them as ordinary
+                // coverage sessions so every downstream ladder branch applies.
+                queue.splice(index, 1, {
+                    ...session,
+                    id: `coverage-compact-split-1`,
+                    toolNames: coverageSegment.toolNames, retryCount: 0,
+                    coverageOnly: true,
+                    coverageSlice: firstSlice,
+                    requirementSlice: firstSlice,
+                    prompt: buildCoveragePrompt(firstSlice),
+                }, {
+                    ...session,
+                    id: `coverage-compact-split-2`,
+                    toolNames: coverageSegment.toolNames, retryCount: 0,
+                    coverageOnly: true,
+                    coverageSlice: secondSlice,
+                    requirementSlice: secondSlice,
+                    prompt: buildCoveragePrompt(secondSlice),
+                });
+                continue;
+            }
+            queue.splice(index, 1, {
+                ...session,
+                coverageSlice: firstSlice,
+                prompt: buildCoveragePrompt(firstSlice),
+            }, {
+                ...session,
+                coverageSlice: secondSlice,
+                prompt: buildCoveragePrompt(secondSlice),
+            });
+            continue;
+        }
+        if (readWriterThinkingExhaustionEvidence(result).stopReason === "length" || ["context-overflow", "context-budget-exhausted"].includes(result.failureCategory))
+            return mapPlannerExhaustion({ ...result, ok: false, stderr: `${result.stderr}\nFRONTEND_INPUT_UNIT_TOO_LARGE: ${session.id}; refine the remaining complete scope; unchanged retries are disabled` }, committedAfter > committedBefore);
+        if ((session.coverageOnly || isUxRegistrySession || isUxLocalSession || session.id.startsWith("global-mock-data")) &&
+            missingPhaseFacts.length > 0 &&
+            !result.stderr.trim() &&
+            !result.timedOut &&
+            (session.retryCount ?? 0) < 2) {
+            queue[index] = {
+                ...session,
+                retryCount: (session.retryCount ?? 0) + 1,
+                missingFacts: missingPhaseFacts,
+                prompt: promptForMissingPhase(missingPhaseFacts),
+            };
+            continue;
+        }
+        return mapPlannerExhaustion(accumulated, committedAfter > committedBefore);
+    }
+    if (index < queue.length) {
+        return {
+            ...(accumulated ?? {
+                ok: false,
+                stdout: "",
+                stderr: "",
+                assistantText: "",
+                command: [],
+                durationMs: 0,
+                exitCode: null,
+                failureCategory: "invalid-output",
+                modelDisplay: "unknown",
+                parsedEvents: 0,
+                timedOut: false,
+                attemptedModels: [],
+                fallbackUsed: false,
+                tokensUsed: 0,
+            }),
+            ok: false,
+            stderr: `${accumulated?.stderr ?? ""}\nfrontend plan segmentation exceeded the ${FRONTEND_PLAN_BATCH_MAX_SESSIONS}-session safety limit before finalize`.trim(),
+            failureCategory: "invalid-output",
+        };
+    }
+    if (!input.parallelCoverageOnly && input.finalizePlan) {
+        // Preserve optional closeout context if an earlier correction or future
+        // ledger producer committed it. The old model-only finalize session was
+        // the only writer of these fields; runtime-owned finalization must not
+        // silently erase them when they are already available.
+        const optionalPlanFields = {};
+        for (const record of input.committedFacts?.() ?? []) {
+            const fact = committedFactFromPlanRecord(record);
+            if (!fact)
+                continue;
+            if (Array.isArray(fact.residualRisks)) {
+                optionalPlanFields.residualRisks = fact.residualRisks.filter((item) => typeof item === "string" && item.trim().length > 0);
+            }
+            if (typeof fact.realIntegrationGap === "string" && fact.realIntegrationGap.trim()) {
+                optionalPlanFields.realIntegrationGap = fact.realIntegrationGap;
+            }
+        }
+        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;
+        if (!finalizeDetails ||
+            typeof finalizeDetails !== "object" ||
+            finalizeDetails.ok !== true) {
+            // Normal plans never open a finalize model session. Keep the old
+            // correction/recovery semantic only for a rejected deterministic
+            // compile: give the planner one bounded repair pass, then retry the
+            // same runtime authority. The correction prompt explicitly forbids
+            // calling finalize_plan, so terminal ownership remains deterministic.
+            const correctionPrompt = [
+                input.basePrompt,
+                "PLAN FINALIZE CORRECTION — the runtime compile rejected the committed ledger.",
+                `Runtime error: ${String(finalizeDetails?.error ?? "plan finalize rejected")}`,
+                "Repair only the reported facts with the typed record_* tools. Do not call finalize_plan; the runtime will retry it after this correction.",
+                input.committedFacts ? compactFrontendPlanLedgerContext({ committedFacts: input.committedFacts(), requirementIds: input.requirementIds ?? [], kinds: ["plan-requirement", "plan-verification-target", "state-registry", "component-choice", "state-flow", "data-flow", "mock-api", "design-deviation", "dependency", "target-surface"] }) : "",
+            ].filter(Boolean).join("\n\n");
+            input.setActiveRequirementScope?.([]);
+            const correctionTools = input.segmentCustomTools(null);
+            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;
+            });
+            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 finalize();
+            }
+            const retriedDetails = finalizeResult && typeof finalizeResult === "object"
+                ? (finalizeResult.details ?? finalizeResult)
+                : finalizeResult;
+            if (retriedDetails && typeof retriedDetails === "object" && retriedDetails.ok === true) {
+                return mapPlannerExhaustion(accumulated ?? { ok: true, stdout: "", stderr: "", assistantText: "", command: [], durationMs: 0, exitCode: 0, failureCategory: "success", modelDisplay: "runtime-finalize", parsedEvents: 0, timedOut: false, attemptedModels: [], fallbackUsed: false, tokensUsed: 0 }, true);
+            }
+            const detail = retriedDetails && typeof retriedDetails === "object"
+                ? String(retriedDetails.error ?? "plan finalize rejected")
+                : "plan finalize rejected";
+            return {
+                ...(accumulated ?? {
+                    ok: false,
+                    stdout: "",
+                    stderr: "",
+                    assistantText: "",
+                    command: [],
+                    durationMs: 0,
+                    exitCode: null,
+                    failureCategory: "invalid-output",
+                    modelDisplay: "unknown",
+                    parsedEvents: 0,
+                    timedOut: false,
+                    attemptedModels: [],
+                    fallbackUsed: false,
+                    tokensUsed: 0,
+                }),
+                ok: false,
+                stderr: `${accumulated?.stderr ?? ""}\nfrontend plan deterministic finalize failed: ${detail}`.trim(),
+                failureCategory: "invalid-output",
+            };
+        }
+    }
+    return mapPlannerExhaustion(accumulated ?? {
+        ok: false,
+        stdout: "",
+        stderr: "frontend plan segmentation produced no session",
+        failureCategory: "empty-output",
+        durationMs: 0,
+    }, false);
+}