@alexeiled/pi-fusion 0.6.2 → 0.7.0

package/README.md

@@ -156,16 +156,18 @@ Other Pi extensions can control Fusion through the versioned event-bus contract
 Methods:
 
 - `ping` — return the RPC version and supported methods
-- `start` — requires `prompt` and a non-empty `operationId`. It accepts an optional `profile`. Reusing an operation ID returns the original run instead of starting another, including after Fusion restores the Pi session history.
+- `start` — requires `prompt` and a non-empty `operationId`. It accepts optional `profile` and versioned `outputContract` (`plan-review-v1`). Reusing an operation ID returns the original run instead of starting another, including after Fusion restores the Pi session history.
 - `status` — return structured run state by `operationId`, `runId`, or the current/last run
 - `result` — return a terminal run and report. An active run returns `not_ready`
 - `cancel` — cancel the selected active run, or report that the selected terminal run was not cancelled
 - `adopt` — verify and return a run from restored session history by `runId`
 
-`start` returns `{ operationId, replayed, run }`. `status` and `result`
-return `{ run }`. `cancel` returns `{ cancelled, run? }`. `adopt` returns
-`{ adopted: true, run }`. Run state contains `runId`, optional `operationId`,
-`phase`, `terminal`, and optional `report` or `error`.
+`start` returns `{ operationId, replayed, run }`. `status` returns `{ run }`.
+`result` returns `{ run, callerOutput? }`; `callerOutput` is present only when
+Fusion validated a strict caller contract, and contains `{ contract, output }`.
+`cancel` returns `{ cancelled, run? }`. `adopt` returns `{ adopted: true, run }`.
+Run state contains `runId`, optional `operationId`, `phase`, `terminal`, and
+optional `report` or `error`.
 
 Failure codes are `invalid_request`, `unsupported_method`, `busy`, `not_found`,
 `not_ready`, `unavailable`, `start_failed`, `cancel_failed`, and `internal`.

package/agents/fusion-composer.md

@@ -28,6 +28,9 @@ a winner.
 Read-only synthesis. Do not edit files. Do not ask other agents. Do not run
 subagents.
 
+If the task defines an exact caller output contract, follow it instead of the
+sections below. Return only the caller's required syntax.
+
 Return final Markdown with these sections:
 
 # Fusion Report

package/agents/fusion-judge.md

@@ -20,6 +20,9 @@ yourself rather than choosing the more confident wording. You have read tools;
 a factual conflict is settled by looking, not by weighing prose. Cite `file:line`
 for what you find, and say plainly when a claim could not be verified.
 
+If the task defines an exact caller output contract, follow it instead of the
+sections below. Return only the caller's required syntax.
+
 Return final Markdown with these sections:
 
 # Fusion Report

package/agents/fusion-panelist.md

@@ -17,6 +17,9 @@ You have no web access: answer from the repository and your own knowledge, and s
 so plainly when a question turns on external facts you cannot retrieve.
 Do not edit files. Do not ask other agents. Do not run subagents.
 
+If the task defines an exact caller output contract, follow it instead of the
+sections and decision record below. Return only the caller's required syntax.
+
 Return concise Markdown with these sections.
 
 When the task includes a decision-record contract:

package/docs/user-guide.md

@@ -130,7 +130,10 @@ Run this inside a trusted project:
         "agent": "pi-fusion.fusion-judge"
       },
       "concurrency": 3,
-      "timeoutMs": 300000,
+      "panelTimeoutMs": 900000,
+      "judgeTimeoutMs": 900000,
+      "panelToolBudget": { "soft": 8, "hard": 12, "block": "*" },
+      "judgeToolBudget": { "soft": 8, "hard": 12, "block": "*" },
       "context": "fresh",
       "stopWhenPanelAgrees": false
     }
