@alexeiled/pi-fusion 0.6.2 → 0.8.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`, versioned `outputContract` (`plan-review-v1`), and positive-integer millisecond deadline overrides: `panelistTimeoutMs`, `panelTimeoutMs`, `panelGraceMs`, and `judgeTimeoutMs`. 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`.
@@ -205,12 +207,13 @@ For commands, config, and troubleshooting details, see [`docs/user-guide.md`](./
 - Config is optional. Defaults work. Use `/fusion init` when you want project config.
 - Project config lives at `.pi/fusion.json`. Global config lives at `~/.pi/agent/fusion.json`.
 - Output appears as a Pi custom message. Active progress also uses the `fusion` status key.
-- Active runs are reconciled from `pi-subagents` lifecycle artifacts, not only completion events.
+- Active runs are reconciled from `pi-subagents` lifecycle artifacts, not only completion events. Verified panel outputs survive a panel deadline; unavailable perspectives and timeout failures are disclosed in a partial report when quorum is not met or coverage is incomplete.
+- Timeouts end the current child or workflow attempt. Fusion never automatically retries panelists, restarts a panel, or extends a deadline; start a new run manually after the terminal report.
 - `pi-fusion` does not own the footer.
 - Fusion sends your prompt and any inspected snippets to every panel model, and to the judge, through `pi-subagents`.
 - Reports include available per-panel and judge time, aggregate model time, usage, estimated cost, and model failure details. Missing provider usage is shown as unknown. `$0.0000` is a known zero cost.
 - `Model` is lifecycle metadata. `Configured model` is the profile request. Both appear when the run differs from the request.
-- `stopWhenPanelAgrees` is an opt-in profile setting. It requires matching high-confidence decision records with no request for more evidence, evaluates panelists in pairs so it can avoid starting later work, records skipped panelists in the report, and still runs the judge.
+- `stopWhenPanelAgrees` is an opt-in profile setting. It requires matching high-confidence decision records with no request for more evidence, initially executes only the configured synthesis quorum (not always two) so it can avoid starting later work, records skipped panelists in the report, and still runs the judge.
 - Panel answers reach the judge in an order seeded from the run id, not in config order. A fixed order advantages the same member on every run, because judges favour whichever candidate they see first or last.
 - Panelists can search the web by opting in to the `fusion-panelist-web` agent, which requires `pi-web-providers`. Defaults stay local-only on purpose: tool names are a strict allowlist, so an agent declaring a tool whose extension is missing fails every task that uses it.
 - `synthesis: "merge"` switches from picking the best answer to merging answers that covered different facets, using the `fusion-composer` agent. Panel members get facets through their optional `question` field. See the user guide.

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

@@ -29,7 +29,7 @@ prompts, or both. **Mixing models is the main lever.** The config that
 `/fusion init` writes sets no `model`. By default you therefore get one model in
 three roles. Give each member its own `model` to get the real benefit.
 
-Fusion launches new panels through `pi-subagents` `workflowScript`; the panel and judge remain separate durable runs. Older runs created as a single `pi-subagents` chain remain supported when restored.
+Fusion launches new panels through `pi-subagents` `workflowScript`; the panel and judge remain separate durable runs. At start, Fusion persists a small resolved profile snapshot (panel labels/models/roles, quorum, synthesis and judge settings) and uses it after restart, so later config edits cannot change an active run's reconciliation, report, or synthesis spawn. Older runs created before this snapshot, including single-chain runs, retain the legacy config-lookup restore fallback. Before each public RPC spawn, Fusion persists a spawn intent. If Pi crashes after that RPC might have started but before its remote run ID is saved, restore fails that local run with an explicit recovery warning instead of spawning a possible duplicate (public RPC cannot safely adopt by correlation key). A corrupt newest run snapshot is likewise refused rather than reviving an older active run.
 
 The base Pi session stays in control. Fusion is a tool for decisions, not a replacement for normal coding.
 
@@ -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
     }
