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

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

@@ -0,0 +1,367 @@
+/** DAG Pi 分段会话的提示词投影：覆盖/UX/全局阶段 prompt 与账本上下文压缩，禁止反向依赖执行器入口。 */
+import { projectFrontendInputScope } from "../../../workflows/dag/frontend-input-projection.js";
+import { isRecordObject } from "../guards.js";
+import { committedFactFromPlanRecord, planFactScopeIntersects, planFactStringList } from "../plan/facts.js";
+export function compactPromptString(value, _maxChars) {
+    return typeof value === "string" && value.trim().length ? value.trim() : undefined;
+}
+export function compactPromptStringArray(value, _maxEntries = 12, maxChars = 180) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => compactPromptString(item, maxChars))
+        .filter((item) => item !== undefined);
+}
+export function compactFrontendPlanPromptForRequirementSlice(basePrompt, requirementIds, options = {}) {
+    const slice = [...new Set(requirementIds.filter((id) => id.trim().length > 0))];
+    if (slice.length === 0)
+        return basePrompt;
+    const planInputPattern = /<frontend_plan_input>[\s\S]*?<\/frontend_plan_input>/;
+    const planInputMatch = planInputPattern.exec(basePrompt);
+    if (!planInputMatch)
+        return basePrompt;
+    const blockLines = planInputMatch[0].split(/\r?\n/);
+    let payload;
+    for (const line of blockLines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                payload = parsed;
+                break;
+            }
+        }
+        catch {
+            // The surrounding block contains prose; only its JSON line is data.
+        }
+    }
+    if (!payload || !Array.isArray(payload.requirements))
+        throw Error("FRONTEND_INPUT_INVALID: plan inventory is not parseable");
+    const requirementsById = new Map();
+    for (const value of payload.requirements) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const requirement = value;
+        if (typeof requirement.id === "string") {
+            requirementsById.set(requirement.id, requirement);
+        }
+    }
+    const requirements = slice.map((id) => requirementsById.get(id));
+    if (requirements.some((requirement) => requirement === undefined)) {
+        throw Error(`FRONTEND_INPUT_SCOPE_MISSING: ${slice.filter(id => !requirementsById.has(id)).join(", ")}`);
+    }
+    const compactRequirements = requirements.map((requirement) => ({
+        id: compactPromptString(requirement.id, 80),
+        ...(options.includeRequirementText !== false && compactPromptString(requirement.text, 240)
+            ? { text: compactPromptString(requirement.text, 240) }
+            : {}),
+        sourceFragmentIds: compactPromptStringArray(requirement.sourceFragmentIds, 20, 80),
+    }));
+    const sliceSet = new Set(slice);
+    const compactVerificationTargets = options.includeVerificationTargets === false
+        ? []
+        : Array.isArray(payload.verificationTargets)
+            ? payload.verificationTargets.flatMap((value) => {
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    return [];
+                const target = value;
+                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 [
+                    {
+                        ...(typeof target.id === "string"
+                            ? { id: target.id }
+                            : {}),
+                        ...(typeof target.commandId === "string"
+                            ? { commandId: target.commandId }
+                            : {}),
+                        ...(compactPromptString(target.commandLabel, 180)
+                            ? { commandLabel: compactPromptString(target.commandLabel, 180) }
+                            : {}),
+                        ...(typeof target.file === "string"
+                            ? { file: target.file }
+                            : {}),
+                        requirementIds: relatedRequirementIds,
+                        uiStates: planFactStringList(target.uiStates),
+                    },
+                ];
+            })
+            : [];
+    const compactTargetSurface = Array.isArray(payload.targetSurface)
+        ? payload.targetSurface.flatMap((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [];
+            const surface = value;
+            return [
+                {
+                    ...(compactPromptString(surface.completeness, 32)
+                        ? { completeness: compactPromptString(surface.completeness, 32) }
+                        : {}),
+                    ...(compactPromptString(surface.entrypoint, 180)
+                        ? { entrypoint: compactPromptString(surface.entrypoint, 180) }
+                        : {}),
+                    ...(compactPromptString(surface.routeOrMount, 180)
+                        ? { routeOrMount: compactPromptString(surface.routeOrMount, 180) }
+                        : {}),
+                    implementationPaths: compactPromptStringArray(surface.implementationPaths),
+                    proposedPaths: compactPromptStringArray(surface.proposedPaths),
+                    testPaths: compactPromptStringArray(surface.testPaths),
+                    ...(compactPromptString(surface.dataSource, 180)
+                        ? { dataSource: compactPromptString(surface.dataSource, 180) }
+                        : {}),
+                    allowedPathConflicts: compactPromptStringArray(surface.allowedPathConflicts),
+                    unresolvedPaths: compactPromptStringArray(surface.unresolvedPaths),
+                },
+            ];
+        })
+        : [];
+    const compactDesignEvidence = options.includeDesignEvidence === true &&
+        Array.isArray(payload.designEvidence)
+        ? payload.designEvidence.flatMap((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [];
+            const evidence = value;
+            return [{
+                    ...(compactPromptString(evidence.source, 180)
+                        ? { source: compactPromptString(evidence.source, 180) }
+                        : {}),
+                    paths: compactPromptStringArray(evidence.paths, 12, 180),
+                    conflicts: compactPromptStringArray(evidence.conflicts, 24, 180),
+                }];
+        })
+        : [];
+    const compactDeclaredUiStates = Array.isArray(payload.declaredUiStates)
+        ? payload.declaredUiStates.flatMap((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [];
+            const state = value;
+            const id = typeof state.id === "string" ? state.id : undefined;
+            if (!id)
+                return [];
+            return [{
+                    id,
+                    ...(compactPromptString(state.trigger, 180)
+                        ? { trigger: compactPromptString(state.trigger, 180) }
+                        : {}),
+                    ...(compactPromptString(state.observableOutcome, 240)
+                        ? { observableOutcome: compactPromptString(state.observableOutcome, 240) }
+                        : {}),
+                }];
+        })
+        : [];
+    const committedUx = payload.committedUx &&
+        typeof payload.committedUx === "object" &&
+        !Array.isArray(payload.committedUx)
+        ? payload.committedUx
+        : undefined;
+    const compactPayload = {
+        inputManifest: { ...projectFrontendInputScope({ ...payload, requirements: [...requirementsById.values()] }, slice).inputManifest, semantics: options.includeRequirementText === false ? "navigation-only" : "full" },
+        constraints: payload.constraints,
+        executionGroups: Array.isArray(payload.executionGroups) ? payload.executionGroups.filter(g => isRecordObject(g) && Array.isArray(g.requirementIds) && g.requirementIds.some(id => slice.includes(String(id)))) : [],
+        requirements: compactRequirements,
+        requiredDeliverables: Array.isArray(payload.requiredDeliverables) ? payload.requiredDeliverables : [],
+        ...(compactTargetSurface.length > 0
+            ? { targetSurface: compactTargetSurface }
+            : {}),
+        ...(compactVerificationTargets.length > 0
+            ? { verificationTargets: compactVerificationTargets }
+            : {}),
+        ...(compactDesignEvidence.length > 0
+            ? { designEvidence: compactDesignEvidence }
+            : {}),
+        ...(compactDeclaredUiStates.length > 0
+            ? { declaredUiStates: compactDeclaredUiStates }
+            : {}),
+        ...(committedUx
+            ? {
+                committedUx: {
+                    uiStateNames: compactPromptStringArray(committedUx.uiStateNames, 40, 100),
+                    interactionNames: compactPromptStringArray(committedUx.interactionNames, 60, 120),
+                },
+            }
+            : {}),
+    };
+    const compactBlock = [
+        "<frontend_plan_input>",
+        `Committed Contract/Scout facts for ONLY the current requirement slice (${slice.join(", ")}); do not infer or record requirements outside this slice.`,
+        JSON.stringify(compactPayload),
+        "Do not read upstream artifacts, task sources, or repository files. If this slice cannot support a decision, record a genuine evidence gap.",
+        "</frontend_plan_input>",
+    ].join("\n");
+    let compactPrompt = basePrompt.replace(planInputPattern, compactBlock);
+    compactPrompt = compactPrompt.replace(/<upstream_context>[\s\S]*?<\/upstream_context>/, "<upstream_context>\n(full upstream prose omitted; use only the slice-specific typed facts above)\n</upstream_context>");
+    compactPrompt = compactPrompt.replace(/Cover each frozen requirement ID exactly once:[^\n]*/, `Cover ONLY the current requirement slice: ${slice.join(", ")}. Record each slice requirement exactly once.`);
+    const checklistPattern = /<plan_review_checklist>([\s\S]*?)<\/plan_review_checklist>/;
+    const checklistMatch = checklistPattern.exec(compactPrompt);
+    if (checklistMatch) {
+        if (options.includeChecklist === false) {
+            compactPrompt = compactPrompt.replace(checklistPattern, "");
+            return compactPrompt;
+        }
+        const checklist = checklistMatch[1]
+            .split(/\r?\n/)
+            .filter((line) => {
+            const requirementLine = /^Requirements requiring behavioural coverage:\s*(.*)$/.exec(line.trim());
+            if (requirementLine) {
+                return false;
+            }
+            const citationId = /^([^\s]+)\s+\+/.exec(line.trim())?.[1];
+            return citationId === undefined || sliceSet.has(citationId);
+        })
+            .concat([`Requirements requiring behavioural coverage: ${slice.join(", ") || "(none)"}`])
+            .join("\n");
+        compactPrompt = compactPrompt.replace(checklistPattern, `<plan_review_checklist>${checklist}</plan_review_checklist>`);
+    }
+    return compactPrompt;
+}
+export function compactFrontendPlanLedgerContext(input) {
+    const slice = new Set(input.requirementIds);
+    const allowed = new Set(input.kinds);
+    const scopedKinds = new Set(input.scopedKinds ?? []);
+    const compactFacts = [];
+    for (const value of input.committedFacts) {
+        const fact = committedFactFromPlanRecord(value);
+        if (!fact || fact.origin !== "plan" || typeof fact.kind !== "string" || !allowed.has(fact.kind))
+            continue;
+        if (scopedKinds.has(fact.kind) && !planFactScopeIntersects(fact, slice)) {
+            continue;
+        }
+        const entry = fact.entry && typeof fact.entry === "object" && !Array.isArray(fact.entry)
+            ? fact.entry
+            : undefined;
+        if (fact.kind === "plan-requirement") {
+            if (!entry || typeof entry.id !== "string" || !slice.has(entry.id))
+                continue;
+            compactFacts.push({
+                kind: fact.kind,
+                entry: {
+                    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) }
+                        : {}),
+                    ...(entry.evidenceGap && typeof entry.evidenceGap === "object"
+                        ? { evidenceGap: entry.evidenceGap }
+                        : {}),
+                },
+            });
+            continue;
+        }
+        if (fact.kind === "plan-verification-target") {
+            if (!entry)
+                continue;
+            // 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: entry.id,
+                    commandId: entry.commandId,
+                    file: entry.file,
+                    requirementIds,
+                    uiStates: planFactStringList(entry.uiStates).slice(0, 12),
+                },
+            });
+            continue;
+        }
+        if (fact.kind === "component-choice") {
+            const choices = Array.isArray(fact.uiComponentChoices)
+                ? fact.uiComponentChoices.flatMap((choice) => {
+                    if (!choice || typeof choice !== "object" || Array.isArray(choice))
+                        return [];
+                    const item = choice;
+                    return [{
+                            purpose: compactPromptString(item.purpose, 120),
+                            component: compactPromptString(item.component, 120),
+                            decision: compactPromptString(item.decision, 40),
+                            covers: compactPromptStringArray(item.covers, 40, 120),
+                            evidencePath: compactPromptString(item.evidencePath, 180),
+                        }];
+                })
+                : [];
+            if (choices.length > 0)
+                compactFacts.push({ kind: fact.kind, uiComponentChoices: choices });
+            continue;
+        }
+        if (fact.kind === "state-registry") {
+            compactFacts.push({
+                kind: fact.kind,
+                uiStateNames: planFactStringList(fact.uiStateNames).slice(0, 40),
+                interactionNames: planFactStringList(fact.interactionNames).slice(0, 60),
+            });
+            continue;
+        }
+        if (fact.kind === "state-flow") {
+            compactFacts.push({
+                kind: fact.kind,
+                uiStates: Array.isArray(fact.uiStates) ? fact.uiStates : [],
+                interactions: Array.isArray(fact.interactions) ? fact.interactions : [],
+                removeUiStateNames: compactPromptStringArray(fact.removeUiStateNames, 24, 100),
+                removeInteractionNames: compactPromptStringArray(fact.removeInteractionNames, 24, 100),
+            });
+            continue;
+        }
+        if (fact.kind === "data-flow") {
+            compactFacts.push({
+                kind: fact.kind,
+                interactions: compactPromptStringArray(fact.interactions, 32, 120),
+                endpoints: compactPromptStringArray(fact.endpoints, 32, 180),
+            });
+            continue;
+        }
+        if (fact.kind === "mock-api") {
+            const mockApi = fact.mockApi && typeof fact.mockApi === "object" && !Array.isArray(fact.mockApi)
+                ? fact.mockApi
+                : {};
+            compactFacts.push({
+                kind: fact.kind,
+                mockApi: {
+                    strategy: compactPromptString(mockApi.strategy, 40),
+                    activation: compactPromptString(mockApi.activation, 180),
+                    endpoints: Array.isArray(mockApi.endpoints) ? mockApi.endpoints : [],
+                },
+            });
+            continue;
+        }
+        if (fact.kind === "design-deviation") {
+            compactFacts.push({ kind: fact.kind, conflicts: compactPromptStringArray(fact.conflicts, 32, 180) });
+            continue;
+        }
+        if (fact.kind === "dependency") {
+            compactFacts.push({ kind: fact.kind, policy: compactPromptString(fact.policy, 300) });
+            continue;
+        }
+        if (fact.kind === "target-surface") {
+            compactFacts.push({ kind: fact.kind, routes: compactPromptStringArray(fact.routes, 24, 180), implementationPaths: compactPromptStringArray(fact.implementationPaths, 24, 180), proposedPaths: compactPromptStringArray(fact.proposedPaths, 24, 180), testPaths: compactPromptStringArray(fact.testPaths, 24, 180) });
+        }
+    }
+    if (compactFacts.length === 0)
+        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.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>",
+        "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");
+}