@@ -150,12 +153,17 @@ Profile:
 - `panel`: one or more panel members
 - `judge`: judge agent config
 - `concurrency`: max parallel panelists. When `stopWhenPanelAgrees` is on, Fusion evaluates the first two panelists before launching another batch so it can avoid work after strong agreement.
-- `timeoutMs`: async subagent timeout in milliseconds
+- `timeoutMs`: legacy shared wall-clock timeout in milliseconds. It remains supported as the fallback for both stages. New profiles default to 15 minutes through the stage-specific fields; existing explicit `timeoutMs` values are preserved. Use a stage-specific field when panel and synthesis need different deadlines.
+- `panelTimeoutMs`: panel workflow wall-clock timeout. It overrides `timeoutMs` for the panel. The default profile uses 15 minutes.
+- `judgeTimeoutMs`: synthesis workflow wall-clock timeout. It overrides `timeoutMs` for the judge or composer. The default profile uses 15 minutes.
 - `context`: `fresh` or `fork`
 - `stopWhenPanelAgrees`: optional boolean, default `false`. When it is on, Fusion can stop the panelists that have not finished yet. All four conditions must hold: two or more finished panelists give the same normalized recommendation, every one of them reports `high` confidence, none of them asks for more evidence, and work remains. The judge still runs over the answers already collected. This policy is fixed on purpose. There is no threshold to tune.
 - `synthesis`: rarely needed. Inferred from the panel — any member with a `question` means `merge`, otherwise `select`. Set it only to override that. See [Synthesis modes](#synthesis-modes).
 - `blindPanelLabels`: optional boolean, default `false`. When it is on, the judge sees `Candidate A`, `Candidate B`, and so on, instead of the configured labels. Fusion also withholds agent names and artifact paths, because they contain the member id. A role label reads as an authority cue before the judge compares any content. Your report always shows the real names.
-- `judgeToolBudget`: optional `{ "soft": n, "hard": n }`. It caps the tool calls the judge can spend to verify contested claims. `soft` is a nudge. After `hard`, Fusion blocks further tool use, so the judge still produces a report. Both numbers must be positive integers, and `soft` must not be larger than `hard`.
+- `panelToolBudget`: optional `{ "soft": n, "hard": n, "block": "*" | [tools...] }` applied to each panelist. Fusion uses `{ "soft": 8, "hard": 12, "block": "*" }` when omitted. After `hard`, the selected tools are blocked so the panelist can still finalise.
+- `judgeToolBudget`: optional `{ "soft": n, "hard": n, "block": "*" | [tools...] }` for the judge or composer. Fusion uses `{ "soft": 8, "hard": 12, "block": "*" }` when omitted. `soft` is a nudge. After `hard`, the selected tools are blocked so synthesis can still finalise. `soft` or `hard` must be positive integers when present, and `soft` must not be larger than `hard` when both are present. Legacy soft-only budgets remain valid.
+
+Timeouts are hard workflow deadlines. A child terminated at the deadline can report exit 143. Fusion keeps completed panel slots and failed panel slots separate, never relabels a compact completion payload, and fails closed when lifecycle sources disagree. A timed-out judge never becomes a panel-only success. Synthesis also fails closed when any configured panelist is missing or failed, unless the missing slots were explicitly stopped after strong agreement.
 
 Panel member:
 
@@ -357,7 +365,8 @@ Deliberate review:
         "thinking": "high"
       },
       "concurrency": 2,
-      "timeoutMs": 300000,
+      "panelTimeoutMs": 900000,
+      "judgeTimeoutMs": 900000,
       "context": "fresh"
     }
   }
@@ -368,6 +377,8 @@ Deliberate review:
 
 When agreement stopping is on, each panelist appends one tagged JSON decision record. The record holds a short recommendation, a confidence level, and whether the panelist needs more evidence. Fusion uses it only to decide whether an unfinished panel can stop early. A record that is malformed, missing, or not final turns early stopping off. You see the Markdown answer above the record, not the record itself.
 