@@ -149,13 +152,21 @@ 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
+- `concurrency`: max parallel panelists. When `stopWhenPanelAgrees` is on, Fusion initially executes only the resolved synthesis quorum (capped by `concurrency`) before launching another batch, so a non-default quorum—not always the first two—governs early agreement.
+- `timeoutMs`: legacy shared wall-clock timeout in milliseconds. It is a fallback only; `/fusion status` warns when it supplied an effective deadline.
+- `panelistTimeoutMs`: per-panelist deadline. Fusion caps it below the enclosing panel deadline.
+- `panelTimeoutMs`: panel workflow wall-clock deadline.
+- `panelGraceMs`: reserved time between a child deadline and the enclosing panel deadline (default 5 seconds).
+- `judgeTimeoutMs`: synthesis workflow deadline. For every deadline the precedence is per-run CLI/tool/RPC override, stage profile field, legacy `timeoutMs`, then the built-in default.
+- `minimumSuccessfulPanelists`: `"majority"` (default), `"all"`, or a positive number. It is the panel quorum for synthesis. For a multi-member panel, numeric `1` is effectively `2`: synthesis needs two candidate answers. A one-member panel remains a direct single-panel result.
 - `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.
+- `stopWhenPanelAgrees`: optional boolean, default `false`. When it is on, Fusion can stop the panelists that have not finished yet only after the configured synthesis quorum is already met. The agreement conditions also require two or more finished panelists to give the same normalized recommendation, every one to report `high` confidence, none to ask for more evidence, and work to remain. Thus an `"all"` quorum never skips unfinished panelists. 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 durably keeps verified completed slots, turns terminal running/interrupted slots into typed failures, and fails closed when lifecycle sources genuinely disagree. A timed-out judge never becomes a panel-only success. When at least one valid panel result exists, Fusion produces either synthesis at quorum or an explicitly unsynthesized partial report below quorum; failures and timeouts are disclosed as missing coverage. Only zero successful outputs fail outright. Fusion never automatically retries a failed panelist, restarts a panel, or extends a deadline.
 
 Panel member:
 
@@ -286,9 +297,7 @@ run does not fail, so a mismatch appears as an empty report, not as an error.
 }
 ```
 
-Under `merge`, one surviving panelist still goes to the composer. Fusion does
-not return that answer directly. One facet is not the answer, and the report must
-name what is missing.
+Under `merge`, surviving outputs at quorum go to the composer even when some facets are unavailable. The composer must name uncovered facets rather than presenting complete coverage. Below quorum Fusion posts an explicitly partial coverage report; it never presents one facet as the full answer.
 
 Judge:
 
@@ -357,7 +366,8 @@ Deliberate review:
         "thinking": "high"
       },
       "concurrency": 2,
-      "timeoutMs": 300000,
+      "panelTimeoutMs": 900000,
+      "judgeTimeoutMs": 900000,
       "context": "fresh"
     }
   }