package/dist/executors/dag-pi/sessions/scout-parallel.js

@@ -0,0 +1,197 @@
+/** DAG Pi scout 并行分片会话：结果聚合、串行结果合并与 completedShards 缓存。 */
+import path from "node:path";
+import { observeFrontendSession } from "../../../workflows/dag/frontend-session-budget.js";
+import { createFrontendScoutEvidenceTools } from "../tools/scout-evidence-tools.js";
+export function aggregateParallelPiResults(results) {
+    const first = results[0];
+    const failed = results.find((result) => !result.ok);
+    const representative = failed ?? first;
+    return {
+        ...representative,
+        ok: failed === undefined,
+        failureCategory: failed?.failureCategory ?? "success",
+        durationMs: Math.max(...results.map((result) => result.durationMs), 0),
+        exitCode: failed ? failed.exitCode : 0,
+        stderr: results.map((result) => result.stderr).filter(Boolean).join("\n"),
+        tokensUsed: results.reduce((total, result) => total + result.tokensUsed, 0),
+        parsedEvents: results.reduce((total, result) => total + result.parsedEvents, 0),
+        attemptedModels: [
+            ...new Set(results.flatMap((result) => result.attemptedModels)),
+        ],
+        fallbackUsed: results.some((result) => result.fallbackUsed),
+        timedOut: results.some((result) => result.timedOut),
+    };
+}
+export function combineSequentialPiResults(first, second) {
+    return {
+        ...second,
+        durationMs: first.durationMs + second.durationMs,
+        stderr: [first.stderr, second.stderr].filter(Boolean).join("\n"),
+        tokensUsed: first.tokensUsed + second.tokensUsed,
+        parsedEvents: first.parsedEvents + second.parsedEvents,
+        attemptedModels: [
+            ...new Set([...first.attemptedModels, ...second.attemptedModels]),
+        ],
+        fallbackUsed: first.fallbackUsed || second.fallbackUsed,
+        timedOut: first.timedOut || second.timedOut,
+    };
+}
+export async function runFrontendScoutParallelSessions(input) {
+    const [{ createTypedEventStore }] = await Promise.all([
+        import("../../../workflows/dag/frontend-typed-event-store.js"),
+    ]);
+    const shards = [
+        {
+            id: "surface",
+            toolName: "record_target_surface",
+            instruction: [
+                "PARALLEL SCOUT SHARD — target surface only.",
+                "Inspect routes, entrypoints, implementation ownership, data source, and existing test entrypoints. Inspect project source/config first; do not recursively explore dependency internals merely to reconfirm standard test-runner behavior. If a concrete required capability cannot be established from project evidence, report the precise gap.",
+                "Call record_target_surface exactly once with the complete runtime-evidenced surface. Do not call record_design_evidence.",
+            ].join(" "),
+        },
+        {
+            id: "design",
+            toolName: "record_design_evidence",
+            instruction: [
+                "PARALLEL SCOUT SHARD — design evidence only.",
+                "Inspect project-owned frontend framework, styling/theme conventions, reusable components, and relevant design/spec files. The surface shard owns test-runner/environment discovery; do not duplicate its Vitest/happy-dom investigation. Stop discovery once the design evidence is sufficient and commit it.",
+                "Call record_design_evidence for the evidence you actually read. Do not call record_target_surface.",
+            ].join(" "),
+        },
+    ];
+    const outcomes = await Promise.all(shards.map(async (shard) => {
+        const cacheKey = JSON.stringify([input.runDir, input.nodeId, shard.id, input.sessionOptions.modelConfig, input.observation?.model, input.observation?.sourceDigest, input.sourceDeclaredPaths]);
+        const cached = input.completedShards?.get(cacheKey);
+        if (cached)
+            return { shard, facts: cached.facts, result: { ...cached.result, durationMs: 0, tokensUsed: 0, parsedEvents: 0, attemptedModels: [], fallbackUsed: false } };
+        let shardTools;
+        let shardResult;
+        try {
+            const store = createTypedEventStore();
+            const shardNodeId = `${input.nodeId}/parallel/${shard.id}`;
+            shardTools = await createFrontendScoutEvidenceTools({
+                attemptId: `${input.attemptId}:parallel:${shard.id}`,
+                store,
+                runDir: input.runDir,
+                nodeId: shardNodeId,
+                workspaceRoot: input.workspaceRoot,
+                sourceDeclaredPaths: input.sourceDeclaredPaths,
+            });
+            const customTools = shardTools.customTools.filter((tool) => typeof tool === "object" &&
+                tool !== null &&
+                tool.name === shard.toolName);
+            const sessionOptions = {
+                ...input.sessionOptions,
+                sessionEventsPath: path.join(input.runDir, shardNodeId, "session-events.jsonl"),
+            };
+            const prompt = `${input.basePrompt}\n\n${shard.instruction}`;
+            const tools = [...customTools, ...(input.readBudgetTools ?? [])];
+            shardResult = await observeFrontendSession({
+                ...input.observation,
+                phase: `scout/parallel/${shard.id}`,
+                scopeIds: [shard.id],
+                prompt,
+                userMessage: sessionOptions.userMessage,
+                customTools: tools,
+                artifactPath: input.observation?.artifactPath ? `${input.observation.artifactPath}-${shard.id}.json` : undefined,
+                committedCount: () => shardTools?.committedFacts().length ?? 0,
+                durableCommittedCount: () => shardTools?.committedFacts().length ?? 0,
+            }, observer => input.piStepFn({
+                ...sessionOptions,
+                onAttemptObservation: observer,
+                prompt,
+                writerToolPolicy: {
+                    requireSdk: true,
+                    customTools: tools,
+                },
+            }));
+            await shardTools.flush();
+            const facts = shardTools.committedFacts();
+            const expectedKind = shard.id === "design" ? "design-evidence" : "target-surface";
+            if (shardResult.ok && facts.some(record => { const fact = record.fact; return fact.kind === expectedKind && (shard.id !== "surface" || fact.completeness === "complete"); })) {
+                input.completedShards?.set(cacheKey, { result: structuredClone(shardResult), facts: structuredClone(facts) });
+            }
+            return { shard, result: shardResult, tools: shardTools, facts };
+        }
+        catch (error) {
+            const crashMessage = `frontend scout parallel shard ${shard.id} crashed: ${error instanceof Error ? error.message : String(error)}`;
+            return {
+                shard,
+                tools: shardTools,
+                result: shardResult
+                    ? {
+                        ...shardResult,
+                        ok: false,
+                        failureCategory: shardResult.ok
+                            ? "invalid-output"
+                            : shardResult.failureCategory,
+                        stderr: [shardResult.stderr, crashMessage]
+                            .filter(Boolean)
+                            .join("\n"),
+                    }
+                    : {
+                        ok: false,
+                        assistantText: "",
+                        command: [],
+                        durationMs: 0,
+                        exitCode: null,
+                        failureCategory: "tool-policy",
+                        modelDisplay: "unknown",
+                        parsedEvents: 0,
+                        stderr: crashMessage,
+                        stdout: "",
+                        timedOut: false,
+                        attemptedModels: [],
+                        fallbackUsed: false,
+                        tokensUsed: 0,
+                    },
+            };
+        }
+    }));
+    const ordered = [...outcomes].sort((left, right) => left.shard.id.localeCompare(right.shard.id));
+    try {
+        for (const outcome of ordered) {
+            if (outcome.result.ok) {
+                await input.mainTools.adoptCommittedFacts(outcome.facts ?? outcome.tools?.committedFacts() ?? []);
+            }
+        }
+    }
+    catch (error) {
+        const aggregate = aggregateParallelPiResults(ordered.map((outcome) => outcome.result));
+        return {
+            ...aggregate,
+            ok: false,
+            failureCategory: "invalid-output",
+            stderr: [
+                aggregate.stderr,
+                `frontend scout parallel fact merge failed: ${error instanceof Error ? error.message : String(error)}`,
+            ]
+                .filter(Boolean)
+                .join("\n"),
+        };
+    }
+    const failed = ordered.find((outcome) => !outcome.result.ok);
+    if (failed) {
+        const aggregate = aggregateParallelPiResults(ordered.map((outcome) => outcome.result));
+        return {
+            ...aggregate,
+            ok: false,
+            stderr: `${aggregate.stderr}\nfrontend scout parallel shard failed: ${failed.shard.id}`.trim(),
+        };
+    }
+    const committedKinds = new Set(ordered.flatMap((outcome) => (outcome.facts ?? outcome.tools?.committedFacts() ?? [])
+        .map((record) => record.fact?.kind)
+        .filter((kind) => typeof kind === "string")));
+    const missing = ["target-surface", "design-evidence"].filter((kind) => !committedKinds.has(kind));
+    if (missing.length > 0) {
+        const fallback = aggregateParallelPiResults(ordered.map((outcome) => outcome.result));
+        return {
+            ...fallback,
+            ok: false,
+            failureCategory: "invalid-output",
+            stderr: `${fallback.stderr}\nfrontend scout parallel shards committed no ${missing.join(" or ")} fact`.trim(),
+        };
+    }
+    return aggregateParallelPiResults(ordered.map((outcome) => outcome.result));
+}