@alexeiled/pi-fusion 0.2.0 → 0.2.2

package/README.md

@@ -1,75 +1,121 @@
 # pi-fusion
 
-[![npm](https://img.shields.io/badge/npm-%40alexeiled%2Fpi--fusion-cb3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@alexeiled/pi-fusion)
+[![npm version](https://img.shields.io/npm/v/%40alexeiled%2Fpi-fusion?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@alexeiled/pi-fusion)
+[![CI](https://img.shields.io/github/actions/workflow/status/alexei-led/pi-fusion/test.yml?branch=master&style=flat-square&label=ci)](https://github.com/alexei-led/pi-fusion/actions/workflows/test.yml?query=branch%3Amaster)
 [![node](https://img.shields.io/badge/node-%3E%3D22.19.0-5fa04e?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
 [![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
 
-> Parallel panel. One judge. One report.
+> Parallel models. One judge. Better answers.
 
-`pi-fusion` is a Pi extension for questions that need deliberation, not a guess.
-It runs a small panel of read-only subagents in parallel, then asks a judge agent
-to synthesize one final Markdown report.
+`pi-fusion` is a Pi extension for hard technical questions.
+It uses `pi-subagents` to send the same prompt through a small parallel model panel,
+then asks a judge agent to compare the outputs and return the best realistic answer.
 
-## Fusion model
+CI covers lint, typecheck, unit tests, integration tests, package smoke tests,
+and `npm pack --dry-run`.
 
-My approach is simple:
+![pi-fusion flow](https://raw.githubusercontent.com/alexei-led/pi-fusion/master/docs/assets/fusion-flow.png)
 
-- one hard question becomes a short review panel
-- panelists work independently in parallel
-- the judge reconciles evidence, not votes
-- if the judge result is missing but the panel still produced enough signal,
-  Fusion retries only the judge step
+## Why Fusion exists
 
-This is evidence-first, not majority vote.
-The judge is a synthesizer, not a tie-breaker by headcount.
+Hard questions are often bottlenecked by one model's search path.
+`pi-fusion` trades latency for diversity:
+
+- the same prompt fans out to several model runs in parallel
+- each model explores the problem from a different training prior and reasoning path
+- overlap raises confidence
+- disagreement exposes risk
+- the judge keeps the strongest parts and drops weak, partial, or conflicting ones
+
+This is evidence selection, not majority vote.
 
 ```mermaid
+%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 28, "rankSpacing": 48}, "themeVariables": {"background": "#050816", "fontFamily": "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace", "primaryTextColor": "#E5F0FF", "lineColor": "#38bdf8", "tertiaryColor": "#0b1220"}}}%%
 flowchart LR
-  classDef input fill:#f8fafc,stroke:#94a3b8,color:#0f172a,stroke-width:1px;
-  classDef panel fill:#e0f2fe,stroke:#38bdf8,color:#0f172a,stroke-width:1px;
-  classDef judge fill:#fef3c7,stroke:#f59e0b,color:#0f172a,stroke-width:1px;
-  classDef report fill:#dcfce7,stroke:#22c55e,color:#0f172a,stroke-width:1px;
-  classDef fallback fill:#fae8ff,stroke:#c084fc,color:#0f172a,stroke-width:1px,stroke-dasharray:4 3;
-
-  U[You in Pi]:::input --> Q[/fusion prompt/]:::input
-
-  subgraph P[Parallel panel]
-    direction LR
-    A[Architect]:::panel
-    I[Implementer]:::panel
-    T[Tester]:::panel
+  classDef prompt fill:#071321,stroke:#38bdf8,color:#dbeafe,stroke-width:2px;
+  classDef modelA fill:#081223,stroke:#38bdf8,color:#dbeafe,stroke-width:2px;
+  classDef modelB fill:#120826,stroke:#a855f7,color:#f3e8ff,stroke-width:2px;
+  classDef modelC fill:#08180f,stroke:#22c55e,color:#dcfce7,stroke-width:2px;
+  classDef modelD fill:#241307,stroke:#f59e0b,color:#fef3c7,stroke-width:2px;
+  classDef modelE fill:#260712,stroke:#ff4d8d,color:#ffd1e7,stroke-width:2px;
+  classDef judge fill:#2b1905,stroke:#f59e0b,color:#fef3c7,stroke-width:3px;
+  classDef answer fill:#062814,stroke:#22c55e,color:#dcfce7,stroke-width:3px;
+  classDef note fill:#0b1220,stroke:#475569,color:#cbd5e1,stroke-width:1px;
+
+  P["input prompt<br/>same question to every model"]:::prompt
+
+  subgraph PANEL[parallel model panel]
+    direction TB
+    A["model A<br/>strong baseline candidate"]:::modelA
+    B["model B<br/>finds contradiction"]:::modelB
+    C["model C<br/>adds unique insight"]:::modelC
+    D["model D<br/>fast practical path"]:::modelD
+    E["model E<br/>catches edge case"]:::modelE
   end
 
-  Q --> A
-  Q --> I
-  Q --> T
-  A --> J{{Judge}}:::judge
-  I --> J
-  T --> J
-  J --> R[Final Markdown report]:::report
-  J -. missing judge result .-> F[Fallback judge retry]:::fallback
-  F --> R
+  J["judge<br/>consensus • contradictions • blind spots"]:::judge
+  R["best answer<br/>selected or synthesized"]:::answer
+  N["not majority vote<br/>best evidence wins"]:::note
+
+  P --> A
+  P --> B
+  P --> C
+  P --> D
+  P --> E
+
+  A --> J
+  B --> J
+  C --> J
+  D --> J
+  E --> J
+
+  J --> R
+  J -.-> N
+
+  linkStyle 0,5 stroke:#38bdf8,stroke-width:3px;
+  linkStyle 1,6 stroke:#a855f7,stroke-width:3px;
+  linkStyle 2,7 stroke:#22c55e,stroke-width:3px;
+  linkStyle 3,8 stroke:#f59e0b,stroke-width:3px;
+  linkStyle 4,9 stroke:#ff4d8d,stroke-width:3px;
+  linkStyle 10 stroke:#22c55e,stroke-width:4px;
+  linkStyle 11 stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5;
 ```
 
-## How the judge works
+## Why a panel can beat one model
+
+Single-model answers are brittle on hard tasks. They are limited by one model's
+priors, one reasoning path, and one failure mode.
+
+A panel helps because:
+
+- different models are trained differently and make different bets
+- errors are less correlated, so blind spots do not line up perfectly
+- consensus is a useful confidence signal without pretending certainty
+- disagreement tells you where the answer is fragile
+- a judge can select or synthesize the best realistic answer from the set
+
+The result is slower, but usually better for design choices, risk review,
+tricky debugging, and research-heavy questions.
+
+## What the judge actually does
 
 The judge gets:
 
 - the original prompt
-- the panel outputs
-- the panel failures and blind spots
+- every panel output
+- panel failures and blind spots
 - the configured judge model
 
-It produces one report that highlights:
+It then:
 
-- consensus
-- disagreements
-- risks
-- missing evidence
-- next step
+- finds consensus
+- preserves real disagreements
+- spots weak or incomplete answers
+- pulls forward unique insights worth keeping
+- returns one clear recommendation and next step
 
-It does not edit files or spawn more subagents. It does one job: turn
-competing notes into one clear recommendation.
+It does not edit files or spawn more subagents. It does one job: choose or
+synthesize the best realistic answer.
 
 ## Good fit
 
@@ -89,6 +135,7 @@ Do not use it for trivial edits, formatting, or obvious one-step fixes.
 /fusion
 /fusion <prompt>
 /fusion --profile <name> <prompt>
+/fusion -p <name> <prompt>
 /fusion status
 /fusion stop
 /fusion init
@@ -113,7 +160,7 @@ Then reload Pi:
 /reload
 ```
 
-For full config examples and profile details, see [`docs/user-guide.md`](./docs/user-guide.md).
+For commands, config, and troubleshooting details, see [`docs/user-guide.md`](./docs/user-guide.md).
 
 ## Notes
 

package/docs/user-guide.md

@@ -1,10 +1,10 @@
 # pi-fusion user guide
 
-Use this when the README is not enough.
+README covers the why. This guide covers commands, config, and troubleshooting.
 
 ## Mental model
 
-`pi-fusion` turns one hard question into a small review panel:
+`pi-fusion` turns one hard question into a small parallel panel:
 
 ```text
 prompt → parallel panel → judge synthesis → final report
@@ -12,6 +12,8 @@ prompt → parallel panel → judge synthesis → final report
 
 Normal execution is a single `pi-subagents` async chain. If that chain completes without a judge result but at least two panelists still produced usable answers, `pi-fusion` runs one fallback judge pass instead of losing the review.
 
+Panel diversity can come from different model choices, different perspective prompts, or both. In practice, mixing models is usually the main lever.
+
 The base Pi session stays in control. Fusion is a tool for decisions, not a replacement for normal coding.
 
 ## Commands
@@ -108,9 +110,9 @@ Panel member:
 - `id`: stable machine name
 - `label`: human-readable report label
 - `agent`: subagent name
-- `model`: optional model override
+- `model`: optional model override; often the main source of panel diversity
 - `thinking`: optional `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`
-- `role`: short perspective instruction
+- `role`: optional perspective hint layered on top of the model
 
 Judge:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.2.0",
-  "description": "Subagent-native multi-model deliberation for Pi",
+  "version": "0.2.2",
+  "description": "Stronger answers for hard Pi questions via a parallel model panel + judge, built on pi-subagents",
   "type": "module",
   "main": "./src/index.ts",
   "license": "MIT",
@@ -22,11 +22,7 @@
   "files": [
     "agents/*.md",
     "src/*.ts",
-    "README.md",
-    "LICENSE",
-    "AGENTS.md",
-    "docs/user-guide.md",
-    "tsconfig.json"
+    "docs/user-guide.md"
   ],
   "scripts": {
     "check": "tsc --noEmit",
@@ -47,7 +43,8 @@
       "agents": [
         "./agents"
       ]
-    }
+    },
+    "image": "https://raw.githubusercontent.com/alexei-led/pi-fusion/master/docs/assets/fusion-icon.png"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/commands.ts

@@ -7,10 +7,11 @@ import {
   getProjectFusionConfigPath,
   writeProjectFusionConfigTemplate,
 } from "./config.js";
-import { FusionArgsError, FusionConfigError } from "./errors.js";
+import { FusionConfigError } from "./errors.js";
+import { parseFusionInlineCommand } from "./fusion-args.js";
+import type { ParsedFusionArgs } from "./types.js";
+import { isNodeErrorCode } from "./utils.js";
 
-const FUSION_USAGE =
-  "Usage: /fusion <prompt> | /fusion --profile <name> <prompt> | /fusion status | /fusion stop | /fusion init.";
 const FUSION_HELP = [
   "Fusion commands",
   "/fusion <prompt>",
@@ -20,39 +21,11 @@ const FUSION_HELP = [
   "/fusion init",
 ].join("\n");
 
-export type FusionInlineCommand = "init" | "status" | "stop";
-
-export interface ParsedFusionArgs {
-  prompt: string;
-  profile?: string;
-}
-
-interface FusionInitContext {
-  cwd: string;
-  hasUI: boolean;
-  isProjectTrusted(): boolean;
-  ui: {
-    confirm(title: string, message: string): Promise<boolean>;
-    notify(message: string, type?: "info" | "warning" | "error"): void;
-  };
-}
-
-export interface FusionInitDeps {
-  readTextFile?: (path: string) => Promise<string>;
-  writeTextFile?: (path: string, content: string) => Promise<void>;
-  ensureDir?: (path: string) => Promise<void>;
-}
-
-export type FusionInitResult =
-  | { status: "written"; path: string }
-  | {
-      status: "skipped";
-      reason: "untrusted" | "exists" | "cancelled";
-      path?: string;
-    };
-
 export interface FusionRuntimeCommandHandler {
-  startRun(args: string, ctx: ExtensionCommandContext): Promise<unknown>;
+  startRun(
+    args: string | ParsedFusionArgs,
+    ctx: ExtensionCommandContext,
+  ): Promise<unknown>;
   showStatus(ctx: ExtensionCommandContext): Promise<unknown>;
   cancelActiveRun(ctx: ExtensionCommandContext): Promise<unknown>;
 }
@@ -124,124 +97,29 @@ export async function runFusionInit(
   return { status: "written", path: writtenPath };
 }
 
-export function parseFusionInlineCommand(
-  input: string | readonly string[],
-): FusionInlineCommand | undefined {
-  const tokens =
-    typeof input === "string" ? tokenizeCommandArgs(input) : [...input];
-  if (tokens.length !== 1) return undefined;
-  const command = tokens[0];
-  if (command === "init" || command === "status" || command === "stop") {
-    return command;
-  }
-  return undefined;
+interface FusionInitContext {
+  cwd: string;
+  hasUI: boolean;
+  isProjectTrusted(): boolean;
+  ui: {
+    confirm(title: string, message: string): Promise<boolean>;
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+  };
 }
 
-export function parseFusionArgs(
-  input: string | readonly string[],
-): ParsedFusionArgs {
-  const tokens =
-    typeof input === "string" ? tokenizeCommandArgs(input) : [...input];
-  if (tokens[0] === "/fusion" || tokens[0] === "fusion") tokens.shift();
-
-  let profile: string | undefined;
-  const promptTokens: string[] = [];
-
-  for (let index = 0; index < tokens.length; index++) {
-    const token = tokens[index];
-    if (!token) continue;
-
-    if (
-      promptTokens.length === 0 &&
-      (token === "--profile" || token === "-p")
-    ) {
-      const value = tokens[index + 1];
-      if (!value || value.startsWith("-")) {
-        throw new FusionArgsError(
-          `Missing value for ${token}. ${FUSION_USAGE}`,
-        );
-      }
-      if (profile)
-        throw new FusionArgsError("Profile can only be provided once.");
-      profile = value;
-      index++;
-      continue;
-    }
-
-    if (promptTokens.length === 0 && token.startsWith("--profile=")) {
-      const value = token.slice("--profile=".length).trim();
-      if (!value)
-        throw new FusionArgsError(
-          `Missing value for --profile. ${FUSION_USAGE}`,
-        );
-      if (profile)
-        throw new FusionArgsError("Profile can only be provided once.");
-      profile = value;
-      continue;
-    }
-
-    if (promptTokens.length === 0 && token.startsWith("-")) {
-      throw new FusionArgsError(`Unknown option ${token}. ${FUSION_USAGE}`);
-    }
-
-    promptTokens.push(token, ...tokens.slice(index + 1));
-    break;
-  }
-
-  const prompt = promptTokens.join(" ").trim();
-  if (!prompt) throw new FusionArgsError(FUSION_USAGE);
-  return profile ? { prompt, profile } : { prompt };
+export interface FusionInitDeps {
+  readTextFile?: (path: string) => Promise<string>;
+  writeTextFile?: (path: string, content: string) => Promise<void>;
+  ensureDir?: (path: string) => Promise<void>;
 }
 
-export function tokenizeCommandArgs(input: string): string[] {
-  const tokens: string[] = [];
-  let current = "";
-  let quote: "'" | '"' | undefined;
-  let escaping = false;
-
-  for (const char of input.trim()) {
-    if (escaping) {
-      current += char;
-      escaping = false;
-      continue;
-    }
-
-    if (char === "\\") {
-      escaping = true;
-      continue;
-    }
-
-    if (quote) {
-      if (char === quote) {
-        quote = undefined;
-      } else {
-        current += char;
-      }
-      continue;
-    }
-
-    if (char === "'" || char === '"') {
-      quote = char;
-      continue;
-    }
-
-    if (/\s/.test(char)) {
-      if (current) {
-        tokens.push(current);
-        current = "";
-      }
-      continue;
-    }
-
-    current += char;
-  }
-
-  if (escaping) current += "\\";
-  if (quote)
-    throw new FusionArgsError(`Unclosed ${quote} quote in /fusion arguments.`);
-  if (current) tokens.push(current);
-  return tokens;
-}
+export type FusionInitResult =
+  | { status: "written"; path: string }
+  | {
+      status: "skipped";
+      reason: "untrusted" | "exists" | "cancelled";
+      path?: string;
+    };
 
 async function fileExists(
   path: string,
@@ -259,15 +137,6 @@ async function fileExists(
   }
 }
 
-function isNodeErrorCode(error: unknown, code: string): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    error.code === code
-  );
-}
-
 async function readUtf8File(path: string): Promise<string> {
   return readFile(path, "utf8");
 }

package/src/config.ts

@@ -11,6 +11,12 @@ import {
   type PanelMemberConfig,
   type ThinkingLevel,
 } from "./types.js";
+import {
+  isNodeErrorCode,
+  isNonEmptyString,
+  isPositiveInteger,
+  isRecord,
+} from "./utils.js";
 
 export const FUSION_CONFIG_FILE = "fusion.json";
 export const DEFAULT_PROFILE_NAME = "quality";
@@ -227,22 +233,6 @@ function isFusionContextMode(value: unknown): value is FusionContextMode {
   return value === "fresh" || value === "fork";
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-function isPositiveInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value > 0;
-}
-
-function isNodeErrorCode(error: unknown, code: string): boolean {
-  return isRecord(error) && error.code === code;
-}
-
 async function readUtf8File(path: string): Promise<string> {
   return readFile(path, "utf8");
 }

package/src/fusion-args.ts

@@ -0,0 +1,126 @@
+import { FusionArgsError } from "./errors.js";
+import type { ParsedFusionArgs } from "./types.js";
+
+const FUSION_USAGE =
+  "Usage: /fusion <prompt> | /fusion --profile <name> <prompt> | /fusion status | /fusion stop | /fusion init.";
+
+export type FusionInlineCommand = "init" | "status" | "stop";
+
+export function parseFusionInlineCommand(
+  input: string | readonly string[],
+): FusionInlineCommand | undefined {
+  const tokens =
+    typeof input === "string" ? tokenizeCommandArgs(input) : [...input];
+  if (tokens.length !== 1) return undefined;
+  const command = tokens[0];
+  if (command === "init" || command === "status" || command === "stop") {
+    return command;
+  }
+  return undefined;
+}
+
+export function parseFusionArgs(
+  input: string | readonly string[],
+): ParsedFusionArgs {
+  const tokens =
+    typeof input === "string" ? tokenizeCommandArgs(input) : [...input];
+  if (tokens[0] === "/fusion" || tokens[0] === "fusion") tokens.shift();
+
+  let profile: string | undefined;
+  const promptTokens: string[] = [];
+
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (!token) continue;
+
+    if (
+      promptTokens.length === 0 &&
+      (token === "--profile" || token === "-p")
+    ) {
+      const value = tokens[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new FusionArgsError(
+          `Missing value for ${token}. ${FUSION_USAGE}`,
+        );
+      }
+      if (profile)
+        throw new FusionArgsError("Profile can only be provided once.");
+      profile = value;
+      index++;
+      continue;
+    }
+
+    if (promptTokens.length === 0 && token.startsWith("--profile=")) {
+      const value = token.slice("--profile=".length).trim();
+      if (!value)
+        throw new FusionArgsError(
+          `Missing value for --profile. ${FUSION_USAGE}`,
+        );
+      if (profile)
+        throw new FusionArgsError("Profile can only be provided once.");
+      profile = value;
+      continue;
+    }
+
+    if (promptTokens.length === 0 && token.startsWith("-")) {
+      throw new FusionArgsError(`Unknown option ${token}. ${FUSION_USAGE}`);
+    }
+
+    promptTokens.push(token, ...tokens.slice(index + 1));
+    break;
+  }
+
+  const prompt = promptTokens.join(" ").trim();
+  if (!prompt) throw new FusionArgsError(FUSION_USAGE);
+  return profile ? { prompt, profile } : { prompt };
+}
+
+export function tokenizeCommandArgs(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  let escaping = false;
+
+  for (const char of input.trim()) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escaping) current += "\\";
+  if (quote)
+    throw new FusionArgsError(`Unclosed ${quote} quote in /fusion arguments.`);
+  if (current) tokens.push(current);
+  return tokens;
+}

package/src/orchestrator.ts

@@ -4,18 +4,17 @@ import {
   type ResolvedFusionProfile,
 } from "./config.js";
 import { FusionArgsError } from "./errors.js";
+import { parseFusionArgs } from "./fusion-args.js";
+import { decidePanelCompletion } from "./panel-completion.js";
 import {
   renderCancelledReport,
   renderFailureReport,
   renderJudgeReport,
-  renderPanelFailureReport,
-  renderSinglePanelReport,
 } from "./report.js";
 import { extractPanelResults } from "./result-extract.js";
 import {
   appendThinkingSuffix,
   buildFusionChainSpawnParams,
-  buildJudgeSpawnParams,
 } from "./run-builder.js";
 import { FusionRunStore, FusionRunStoreError } from "./run-store.js";
 import {
@@ -35,8 +34,8 @@ import type {
   FusionProfile,
   FusionRun,
   PanelOutput,
+  ParsedFusionArgs,
 } from "./types.js";
-import { parseFusionArgs, type ParsedFusionArgs } from "./commands.js";
 import type { SubagentsTargetParams } from "./subagents-rpc.js";
 
 export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
@@ -124,15 +123,7 @@ export class FusionOrchestrator {
   ): Promise<FusionCommandResult> {
     this.context = ctx;
 
-    let args: ParsedFusionArgs;
-    try {
-      args = typeof input === "string" ? parseFusionArgs(input) : input;
-    } catch (error: unknown) {
-      const message = errorMessage(error);
-      this.notify(ctx, message, "error");
-      return { status: "failed", error: message };
-    }
-
+    const args = typeof input === "string" ? parseFusionArgs(input) : input;
     const existing = this.runStore.getActiveRun();
     if (existing) {
       const message = `Fusion run ${existing.id} is already active.`;
@@ -475,61 +466,13 @@ export class FusionOrchestrator {
       return this.completeActiveRun(report);
     }
 
-    if (extracted.outputs.length === 0) {
-      const report = renderPanelFailureReport({
-        run: updated,
-        failures: extracted.failures,
-        ...withJudgeModel(configuredJudgeModel(profile)),
-      });
-      return this.failActiveRun(
-        "No fusion panelists completed successfully.",
-        report,
-      );
-    }
-
-    if (extracted.outputs.length === 1) {
-      const report = renderSinglePanelReport({
-        run: updated,
-        output: extracted.outputs[0]!,
-        failures: extracted.failures,
-        ...withJudgeModel(configuredJudgeModel(profile)),
-      });
-      return this.completeActiveRun(report);
-    }
-
-    try {
-      const spawnResult = await this.rpc.spawn(
-        buildJudgeSpawnParams({
-          profile,
-          prompt: active.prompt,
-          panelOutputs: extracted.outputs,
-          failedPanelists: extracted.failures,
-        }),
-      );
-      const judgeRunId = extractSubagentRunId(spawnResult);
-      if (!judgeRunId) {
-        throw new FusionArgsError(
-          "pi-subagents spawn did not return a fallback judge run ID.",
-        );
-      }
-      const judgeAsyncDir = extractSubagentAsyncDir(spawnResult);
-      const nextRun = this.runStore.updateRun(active.id, {
-        phase: "judge",
-        judgeRunId,
-        ...(judgeAsyncDir ? { judgeAsyncDir } : {}),
-        panelOutputs: extracted.outputs,
-        panelFailures: extracted.failures,
-      });
-      publishFusionStatus(this.context, nextRun);
-      this.notify(
-        this.context,
-        `Fusion fallback judge started: ${judgeRunId}`,
-        "info",
-      );
-      return { status: "started", run: nextRun };
-    } catch (error: unknown) {
-      return this.failActiveRun(errorMessage(error));
-    }
+    return this.finishPanelCompletion(
+      updated,
+      profile,
+      extracted.outputs,
+      extracted.failures,
+      { fallbackJudge: true },
+    );
   }
 
   private async handleLegacyPanelComplete(
@@ -576,53 +519,57 @@ export class FusionOrchestrator {
       extracted.failures,
     );
 
-    if (extracted.outputs.length === 0) {
-      const report = renderPanelFailureReport({
-        run: updated,
-        failures: extracted.failures,
-        ...withJudgeModel(configuredJudgeModel(profile)),
-      });
-      return this.failActiveRun(
-        "No fusion panelists completed successfully.",
-        report,
-      );
-    }
+    return this.finishPanelCompletion(
+      updated,
+      profile,
+      extracted.outputs,
+      extracted.failures,
+      { fallbackJudge: false },
+    );
+  }
 
-    if (extracted.outputs.length === 1) {
-      const report = renderSinglePanelReport({
-        run: updated,
-        output: extracted.outputs[0]!,
-        failures: extracted.failures,
-        ...withJudgeModel(configuredJudgeModel(profile)),
-      });
-      return this.completeActiveRun(report);
+  private async finishPanelCompletion(
+    run: FusionRun,
+    profile: FusionProfile,
+    panelOutputs: readonly PanelOutput[],
+    panelFailures: readonly FailedPanelSummary[],
+    options: { fallbackJudge: boolean },
+  ): Promise<FusionCommandResult> {
+    const decision = decidePanelCompletion({
+      run,
+      profile,
+      panelOutputs,
+      panelFailures,
+      fallbackJudge: options.fallbackJudge,
+    });
+
+    if (decision.kind === "fail") {
+      return this.failActiveRun(decision.error, decision.report);
+    }
+    if (decision.kind === "complete") {
+      return this.completeActiveRun(decision.report);
     }
 
     try {
-      const spawnResult = await this.rpc.spawn(
-        buildJudgeSpawnParams({
-          profile,
-          prompt: active.prompt,
-          panelOutputs: extracted.outputs,
-          failedPanelists: extracted.failures,
-        }),
-      );
+      const spawnResult = await this.rpc.spawn(decision.params);
       const judgeRunId = extractSubagentRunId(spawnResult);
       if (!judgeRunId) {
-        throw new FusionArgsError(
-          "pi-subagents spawn did not return a judge run ID.",
-        );
+        throw new FusionArgsError(decision.missingRunIdError);
       }
       const judgeAsyncDir = extractSubagentAsyncDir(spawnResult);
-      const nextRun = this.runStore.updateRun(active.id, {
+      const nextRun = this.runStore.updateRun(run.id, {
         phase: "judge",
         judgeRunId,
         ...(judgeAsyncDir ? { judgeAsyncDir } : {}),
-        panelOutputs: extracted.outputs,
-        panelFailures: extracted.failures,
+        panelOutputs: [...panelOutputs],
+        panelFailures: [...panelFailures],
       });
       publishFusionStatus(this.context, nextRun);
-      this.notify(this.context, `Fusion judge started: ${judgeRunId}`, "info");
+      this.notify(
+        this.context,
+        `${decision.notification}: ${judgeRunId}`,
+        "info",
+      );
       return { status: "started", run: nextRun };
     } catch (error: unknown) {
       return this.failActiveRun(errorMessage(error));

package/src/panel-completion.ts

@@ -0,0 +1,85 @@
+import { renderPanelFailureReport, renderSinglePanelReport } from "./report.js";
+import {
+  appendThinkingSuffix,
+  buildJudgeSpawnParams,
+  type JudgeSpawnParams,
+} from "./run-builder.js";
+import type {
+  FailedPanelSummary,
+  FusionProfile,
+  FusionRun,
+  PanelOutput,
+} from "./types.js";
+
+export type PanelCompletionDecision =
+  | { kind: "fail"; error: string; report: string }
+  | { kind: "complete"; report: string }
+  | {
+      kind: "judge";
+      params: JudgeSpawnParams;
+      missingRunIdError: string;
+      notification: string;
+    };
+
+export interface DecidePanelCompletionInput {
+  run: FusionRun;
+  profile: FusionProfile;
+  panelOutputs: readonly PanelOutput[];
+  panelFailures: readonly FailedPanelSummary[];
+  fallbackJudge?: boolean;
+}
+
+export function decidePanelCompletion(
+  input: DecidePanelCompletionInput,
+): PanelCompletionDecision {
+  const judgeModel = configuredJudgeModel(input.profile);
+
+  if (input.panelOutputs.length === 0) {
+    const report = renderPanelFailureReport({
+      run: input.run,
+      failures: input.panelFailures,
+      ...withJudgeModel(judgeModel),
+    });
+    return {
+      kind: "fail",
+      error: "No fusion panelists completed successfully.",
+      report,
+    };
+  }
+
+  if (input.panelOutputs.length === 1) {
+    const report = renderSinglePanelReport({
+      run: input.run,
+      output: input.panelOutputs[0]!,
+      failures: input.panelFailures,
+      ...withJudgeModel(judgeModel),
+    });
+    return { kind: "complete", report };
+  }
+
+  return {
+    kind: "judge",
+    params: buildJudgeSpawnParams({
+      profile: input.profile,
+      prompt: input.run.prompt,
+      panelOutputs: input.panelOutputs,
+      failedPanelists: input.panelFailures,
+    }),
+    missingRunIdError: input.fallbackJudge
+      ? "pi-subagents spawn did not return a fallback judge run ID."
+      : "pi-subagents spawn did not return a judge run ID.",
+    notification: input.fallbackJudge
+      ? "Fusion fallback judge started"
+      : "Fusion judge started",
+  };
+}
+
+function configuredJudgeModel(profile: FusionProfile): string | undefined {
+  return appendThinkingSuffix(profile.judge.model, profile.judge.thinking);
+}
+
+function withJudgeModel(
+  judgeModel: string | undefined,
+): { judgeModel: string } | Record<string, never> {
+  return judgeModel ? { judgeModel } : {};
+}

package/src/run-store.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { FusionPhase, FusionRun } from "./types.js";
+import { isFiniteNumber, isNonEmptyString, isRecord } from "./utils.js";
 
 export const FUSION_RUN_ENTRY_TYPE = "fusion-run";
 
@@ -423,18 +424,6 @@ function isTerminalPhase(value: unknown): value is FusionTerminalPhase {
   return value === "done" || value === "failed" || value === "cancelled";
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
 function isPanelOutputArray(
   value: unknown,
 ): value is NonNullable<FusionRun["panelOutputs"]> {

package/src/types.ts

@@ -38,6 +38,11 @@ export interface FusionConfig {
   profiles: Record<string, FusionProfile>;
 }
 
+export interface ParsedFusionArgs {
+  prompt: string;
+  profile?: string;
+}
+
 export interface PanelOutput {
   index: number;
   agent: string;

package/src/utils.ts

@@ -0,0 +1,19 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function isPositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function isNodeErrorCode(error: unknown, code: string): boolean {
+  return isRecord(error) && error.code === code;
+}

package/AGENTS.md

@@ -1,7 +0,0 @@
-# Contributor notes
-
-- Keep the extension small, typed, and testable.
-- Do not own or replace the Pi footer. Publish only the `fusion` status key.
-- Use `pi-subagents` RPC for panel and judge execution. Do not import its internals.
-- Keep bundled panel agents read-only by default.
-- Do not add runtime dependencies unless the task needs them.

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2023",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-    "useUnknownInCatchVariables": true,
-    "noImplicitOverride": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "skipLibCheck": true
-  },
-  "include": [
-    "src/**/*.ts",
-    "test/**/*.ts"
-  ]
-}