@@ -368,6 +378,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 +479,15 @@ 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
+- a timeout ends that child/run attempt; Fusion does not retry panelists, restart the panel, or extend deadlines
+- failed-only retry is deliberately not exposed yet: terminal failure state persists the failed panel slot indices for recovery/provenance, but `/fusion` starts a new independent run rather than replaying only those slots
+- retry manually only after the run is terminal
+
 Run is stuck or no longer useful:
 
 ```text
@@ -483,4 +504,4 @@ Notes:
 
 - `Panel run` is the normal panel phase for new Fusion runs.
 - `Judge run` is the normal synthesis phase for new runs. `Fallback judge run` appears only while restoring a legacy chain that completed without its judge result.
-- If `pi-subagents` completion notifications are delayed or missed, Fusion still reconciles from lifecycle artifacts written under the subagent async run directory.
+- If `pi-subagents` completion notifications are delayed or missed, Fusion still reconciles from lifecycle artifacts written under the subagent async run directory. The full result artifact is preferred over compact completion events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.6.2",
+  "version": "0.8.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/skills/fusion-review/SKILL.md

@@ -76,10 +76,11 @@ better.
 ## After the call
 
 The tool returns at once. The panel and the synthesis step run in the background,
-and Fusion posts the report when they finish.
+and Fusion posts the report when they finish. A panel deadline can produce an explicitly partial report that names unavailable perspectives and timeout coverage gaps.
 
 - Do not call the tool again while a run is active. It returns a conflict with
   the id of the active run.
 - Do not summarize or predict the report. Wait for it.
 - To show progress or stop a run, tell the user to type `/fusion status` or
   `/fusion stop`. No tool does this.
+- Do not invoke another review automatically after a partial report or timeout. Fusion does not retry failed panelists; users can inspect `/fusion status` and manually rerun only after the current run is terminal.

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,44 @@ function isFusionProfile(value: unknown): value is FusionProfile {
     return false;
   if (value.timeoutMs !== undefined && !isPositiveInteger(value.timeoutMs))
     return false;
+  if (
+    value.panelistTimeoutMs !== undefined &&
+    !isPositiveInteger(value.panelistTimeoutMs)
+  ) {
+    return false;
+  }
+  if (
+    value.panelTimeoutMs !== undefined &&
+    !isPositiveInteger(value.panelTimeoutMs)
+  ) {
+    return false;
+  }
+  if (
+    value.panelGraceMs !== undefined &&
+    !isPositiveInteger(value.panelGraceMs)
+  ) {
+    return false;
+  }
+  const panelTimeoutMs = value.panelTimeoutMs ?? value.timeoutMs ?? 900_000;
+  const panelGraceMs = value.panelGraceMs ?? 5_000;
+  // Never accept a configuration that would leave child panelists a 1ms
+  // timeout after deadline capping. Overrides receive the same validation when
+  // their effective values are resolved at run start.
+  if (panelGraceMs >= panelTimeoutMs) return false;
+  if (
+    value.judgeTimeoutMs !== undefined &&
+    !isPositiveInteger(value.judgeTimeoutMs)
+  ) {
+    return false;
+  }
+  if (
+    value.minimumSuccessfulPanelists !== undefined &&
+    value.minimumSuccessfulPanelists !== "majority" &&
+    value.minimumSuccessfulPanelists !== "all" &&
+    !isPositiveInteger(value.minimumSuccessfulPanelists)
+  ) {
+    return false;
+  }
   if (value.context !== undefined && !isFusionContextMode(value.context))
     return false;
   if (
@@ -336,6 +377,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 +401,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 +411,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-args.ts

@@ -1,8 +1,8 @@
 import { FusionArgsError } from "./errors.js";
-import type { ParsedFusionArgs } from "./types.js";
+import type { FusionTimeoutOverrides, ParsedFusionArgs } from "./types.js";
 
 const FUSION_USAGE =
-  "Usage: /fusion <prompt> | /fusion --profile <name> <prompt> | /fusion --panel <models> <prompt> | /fusion status | /fusion stop | /fusion init.";
+  "Usage: /fusion <prompt> | /fusion --profile <name> <prompt> | /fusion --panel <models> <prompt> [--panelist-timeout-ms n --panel-timeout-ms n --panel-grace-ms n --judge-timeout-ms n] | /fusion status | /fusion stop | /fusion init.";
 
 export type FusionInlineCommand = "init" | "status" | "stop";
 
@@ -28,6 +28,13 @@ export function parseFusionArgs(
 
   let profile: string | undefined;
   let panel: string[] | undefined;
+  const timeoutOverrides: FusionTimeoutOverrides = {};
+  const timeoutOptions: Record<string, keyof FusionTimeoutOverrides> = {
+    "--panelist-timeout-ms": "panelistTimeoutMs",
+    "--panel-timeout-ms": "panelTimeoutMs",
+    "--panel-grace-ms": "panelGraceMs",
+    "--judge-timeout-ms": "judgeTimeoutMs",
+  };
   const promptTokens: string[] = [];
 
   for (let index = 0; index < tokens.length; index++) {
@@ -81,6 +88,25 @@ export function parseFusionArgs(
       continue;
     }
 
+    const timeoutKey = timeoutOptions[token];
+    const timeoutEquals = Object.entries(timeoutOptions).find(([option]) =>
+      token.startsWith(`${option}=`),
+    );
+    if (promptTokens.length === 0 && (timeoutKey || timeoutEquals)) {
+      const key = timeoutKey ?? timeoutEquals?.[1];
+      const raw = timeoutKey ? tokens[index + 1] : token.slice((timeoutEquals?.[0].length ?? 0) + 1);
+      const value = raw ? Number(raw) : NaN;
+      if (!key || !Number.isInteger(value) || value <= 0) {
+        throw new FusionArgsError(`Timeout options require a positive integer milliseconds value. ${FUSION_USAGE}`);
+      }
+      if (timeoutOverrides[key] !== undefined) {
+        throw new FusionArgsError(`${token.split("=")[0]} can only be provided once.`);
+      }
+      timeoutOverrides[key] = value;
+      if (timeoutKey) index++;
+      continue;
+    }
+
     if (promptTokens.length === 0 && token.startsWith("-")) {
       throw new FusionArgsError(`Unknown option ${token}. ${FUSION_USAGE}`);
     }
@@ -95,6 +121,7 @@ export function parseFusionArgs(
     prompt,
     ...(profile ? { profile } : {}),
     ...(panel ? { panel } : {}),
+    ...(Object.keys(timeoutOverrides).length ? { timeoutOverrides } : {}),
   };
 }
 

package/src/fusion-rpc.ts

@@ -1,9 +1,20 @@
+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,
+  FusionTimeoutOverrides,
+  ParsedFusionArgs,
+} from "./types.js";
 import { isNonEmptyString, isRecord } from "./utils.js";
 
 export const FUSION_RPC_VERSION = 1;
@@ -70,8 +81,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 +151,8 @@ interface StartParams {
   prompt: string;
   profile?: string;
   operationId: string;
+  outputContract?: CallerOutputContract;
+  timeoutOverrides?: FusionTimeoutOverrides;
 }
 
 interface RunParams {
@@ -143,7 +162,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 +277,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 +427,57 @@ function parseStartParams(input: unknown): StartParams {
     );
   }
 
-  return profile === undefined
-    ? { prompt, operationId }
-    : { prompt, operationId, profile };
+  const timeoutOverrides = parseTimeoutOverrides(input);
+
+  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 }),
+    ...(timeoutOverrides ? { timeoutOverrides } : {}),
+  };
+}
+
+function parseTimeoutOverrides(
+  input: Record<string, unknown>,
+): FusionTimeoutOverrides | undefined {
+  const fields = [
+    ["panelistTimeoutMs", "panelistTimeoutMs"],
+    ["panelTimeoutMs", "panelTimeoutMs"],
+    ["panelGraceMs", "panelGraceMs"],
+    ["judgeTimeoutMs", "judgeTimeoutMs"],
+  ] as const;
+  const overrides: FusionTimeoutOverrides = {};
+  for (const [wireName, key] of fields) {
+    const value = input[wireName];
+    if (value === undefined) continue;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+      throw invalidParams(`${wireName} must be a positive integer when provided.`);
+    }
+    overrides[key] = value;
+  }
+  return Object.keys(overrides).length ? overrides : undefined;
 }
 
 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 }),
+    ...(input.timeoutOverrides === undefined
+      ? {}
+      : { timeoutOverrides: input.timeoutOverrides }),
+  };
 }
 
 function findRun(
@@ -548,6 +612,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/index.ts

@@ -25,23 +25,45 @@ function registerFusionTool(
       "Pass panel only when the user names the models to compare. Otherwise omit it and let the profile decide.",
     ],
     parameters: Type.Object({
-      prompt: Type.String({ description: "What to review or discuss" }),
+      prompt: Type.String({
+        minLength: 1,
+        pattern: ".*\\S.*",
+        description: "What to review or discuss (must contain non-whitespace text)",
+      }),
       profile: Type.Optional(
-        Type.String({ description: "Fusion profile name (optional)" }),
+        Type.String({ minLength: 1, description: "Fusion profile name (optional)" }),
       ),
       panel: Type.Optional(
-        Type.Array(Type.String(), {
+        Type.Array(Type.String({ minLength: 1 }), {
+          minItems: 1,
           description:
             "Models to use for this run, overriding the profile panel. Each entry is <model> or <agent>:<model>. Use only when the user names specific models.",
         }),
       ),
+      panelistTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Per-panelist deadline in milliseconds" })),
+      panelTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Panel workflow deadline in milliseconds" })),
+      panelGraceMs: Type.Optional(Type.Integer({ minimum: 1, description: "Reserved grace between child and panel deadlines in milliseconds" })),
+      judgeTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Judge/composer deadline in milliseconds" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = await orchestrator.startRun(
         {
           prompt: params.prompt,
-          ...(params.profile ? { profile: params.profile } : {}),
-          ...(params.panel?.length ? { panel: params.panel } : {}),
+          ...(params.profile !== undefined ? { profile: params.profile } : {}),
+          ...(params.panel !== undefined ? { panel: params.panel } : {}),
+          ...(params.panelistTimeoutMs !== undefined ||
+          params.panelTimeoutMs !== undefined ||
+          params.panelGraceMs !== undefined ||
+          params.judgeTimeoutMs !== undefined
+            ? {
+                timeoutOverrides: {
+                  ...(params.panelistTimeoutMs !== undefined ? { panelistTimeoutMs: params.panelistTimeoutMs } : {}),
+                  ...(params.panelTimeoutMs !== undefined ? { panelTimeoutMs: params.panelTimeoutMs } : {}),
+                  ...(params.panelGraceMs !== undefined ? { panelGraceMs: params.panelGraceMs } : {}),
+                  ...(params.judgeTimeoutMs !== undefined ? { judgeTimeoutMs: params.judgeTimeoutMs } : {}),
+                },
+              }
+            : {}),
         },
         ctx,
       );
@@ -57,6 +79,12 @@ function registerFusionTool(
           prompt: params.prompt,
           profile: params.profile,
           panel: params.panel,
+          timeoutOverrides: {
+            panelistTimeoutMs: params.panelistTimeoutMs,
+            panelTimeoutMs: params.panelTimeoutMs,
+            panelGraceMs: params.panelGraceMs,
+            judgeTimeoutMs: params.judgeTimeoutMs,
+          },
           status: result.status,
         },
       };