@alexeiled/pi-fusion 0.6.2 → 0.8.0

package/src/panel-completion.ts

@@ -1,9 +1,19 @@
-import { renderPanelFailureReport, renderSinglePanelReport } from "./report.js";
+import {
+  detectCallerOutputContract,
+  validateCallerOutput,
+} from "./caller-contract.js";
+import {
+  renderFailureReport,
+  renderPanelFailureReport,
+  renderPartialPanelReport,
+  renderSinglePanelReport,
+} from "./report.js";
 import {
   appendThinkingSuffix,
   buildJudgeSpawnParams,
   type JudgeSpawnParams,
 } from "./run-builder.js";
+import { resolveMinimumSuccessfulPanelists } from "./panel-quorum.js";
 import {
   resolveSynthesisMode,
   type FailedPanelSummary,
@@ -12,6 +22,8 @@ import {
   type PanelOutput,
 } from "./types.js";
 
+export { resolveMinimumSuccessfulPanelists } from "./panel-quorum.js";
+
 export type PanelCompletionDecision =
   | { kind: "fail"; error: string; report: string }
   | { kind: "complete"; report: string }
@@ -50,14 +62,48 @@ export function decidePanelCompletion(
     };
   }
 
-  // Under `select` every panelist answered the whole question, so a lone
-  // survivor is a complete if thin answer. Under `merge` it answered ONE facet:
-  // returning it as the answer would be wrong, not thin. Run the composer so
-  // the report names the facets nobody covered.
+  const intentionalStops =
+    input.profile.stopWhenPanelAgrees === true &&
+    input.panelOutputs.length >= 2 &&
+    input.panelFailures.length > 0 &&
+    input.panelFailures.every(
+      ({ reason }) => reason === "stopped-after-agreement",
+    );
+  const synthesis = resolveSynthesisMode(input.profile);
+  const required = resolveMinimumSuccessfulPanelists(
+    input.run.minimumSuccessfulPanelists ??
+      input.profile.minimumSuccessfulPanelists,
+    input.profile.panel.length,
+  );
+  // A configured one-member panel is still validated as an exact caller
+  // contract, but does not need a synthetic comparison.
   if (
-    input.panelOutputs.length === 1 &&
-    resolveSynthesisMode(input.profile) !== "merge"
+    synthesis !== "merge" &&
+    input.profile.panel.length === 1 &&
+    input.panelOutputs.length === 1
   ) {
+    const callerContract =
+      input.run.outputContract ??
+      detectCallerOutputContract(input.run.prompt);
+    if (callerContract) {
+      const validation = validateCallerOutput(
+        callerContract,
+        input.panelOutputs[0]!.output,
+      );
+      if (!validation.ok) {
+        const report = renderFailureReport({
+          run: input.run,
+          error: validation.error,
+          panelOutputs: input.panelOutputs,
+          failures: input.panelFailures,
+          ...withJudgeModel(judgeModel),
+          synthesis,
+          panel: input.profile.panel,
+        });
+        return { kind: "fail", error: validation.error, report };
+      }
+    }
+
     const report = renderSinglePanelReport({
       run: input.run,
       output: input.panelOutputs[0]!,
@@ -67,6 +113,49 @@ export function decidePanelCompletion(
     return { kind: "complete", report };
   }
 
+  // Synthesis needs two candidates for select mode. A lower configured quorum
+  // still produces a useful, explicitly unsynthesized partial report instead
+  // of pretending that one panelist is a panel.
+  if (
+    (input.panelOutputs.length < required && !intentionalStops) ||
+    input.panelOutputs.length < 2
+  ) {
+    const report = renderPartialPanelReport({
+      run: { ...input.run, completionQuality: "partial" },
+      panelOutputs: input.panelOutputs,
+      failures: input.panelFailures,
+      required,
+      synthesis,
+      panel: input.profile.panel,
+      ...withJudgeModel(judgeModel),
+    });
+    const callerContract =
+      input.run.outputContract ?? detectCallerOutputContract(input.run.prompt);
+    if (callerContract) {
+      // A partial report must disclose its incomplete coverage, but that prose
+      // is forbidden by exact caller contracts. Do not publish a report that
+      // merely looks successful while violating the caller's protocol.
+      const validation = validateCallerOutput(callerContract, report);
+      if (!validation.ok) {
+        const error = `${validation.error} Fusion could not synthesize a contract-compliant result from below-quorum panel coverage.`;
+        return {
+          kind: "fail",
+          error,
+          report: renderFailureReport({
+            run: input.run,
+            error,
+            panelOutputs: input.panelOutputs,
+            failures: input.panelFailures,
+            ...withJudgeModel(judgeModel),
+            synthesis,
+            panel: input.profile.panel,
+          }),
+        };
+      }
+    }
+    return { kind: "complete", report };
+  }
+
   return {
     kind: "judge",
     params: buildJudgeSpawnParams({
@@ -75,6 +164,15 @@ export function decidePanelCompletion(
       panelOutputs: input.panelOutputs,
       failedPanelists: input.panelFailures,
       runId: input.run.id,
+      ...(input.run.outputContract
+        ? { callerContract: input.run.outputContract }
+        : {}),
+      ...(input.run.timeoutOverrides
+        ? { timeoutOverrides: input.run.timeoutOverrides }
+        : {}),
+      ...(input.run.effectiveTimeouts
+        ? { effectiveTimeouts: input.run.effectiveTimeouts }
+        : {}),
     }),
     missingRunIdError: input.fallbackJudge
       ? "pi-subagents spawn did not return a fallback judge run ID."

package/src/panel-quorum.ts

@@ -0,0 +1,22 @@
+import type { MinimumSuccessfulPanelists } from "./types.js";
+
+/**
+ * Resolves a configured panel-success policy to the number of successful
+ * panelists required for synthesis and agreement stopping.
+ */
+export function resolveMinimumSuccessfulPanelists(
+  policy: MinimumSuccessfulPanelists | undefined,
+  panelSize: number,
+): number {
+  if (policy === "all") return panelSize;
+  if (typeof policy === "number") {
+    // A multi-member synthesis cannot truthfully claim a panel conclusion from
+    // one answer. Preserve one-member panels while making legacy numeric `1`
+    // behave as the minimum meaningful two-candidate quorum.
+    return panelSize > 1 ? Math.max(2, Math.min(policy, panelSize)) : 1;
+  }
+  // Fusion uses a quorum (half rounded up), not an absolute strict-majority
+  // vote: two independent completed answers are enough to synthesize a
+  // four-member panel while still requiring two of three.
+  return Math.ceil(panelSize / 2);
+}

package/src/report.ts

@@ -1,3 +1,7 @@
+import {
+  detectCallerOutputContract,
+  validateCallerOutput,
+} from "./caller-contract.js";
 import {
   buildBlindLabelMap,
   type FailedPanelSummary,
@@ -23,6 +27,10 @@ type ReportRun = Pick<
   | "panelRunId"
   | "judgeRunId"
   | "panelStopReason"
+  | "outputContract"
+  | "completionQuality"
+  | "minimumSuccessfulPanelists"
+  | "effectiveTimeouts"
 > &
   Partial<Pick<FusionRun, "phase" | "createdAt" | "updatedAt">>;
 
@@ -43,6 +51,16 @@ export interface RenderSinglePanelReportInput {
   judgeModel?: string;
 }
 
+export interface RenderPartialPanelReportInput {
+  run: ReportRun;
+  panelOutputs: readonly PanelOutput[];
+  failures: readonly FailedPanelSummary[];
+  required: number;
+  synthesis: FusionSynthesisMode;
+  panel: readonly PanelMemberConfig[];
+  judgeModel?: string;
+}
+
 export interface RenderJudgeReportInput {
   run: ReportRun;
   judgeOutput: string;
@@ -118,9 +136,13 @@ interface AgentStatusOptions {
 /** Lists the facets that no panelist covered, for a merge-mode failure. */
 function formatUncoveredFacets(
   panel?: readonly PanelMemberConfig[],
+  outputs: readonly PanelOutput[] = [],
 ): string | string[] {
   if (!panel?.length) return "Every configured facet is uncovered.";
-  return panel.map((member) => {
+  const covered = new Set(outputs.map((output) => output.index));
+  const missing = panel.filter((_member, index) => !covered.has(index));
+  if (missing.length === 0) return "No configured facets are uncovered.";
+  return missing.map((member) => {
     const facet =
       member.question?.trim() ?? member.role?.trim() ?? "the whole task";
     return `- ${memberLabel(member)}: ${facet} (uncovered)`;
@@ -227,6 +249,9 @@ export function renderPanelFailureReport(
 export function renderSinglePanelReport(
   input: RenderSinglePanelReportInput,
 ): string {
+  const exactOutput = validExactCallerOutput(input.run, input.output.output);
+  if (exactOutput) return exactOutput;
+
   const panelName = formatPanelName(input.output);
   const sections: ReportSection[] = [
     {
@@ -291,6 +316,15 @@ export function renderSinglePanelReport(
  * Rewrites the neutral names the judge saw back to the configured member names.
  * Longest label first so "Candidate AA" is not partly replaced by "Candidate A".
  */
+function validExactCallerOutput(
+  run: ReportRun,
+  output: string,
+): string | undefined {
+  const contract = run.outputContract ?? detectCallerOutputContract(run.prompt);
+  if (!contract) return undefined;
+  return validateCallerOutput(contract, output).ok ? output.trim() : undefined;
+}
+
 function restoreBlindLabels(
   judgeOutput: string,
   panelOutputs: readonly PanelOutput[],
@@ -314,9 +348,68 @@ function restoreBlindLabels(
   return restored;
 }
 
+export function renderPartialPanelReport(
+  input: RenderPartialPanelReportInput,
+): string {
+  const succeeded = input.panelOutputs.length;
+  const merger = input.synthesis === "merge";
+  const partial = `Partial panel coverage: ${succeeded} successful panelist(s), below the required quorum of ${input.required}. No ${merger ? "composer" : "judge"} synthesis was run.`;
+  const candidateText = input.panelOutputs
+    .map((output) => `### ${formatPanelName(output)}\n${output.output.trim()}`)
+    .join("\n\n");
+  const sections: ReportSection[] = [
+    { title: "Summary", content: partial },
+    {
+      title: "Agent Status",
+      content: formatAgentStatus({
+        panelOutputs: input.panelOutputs,
+        failures: input.failures,
+        judgeStatus: `not run - below quorum (${succeeded}/${input.required})`,
+        ...(input.judgeModel ? { judgeModel: input.judgeModel } : {}),
+        synthesis: input.synthesis,
+        extra: ["- Completion quality: partial"],
+      }),
+    },
+    ...(merger
+      ? [
+          { title: "Coverage Map" as const, content: "Partial coverage only; surviving facet outputs are listed below." },
+          { title: "Combined Answer" as const, content: candidateText || "No usable panel output." },
+          {
+            title: "Gaps" as const,
+            content: formatUncoveredFacets(input.panel, input.panelOutputs),
+          },
+          { title: "Conflicts At Seams" as const, content: "Not synthesized because the composer quorum was not met." },
+        ]
+      : [
+          { title: "Consensus" as const, content: "Not synthesized because the panel quorum was not met." },
+          { title: "Disagreements" as const, content: "Not synthesized because the judge did not run." },
+          { title: "Unique Insights" as const, content: candidateText || "No usable panel output." },
+          { title: "Blind Spots" as const, content: "Unavailable perspectives and absent cross-panel synthesis can hide important issues." },
+        ]),
+    { title: "Recommendation", content: "Use the surviving panel output as incomplete evidence, not a final fusion recommendation." },
+    {
+      title: "Risks",
+      content: `Coverage is incomplete; ${input.failures.length} panelist(s) were unavailable${input.failures.some((failure) => failure.reason === "timeout") ? " (including timeout failures)" : ""}. Fusion did not retry any panelist.`,
+    },
+    { title: "Next Step", content: "Inspect the unavailable perspectives; after this terminal run, manually start a new /fusion run if full coverage is needed." },
+    { title: "Run Metadata", content: formatRunMetadata(input.run) },
+  ];
+  const runDetails = formatRunDetails({
+    panelOutputs: input.panelOutputs,
+    failures: input.failures,
+    ...(input.judgeModel ? { judgeModel: input.judgeModel } : {}),
+    synthesis: input.synthesis,
+  });
+  if (runDetails) sections.splice(-1, 0, runDetails);
+  return renderReport(sections);
+}
+
 export function renderJudgeReport(input: RenderJudgeReportInput): string {
   const panelOutputs = input.panelOutputs ?? [];
   const failures = input.failures ?? [];
+  const exactOutput = validExactCallerOutput(input.run, input.judgeOutput);
+  if (exactOutput) return exactOutput;
+
   const judgeOutput = input.blindPanelLabels
     ? restoreBlindLabels(input.judgeOutput, panelOutputs, failures)
     : input.judgeOutput;
@@ -382,7 +475,10 @@ export function renderJudgeReport(input: RenderJudgeReportInput): string {
   const reportSections: ReportSection[] = [
     {
       title: "Summary",
-      content: sections.get("Summary") ?? judgeSummary(panelOutputs, failures),
+      content:
+        input.run.completionQuality === "partial"
+          ? `Partial panel coverage: ${panelOutputs.length} successful panelist(s) and ${failures.length} unavailable perspective(s) were synthesized. ${sections.get("Summary") ?? ""}`.trim()
+          : (sections.get("Summary") ?? judgeSummary(panelOutputs, failures)),
     },
     {
       title: "Agent Status",
@@ -392,6 +488,9 @@ export function renderJudgeReport(input: RenderJudgeReportInput): string {
         judgeStatus: "succeeded",
         ...(input.judgeModel ? { judgeModel: input.judgeModel } : {}),
         ...(input.synthesis ? { synthesis: input.synthesis } : {}),
+        ...(input.run.completionQuality === "partial"
+          ? { extra: ["- Completion quality: partial (incomplete coverage)"] }
+          : {}),
       }),
     },
     ...synthesisSections,
@@ -401,7 +500,10 @@ export function renderJudgeReport(input: RenderJudgeReportInput): string {
     },
     {
       title: "Risks",
-      content: sections.get("Risks") ?? "Not specified by the judge.",
+      content:
+        input.run.completionQuality === "partial"
+          ? `Incomplete coverage: unavailable panel perspectives${failures.some((failure) => failure.reason === "timeout") ? " include timeout failures" : ""}. ${sections.get("Risks") ?? ""}`.trim()
+          : (sections.get("Risks") ?? "Not specified by the judge."),
     },
     {
       title: "Next Step",

package/src/result-extract.ts

@@ -22,6 +22,10 @@ export interface ExtractPanelResultsOptions {
   panel?: readonly PanelMemberConfig[];
   limit?: number;
   completedOnly?: boolean;
+  /** On a terminal workflow deadline, running slots become typed failures. */
+  terminalizeRunning?: boolean;
+  /** Compact events need an explicit public workflow slot, never array order. */
+  requireStableSlotIdentity?: boolean;
   stoppedPanelIndices?: readonly number[];
 }
 
@@ -63,20 +67,50 @@ export function extractPanelResults(
 
   const outputs: PanelOutput[] = [];
   const failures: FailedPanelSummary[] = [];
+  const fallbackFailureReason = failureReason(container.payload);
   const results =
     options.limit === undefined
       ? container.results
       : container.results.slice(0, options.limit);
-  for (const [index, rawResult] of results.entries()) {
+  const seenSlots = new Set<number>();
+  for (const [arrayIndex, rawResult] of results.entries()) {
     if (options.completedOnly && !isCompletedResult(rawResult)) continue;
-    const child = normalizeChildResult(rawResult, index, options);
+    const index = workflowSlotIndex(rawResult, arrayIndex, options);
+    if (index === undefined) {
+      return error(
+        "missing-result-field",
+        "Compact subagents result omitted a stable workflow slot identity.",
+        `${container.path}[${arrayIndex}]`,
+      );
+    }
+    if (options.limit !== undefined && index >= options.limit) {
+      return error(
+        "unknown-result-shape",
+        "Subagents result workflow slot is outside the configured panel.",
+        `${container.path}[${arrayIndex}]`,
+      );
+    }
+    if (seenSlots.has(index)) {
+      return error(
+        "unknown-result-shape",
+        "Subagents result repeated a workflow slot identity.",
+        `${container.path}[${arrayIndex}]`,
+      );
+    }
+    seenSlots.add(index);
+    const child = normalizeChildResult(
+      rawResult,
+      index,
+      options,
+      fallbackFailureReason,
+    );
     if (!child.ok) return child;
     if (child.status === "success") outputs.push(child.output);
     else failures.push(child.failure);
   }
 
   for (const index of options.stoppedPanelIndices ?? []) {
-    if (index < results.length || index >= (options.limit ?? Infinity)) continue;
+    if (seenSlots.has(index) || index >= (options.limit ?? Infinity)) continue;
     const child = normalizeChildResult(
       {
         success: false,
@@ -84,12 +118,17 @@ export function extractPanelResults(
       },
       index,
       options,
+      fallbackFailureReason,
     );
     if (!child.ok) return child;
     if (child.status === "failed") failures.push(child.failure);
   }
 
   const runId = firstString(container.payload.runId, container.payload.id);
+  // Stable slot identity also gives consumers configuration order independent
+  // of compact-event ordering.
+  outputs.sort((left, right) => left.index - right.index);
+  failures.sort((left, right) => left.index - right.index);
   return {
     ok: true,
     outputs,
@@ -193,10 +232,36 @@ function findResultsContainer(
   );
 }
 
+function workflowSlotIndex(
+  rawResult: unknown,
+  fallback: number,
+  options: ExtractPanelResultsOptions,
+): number | undefined {
+  if (!options.requireStableSlotIdentity) return fallback;
+  if (!isRecord(rawResult)) return undefined;
+  for (const candidate of [rawResult.index, rawResult.taskIndex, rawResult.stepIndex]) {
+    if (typeof candidate === "number" && Number.isInteger(candidate) && candidate >= 0) {
+      return candidate;
+    }
+  }
+  const key = firstString(
+    rawResult.key,
+    rawResult.taskKey,
+    rawResult.stepKey,
+    rawResult.agent,
+  );
+  // Workflow scripts name their public child slots panel-1, panel-2, etc.
+  // Never infer an omitted compact-event slot from its array position: compact
+  // completion events can be reordered or omit failed children.
+  const match = key?.match(/^panel-([1-9]\d*)$/);
+  return match ? Number(match[1]) - 1 : undefined;
+}
+
 function normalizeChildResult(
   rawResult: unknown,
   index: number,
   options: ExtractPanelResultsOptions,
+  fallbackFailureReason?: FailedPanelSummary["reason"],
 ):
   | { ok: true; status: "success"; output: PanelOutput }
   | { ok: true; status: "failed"; failure: FailedPanelSummary }
@@ -222,7 +287,9 @@ function normalizeChildResult(
 
   const artifactPath = extractArtifactPath(rawResult);
   const sessionPath = firstString(rawResult.sessionPath, rawResult.sessionFile);
-  const status = classifyChildStatus(rawResult);
+  const terminalizedRunning =
+    options.terminalizeRunning === true && !isCompletedResult(rawResult);
+  const status = terminalizedRunning ? "failed" : classifyChildStatus(rawResult);
 
   if (status === "success") {
     const rawOutput = firstNonBlankString(
@@ -274,8 +341,13 @@ function normalizeChildResult(
       agent,
       summary: stoppedAfterAgreement
         ? "Stopped after strong panel agreement."
-        : failureSummary(rawResult, artifactPath),
-      reason: failureReason(rawResult, stoppedAfterAgreement),
+        : terminalizedRunning
+          ? "Panelist did not finish before the workflow deadline."
+          : failureSummary(rawResult, artifactPath),
+      reason:
+        (terminalizedRunning ? "timeout" : undefined) ??
+        failureReason(rawResult, stoppedAfterAgreement) ??
+        fallbackFailureReason,
       observation,
       artifactPath,
       sessionPath,
@@ -392,7 +464,12 @@ function failureReason(
   stoppedAfterAgreement = false,
 ): FailedPanelSummary["reason"] {
   if (stoppedAfterAgreement) return "stopped-after-agreement";
-  if (result.timedOut === true) return "timeout";
+  if (
+    result.timedOut === true ||
+    /(?:timed out|timeout)/i.test(firstNonBlankString(result.error) ?? "")
+  ) {
+    return "timeout";
+  }
   if (result.interrupted === true) return "interrupted";
   return undefined;
 }