+An original task can define the strict plan-review contract: exactly `NO_FINDINGS`, or complete `FINDING`/`Evidence`/`Fix` blocks with no other prose. That caller contract overrides Fusion's normal report headings and agreement record. Fusion validates the synthesis, returns it unchanged, and fails rather than fabricating a clean result when the judge violates the contract. RPC `result` also exposes a validated value as `callerOutput`.
+
 The judge returns:
 
 - summary
@@ -467,6 +478,13 @@ For an economical mixed panel, give each member a fast or inexpensive frontier,
 - verify the requested `--profile` name
 - run `/fusion init` to regenerate a known-good template
 
+`Workflow script timed out` or judge exit 143
+
+- raise `panelTimeoutMs` or `judgeTimeoutMs` for slower models
+- keep `panelToolBudget` and `judgeToolBudget` bounded so agents finalise before the deadline
+- inspect `/fusion status`; panel failures and the workflow timeout must both be present
+- retry only after the run is terminal
+
 Run is stuck or no longer useful:
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Stronger answers for hard Pi questions via a parallel model panel + judge, built on pi-subagents",
   "type": "module",
   "main": "./src/index.ts",

package/src/caller-contract.ts

@@ -0,0 +1,80 @@
+import type { CallerOutputContract } from "./types.js";
+
+export type CallerOutputValidation =
+  | { ok: true }
+  | { ok: false; error: string };
+
+const PLAN_REVIEW_HEADER = /^FINDING:\s*(CRITICAL|MAJOR|MINOR)\s*\|\s*\S.*$/;
+
+export function isCallerOutputContract(
+  value: unknown,
+): value is CallerOutputContract {
+  return value === "plan-review-v1";
+}
+
+export function detectCallerOutputContract(
+  prompt: string,
+): CallerOutputContract | undefined {
+  const hasExactCleanToken = /exact line\s+`?NO_FINDINGS`?/i.test(prompt);
+  const hasFindingContract =
+    /exact format[\s\S]*FINDING:\s*(?:CRITICAL\|MAJOR\|MINOR|CRITICAL|MAJOR|MINOR)/i.test(
+      prompt,
+    );
+  const forbidsProse = /do not write any other prose/i.test(prompt);
+  return hasExactCleanToken && hasFindingContract && forbidsProse
+    ? "plan-review-v1"
+    : undefined;
+}
+
+export function validateCallerOutput(
+  contract: CallerOutputContract,
+  output: string,
+): CallerOutputValidation {
+  switch (contract) {
+    case "plan-review-v1":
+      return validatePlanReviewOutput(output);
+  }
+}
+
+export function callerOutputContractInstructions(
+  contract: CallerOutputContract,
+): readonly string[] {
+  switch (contract) {
+    case "plan-review-v1":
+      return [
+        "The exact output contract in the original task takes priority over Fusion's normal Markdown sections.",
+        "Return only NO_FINDINGS or complete FINDING/Evidence/Fix blocks as requested by the original task.",
+        "Do not add Fusion headings, commentary, or a panel decision record.",
+      ];
+  }
+}
+
+function validatePlanReviewOutput(output: string): CallerOutputValidation {
+  const trimmed = output.trim();
+  if (trimmed === "NO_FINDINGS") return { ok: true };
+
+  const blocks = trimmed.split(/(?=^[ \t]*FINDING:\s)/m);
+  if (
+    blocks.length > 0 &&
+    blocks.every((block) => {
+      const lines = block
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+      return (
+        lines.length === 3 &&
+        PLAN_REVIEW_HEADER.test(lines[0] ?? "") &&
+        /^Evidence:\s*\S.*$/.test(lines[1] ?? "") &&
+        /^Fix:\s*\S.*$/.test(lines[2] ?? "")
+      );
+    })
+  ) {
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    error:
+      "Fusion synthesis violated the exact caller output contract. Expected NO_FINDINGS or complete FINDING/Evidence/Fix blocks with no other prose.",
+  };
+}

