@alexeiled/pi-fusion 0.7.0 → 0.9.0

package/src/panel-completion.ts

@@ -5,6 +5,7 @@ import {
 import {
   renderFailureReport,
   renderPanelFailureReport,
+  renderPartialPanelReport,
   renderSinglePanelReport,
 } from "./report.js";
 import {
@@ -12,6 +13,7 @@ import {
   buildJudgeSpawnParams,
   type JudgeSpawnParams,
 } from "./run-builder.js";
+import { resolveMinimumSuccessfulPanelists } from "./panel-quorum.js";
 import {
   resolveSynthesisMode,
   type FailedPanelSummary,
@@ -20,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 }
@@ -65,24 +69,19 @@ export function decidePanelCompletion(
     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 < input.profile.panel.length &&
-    !intentionalStops
+    synthesis !== "merge" &&
+    input.profile.panel.length === 1 &&
+    input.panelOutputs.length === 1
   ) {
-    const error = `Only ${input.panelOutputs.length} of ${input.profile.panel.length} fusion panelists completed successfully; ${input.panelFailures.length} panelist result(s) are also missing.`;
-    const report = renderFailureReport({
-      run: input.run,
-      error,
-      panelOutputs: input.panelOutputs,
-      failures: input.panelFailures,
-      ...withJudgeModel(judgeModel),
-      synthesis: resolveSynthesisMode(input.profile),
-      panel: input.profile.panel,
-    });
-    return { kind: "fail", error, report };
-  }
-
-  if (input.panelOutputs.length === 1) {
     const callerContract =
       input.run.outputContract ??
       detectCallerOutputContract(input.run.prompt);
@@ -98,7 +97,7 @@ export function decidePanelCompletion(
           panelOutputs: input.panelOutputs,
           failures: input.panelFailures,
           ...withJudgeModel(judgeModel),
-          synthesis: resolveSynthesisMode(input.profile),
+          synthesis,
           panel: input.profile.panel,
         });
         return { kind: "fail", error: validation.error, report };
@@ -114,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({
@@ -125,6 +167,12 @@ export function decidePanelCompletion(
       ...(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-deadlines.ts

@@ -0,0 +1,90 @@
+import type { FusionRun, PanelDeadlineState } from "./types.js";
+import { isRecord } from "./utils.js";
+
+export const PANEL_FINALIZE_RESERVE_MS = 60_000;
+export const PANEL_DECISION_WAIT_MS = 60_000;
+
+export interface PanelDeadlineAction {
+  state: PanelDeadlineState;
+  kind: "ask" | "finish";
+}
+
+/** Plan controls only for unambiguous, live children of the current panel. */
+export function planPanelDeadlines(
+  run: FusionRun,
+  steps: readonly unknown[],
+  now: number,
+): PanelDeadlineAction[] {
+  const timeouts = run.effectiveTimeouts;
+  if (!timeouts?.panelistSoftTimeoutMs || !run.profileSnapshot) return [];
+  const candidates = steps.flatMap((step) => {
+    if (!isRecord(step) || (step.status ?? step.state) !== "running") return [];
+    const key = step.workflowKey ?? step.key ?? step.agent;
+    const match =
+      typeof key === "string" ? key.match(/^panel-([1-9]\d*)$/) : undefined;
+    const index = match ? Number(match[1]) - 1 : undefined;
+    if (
+      index === undefined ||
+      index >= run.profileSnapshot!.panel.length ||
+      typeof step.runId !== "string" ||
+      !step.runId.trim() ||
+      typeof step.startedAt !== "number" ||
+      !Number.isFinite(step.startedAt)
+    )
+      return [];
+    return [{ index, childRunId: step.runId, startedAt: step.startedAt }];
+  });
+  const actions: PanelDeadlineAction[] = [];
+  for (const child of candidates) {
+    if (
+      candidates.filter(
+        (item) =>
+          item.index === child.index || item.childRunId === child.childRunId,
+      ).length !== 1
+    )
+      continue;
+    const previous = run.panelDeadlines?.find(
+      (item) => item.index === child.index,
+    );
+    // A different run ID in the same slot is not authority to control it.
+    if (previous && previous.childRunId !== child.childRunId) continue;
+    const hardDeadlineAt = child.startedAt + timeouts.panelistTimeoutMs;
+    if (now >= hardDeadlineAt || previous?.status === "finishing") continue;
+    const finalizeAt = hardDeadlineAt - PANEL_FINALIZE_RESERVE_MS;
+    if (previous) {
+      const finishAt =
+        previous.status === "pending"
+          ? Math.min(previous.requestedAt + PANEL_DECISION_WAIT_MS, finalizeAt)
+          : finalizeAt;
+      if (now >= finishAt)
+        actions.push({
+          kind: "finish",
+          state: { ...previous, status: "finishing" },
+        });
+    } else if (now >= child.startedAt + timeouts.panelistSoftTimeoutMs) {
+      const finishing = now >= finalizeAt;
+      actions.push({
+        kind: finishing ? "finish" : "ask",
+        state: {
+          index: child.index,
+          childRunId: child.childRunId,
+          requestedAt: now,
+          finalizeAt,
+          hardDeadlineAt,
+          status: finishing ? "finishing" : "pending",
+        },
+      });
+    }
+  }
+  return actions;
+}
+
+export function deadlineSteerMessage(state: PanelDeadlineState): string {
+  if (state.status === "finishing") {
+    return "Fusion time budget: stop new investigation and return your best current answer now in the original output contract. State unfinished checks and uncertainty. Do not restart or wait for another decision. The hard deadline is unchanged.";
+  }
+  if (state.status === "continued") {
+    return `Fusion continuation approved within the existing budget. Finish investigation by ${new Date(state.finalizeAt).toISOString()} and return the answer. The hard deadline is unchanged; there will be no further extension.`;
+  }
+  return "Fusion soft deadline reached. At the next safe point, send a short progress_update through contact_supervisor if available: findings so far, unfinished checks, and time needed. Do not block waiting in a supervisor tool. Finish the current check while the parent decides whether to continue; do not expand scope. If no decision arrives, Fusion will ask you to finalize shortly. Keep the original final-output contract.";
+}

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

@@ -28,6 +28,9 @@ type ReportRun = Pick<
   | "judgeRunId"
   | "panelStopReason"
   | "outputContract"
+  | "completionQuality"
+  | "minimumSuccessfulPanelists"
+  | "effectiveTimeouts"
 > &
   Partial<Pick<FusionRun, "phase" | "createdAt" | "updatedAt">>;
 
@@ -48,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;
@@ -123,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)`;
@@ -331,6 +348,62 @@ 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 ?? [];
@@ -402,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",
@@ -412,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,
@@ -421,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

@@ -10,7 +10,7 @@ import {
 import type { PanelMemberConfig } from "./types.js";
 
 export type ResultExtractErrorCode =
-  "missing-results" | "unknown-result-shape" | "missing-result-field";
+  "missing-results" | "unknown-result-shape" | "missing-result-field" | "incomplete-lifecycle";
 
 export interface ResultExtractError {
   code: ResultExtractErrorCode;
@@ -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[];
 }
 
@@ -68,8 +72,32 @@ export function extractPanelResults(
     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 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,
@@ -82,7 +110,7 @@ export function extractPanelResults(
   }
 
   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,
@@ -97,6 +125,10 @@ export function extractPanelResults(
   }
 
   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,
@@ -200,6 +232,31 @@ 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,
@@ -230,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(
@@ -282,8 +341,11 @@ function normalizeChildResult(
       agent,
       summary: stoppedAfterAgreement
         ? "Stopped after strong panel agreement."
-        : failureSummary(rawResult, artifactPath),
+        : terminalizedRunning
+          ? "Panelist did not finish before the workflow deadline."
+          : failureSummary(rawResult, artifactPath),
       reason:
+        (terminalizedRunning ? "timeout" : undefined) ??
         failureReason(rawResult, stoppedAfterAgreement) ??
         fallbackFailureReason,
       observation,