package/src/config.ts

@@ -115,7 +115,10 @@ export function createDefaultFusionConfig(): FusionConfig {
           thinking: "high",
         },
         concurrency: 3,
-        timeoutMs: 300_000,
+        panelTimeoutMs: 900_000,
+        judgeTimeoutMs: 900_000,
+        panelToolBudget: { soft: 8, hard: 12, block: "*" },
+        judgeToolBudget: { soft: 8, hard: 12, block: "*" },
         context: "fresh",
         stopWhenPanelAgrees: false,
       },
@@ -322,6 +325,18 @@ function isFusionProfile(value: unknown): value is FusionProfile {
     return false;
   if (value.timeoutMs !== undefined && !isPositiveInteger(value.timeoutMs))
     return false;
+  if (
+    value.panelTimeoutMs !== undefined &&
+    !isPositiveInteger(value.panelTimeoutMs)
+  ) {
+    return false;
+  }
+  if (
+    value.judgeTimeoutMs !== undefined &&
+    !isPositiveInteger(value.judgeTimeoutMs)
+  ) {
+    return false;
+  }
   if (value.context !== undefined && !isFusionContextMode(value.context))
     return false;
   if (
@@ -336,6 +351,12 @@ function isFusionProfile(value: unknown): value is FusionProfile {
   ) {
     return false;
   }
+  if (
+    value.panelToolBudget !== undefined &&
+    !isToolBudget(value.panelToolBudget)
+  ) {
+    return false;
+  }
   if (
     value.judgeToolBudget !== undefined &&
     !isToolBudget(value.judgeToolBudget)
@@ -354,9 +375,9 @@ function isFusionProfile(value: unknown): value is FusionProfile {
 
 function isToolBudget(value: unknown): value is ToolBudget {
   if (!isRecord(value)) return false;
+  if (value.soft === undefined && value.hard === undefined) return false;
   if (value.soft !== undefined && !isPositiveInteger(value.soft)) return false;
   if (value.hard !== undefined && !isPositiveInteger(value.hard)) return false;
-  if (value.soft === undefined && value.hard === undefined) return false;
   if (
     isPositiveInteger(value.soft) &&
     isPositiveInteger(value.hard) &&
@@ -364,6 +385,15 @@ function isToolBudget(value: unknown): value is ToolBudget {
   ) {
     return false;
   }
+  if (
+    value.block !== undefined &&
+    value.block !== "*" &&
+    (!Array.isArray(value.block) ||
+      value.block.length === 0 ||
+      !value.block.every(isNonEmptyString))
+  ) {
+    return false;
+  }
   return true;
 }
 

package/src/fusion-rpc.ts

@@ -1,9 +1,19 @@
+import {
+  detectCallerOutputContract,
+  isCallerOutputContract,
+  validateCallerOutput,
+} from "./caller-contract.js";
 import type {
   FusionCommandContext,
   FusionCommandResult,
 } from "./orchestrator.js";
 import type { FusionRunStore } from "./run-store.js";
-import type { FusionPhase, FusionRun, ParsedFusionArgs } from "./types.js";
+import type {
+  CallerOutputContract,
+  FusionPhase,
+  FusionRun,
+  ParsedFusionArgs,
+} from "./types.js";
 import { isNonEmptyString, isRecord } from "./utils.js";
 
 export const FUSION_RPC_VERSION = 1;
@@ -70,8 +80,14 @@ export interface FusionRpcStatusData {
   run: FusionRunState;
 }
 
+export interface FusionRpcCallerOutput {
+  contract: CallerOutputContract;
+  output: string;
+}
+
 export interface FusionRpcResultData {
   run: FusionRunState;
+  callerOutput?: FusionRpcCallerOutput;
 }
 
 export interface FusionRpcCancelData {
@@ -134,6 +150,7 @@ interface StartParams {
   prompt: string;
   profile?: string;
   operationId: string;
+  outputContract?: CallerOutputContract;
 }
 
 interface RunParams {
@@ -143,7 +160,13 @@ interface RunParams {
 
 type ObservableRun = Pick<
   FusionRun,
-  "id" | "operationId" | "phase" | "report" | "error"
+  | "id"
+  | "operationId"
+  | "phase"
+  | "prompt"
+  | "outputContract"
+  | "report"
+  | "error"
 >;
 
 const TERMINAL_PHASES = new Set<FusionPhase>(["done", "failed", "cancelled"]);
@@ -252,7 +275,8 @@ export function registerFusionRpc({
         details: { run: state },
       });
     }
-    return { run: state };
+    const callerOutput = validatedCallerOutput(run);
+    return { run: state, ...(callerOutput ? { callerOutput } : {}) };
   }
 
   async function cancel(params: unknown): Promise<FusionRpcCancelData> {
@@ -401,19 +425,30 @@ function parseStartParams(input: unknown): StartParams {
     );
   }
 
-  return profile === undefined
-    ? { prompt, operationId }
-    : { prompt, operationId, profile };
+  const outputContract = input.outputContract;
+  if (outputContract !== undefined && !isCallerOutputContract(outputContract)) {
+    throw invalidParams(
+      "start outputContract must be a supported caller output contract.",
+    );
+  }
+
+  return {
+    prompt,
+    operationId,
+    ...(profile === undefined ? {} : { profile }),
+    ...(outputContract === undefined ? {} : { outputContract }),
+  };
 }
 
 function toParsedFusionArgs(input: StartParams): ParsedFusionArgs {
-  return input.profile === undefined
-    ? { prompt: input.prompt, operationId: input.operationId }
-    : {
-        prompt: input.prompt,
-        profile: input.profile,
-        operationId: input.operationId,
-      };
+  return {
+    prompt: input.prompt,
+    operationId: input.operationId,
+    ...(input.profile === undefined ? {} : { profile: input.profile }),
+    ...(input.outputContract === undefined
+      ? {}
+      : { outputContract: input.outputContract }),
+  };
 }
 
 function findRun(
@@ -548,6 +583,17 @@ function startFailure(message: string, run?: ObservableRun): RpcFailure {
   });
 }
 
+function validatedCallerOutput(
+  run: ObservableRun,
+): FusionRpcCallerOutput | undefined {
+  if (!run.report) return undefined;
+  const contract = run.outputContract ?? detectCallerOutputContract(run.prompt);
+  if (!contract || !validateCallerOutput(contract, run.report).ok) {
+    return undefined;
+  }
+  return { contract, output: run.report.trim() };
+}
+
 function stateFor(run: ObservableRun): FusionRunState {
   const state: FusionRunState = {
     runId: run.id,

package/src/lifecycle-reconcile.ts

@@ -0,0 +1,248 @@
+import type { FailedPanelSummary, PanelOutput } from "./types.js";
+import { mergeRunObservations } from "./run-observations.js";
+import {
+  extractPanelResults,
+  type ExtractPanelResultsResult,
+  type ExtractPanelResultsSuccess,
+} from "./result-extract.js";
+import type { FusionProfile } from "./types.js";
+import { isRecord } from "./utils.js";
+
+export function reconcileIndexedLifecycleResult(
+  eventPayload: unknown,
+  statusPayload: unknown,
+  index: number,
+  label: "judge" | "panel",
+): string | undefined {
+  const eventResults = findLifecycleArray(eventPayload, "results");
+  const eventResult = eventResults?.[index];
+  if (!isRecord(eventResult)) return undefined;
+
+  const statusSteps = findLifecycleArray(statusPayload, "steps");
+  const rawStatusResults = findLifecycleArray(statusPayload, "results");
+  const statusResults =
+    statusSteps ?? (rawStatusResults?.length ? rawStatusResults : undefined);
+  const statusResult = statusResults?.[index];
+  if (statusResults && !isRecord(statusResult)) {
+    return `Subagents event includes ${label} result ${index + 1}, but status does not.`;
+  }
+  if (!isRecord(statusResult)) return undefined;
+  if (isFailedLifecycleResult(eventResult) === isFailedLifecycleResult(statusResult)) {
+    return undefined;
+  }
+  return `Subagents event and status disagree about ${label} result ${index + 1}.`;
+}
+
+export interface ReconcilePanelResultsOptions {
+  /** Extra terminal result allowed after the configured panel (the judge). */
+  allowedTrailingResults?: number;
+  /** Indices intentionally absent from status after early agreement. */
+  stoppedPanelIndices?: readonly number[];
+}
+
+/**
+ * Reconciles compact completion events with the richer lifecycle snapshot.
+ * Status is authoritative when it describes every configured panel member.
+ * Incomplete or contradictory lifecycle data fails closed.
+ */
+export function reconcilePanelResults(
+  eventResults: ExtractPanelResultsSuccess,
+  statusPayload: unknown,
+  profile: FusionProfile,
+  resultPayload: unknown,
+  options: ReconcilePanelResultsOptions = {},
+): ExtractPanelResultsResult {
+  const expectedCount = profile.panel.length;
+  const allowedTrailing = options.allowedTrailingResults ?? 0;
+  const rawEvent = findLifecycleArray(resultPayload, "results");
+  if (rawEvent && rawEvent.length > expectedCount + allowedTrailing) {
+    return error(
+      `Terminal subagents data contained ${rawEvent.length} results for ${expectedCount + allowedTrailing} expected workflow steps.`,
+      "$.results",
+    );
+  }
+
+  const rawStatusSteps = findLifecycleArray(statusPayload, "steps");
+  const rawStatusResults = findLifecycleArray(statusPayload, "results");
+  const rawStatus =
+    rawStatusSteps ?? (rawStatusResults?.length ? rawStatusResults : undefined);
+  if (!rawStatus) {
+    if (eventResults.outputs.length + eventResults.failures.length !== expectedCount) {
+      return error(
+        `Terminal subagents data described ${eventResults.outputs.length + eventResults.failures.length} of ${expectedCount} configured panel members.`,
+        "$.results",
+      );
+    }
+    return eventResults;
+  }
+
+  if (rawStatus.length > expectedCount + allowedTrailing) {
+    return error(
+      `Terminal subagents status contained ${rawStatus.length} steps for ${expectedCount + allowedTrailing} expected workflow steps.`,
+      "$.steps",
+    );
+  }
+
+  const statusResults = extractPanelResults(statusPayload, {
+    panel: profile.panel,
+    completedOnly: true,
+    limit: expectedCount,
+    ...(options.stoppedPanelIndices
+      ? { stoppedPanelIndices: options.stoppedPanelIndices }
+      : {}),
+  });
+  if (!statusResults.ok) {
+    return error(
+      `${statusResults.error.message} (${statusResults.error.path})`,
+      statusResults.error.path,
+    );
+  }
+
+  const statusCount =
+    statusResults.outputs.length + statusResults.failures.length;
+  const eventCount =
+    eventResults.outputs.length + eventResults.failures.length;
+  const statusIndices = new Set([
+    ...statusResults.outputs.map(({ index }) => index),
+    ...statusResults.failures.map(({ index }) => index),
+  ]);
+  const stopped = new Set(options.stoppedPanelIndices ?? []);
+  const missingStatusIndices = Array.from(
+    { length: expectedCount },
+    (_, index) => index,
+  ).filter((index) => !statusIndices.has(index));
+
+  if (statusCount === expectedCount) {
+    return preserveAgreementReasons(statusResults, eventResults);
+  }
+
+  const missingWereStopped =
+    eventCount === expectedCount &&
+    missingStatusIndices.length > 0 &&
+    missingStatusIndices.every((index) => stopped.has(index));
+  if (!missingWereStopped) {
+    return error(
+      `Terminal subagents status described ${statusCount} of ${expectedCount} configured panel members.`,
+      "$.steps",
+    );
+  }
+
+  if (eventCount !== expectedCount) {
+    return error(
+      `Terminal subagents data described ${eventCount} of ${expectedCount} configured panel members.`,
+      "$.results",
+    );
+  }
+
+  return mergeObservations(eventResults, statusResults);
+}
+
+function preserveAgreementReasons(
+  status: ExtractPanelResultsSuccess,
+  event: ExtractPanelResultsSuccess,
+): ExtractPanelResultsSuccess {
+  const eventFailures = new Map(
+    event.failures.map((failure) => [failure.index, failure]),
+  );
+  return {
+    ...status,
+    failures: status.failures.map((failure) => {
+      const eventFailure = eventFailures.get(failure.index);
+      return eventFailure?.reason === "stopped-after-agreement"
+        ? { ...failure, reason: eventFailure.reason }
+        : failure;
+    }),
+  };
+}
+
+function mergeObservations(
+  event: ExtractPanelResultsSuccess,
+  status: ExtractPanelResultsSuccess,
+): ExtractPanelResultsSuccess {
+  const observations = new Map<number, PanelOutput["observation"]>();
+  for (const output of status.outputs) {
+    observations.set(output.index, output.observation);
+  }
+  for (const failure of status.failures) {
+    observations.set(failure.index, failure.observation);
+  }
+
+  return {
+    ...event,
+    outputs: event.outputs.map((output) =>
+      withObservation(output, observations.get(output.index)),
+    ),
+    failures: event.failures.map((failure) =>
+      withObservation(failure, observations.get(failure.index)),
+    ),
+  };
+}
+
+function withObservation<T extends PanelOutput | FailedPanelSummary>(
+  item: T,
+  statusObservation: PanelOutput["observation"] | undefined,
+): T {
+  const observation = mergeRunObservations(statusObservation, item.observation);
+  return hasObservationData(observation) ? { ...item, observation } : item;
+}
+
+function hasObservationData(
+  observation: PanelOutput["observation"] | undefined,
+): boolean {
+  return Boolean(
+    observation &&
+      (observation.model ||
+        observation.durationMs !== undefined ||
+        observation.usage ||
+        observation.attempts ||
+        observation.providerFailures),
+  );
+}
+
+function findLifecycleArray(
+  payload: unknown,
+  key: "results" | "steps",
+): readonly unknown[] | undefined {
+  if (!isRecord(payload)) return undefined;
+  const direct = unknownArray(payload[key]);
+  if (direct) return direct;
+  if (isRecord(payload.details)) {
+    const nested = unknownArray(payload.details[key]);
+    if (nested) return nested;
+  }
+  if (isRecord(payload.data)) return findLifecycleArray(payload.data, key);
+  return undefined;
+}
+
+function isFailedLifecycleResult(result: Record<string, unknown>): boolean {
+  if (result.success === false) return true;
+  if (result.timedOut === true || result.interrupted === true) return true;
+  if (typeof result.error === "string" && result.error.trim()) return true;
+  const status = firstString(result.status, result.state);
+  return status === "failed" || status === "paused" || status === "detached";
+}
+
+function firstString(...values: readonly unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string") return value;
+  }
+  return undefined;
+}
+
+function unknownArray(value: unknown): readonly unknown[] | undefined {
+  return Array.isArray(value) ? value : undefined;
+}
+
+function error(
+  message: string,
+  path: string,
+): ExtractPanelResultsResult {
+  return {
+    ok: false,
+    error: {
+      code: "unknown-result-shape",
+      message,
+      path,
+    },
+  };
+}