@alexeiled/pi-fusion 0.1.2 → 0.2.0

package/README.md

@@ -4,19 +4,72 @@
 [![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)
 
-When a coding question deserves a design review, not a guess.
+> Parallel panel. One judge. One report.
+
+`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.
+
+## Fusion model
+
+My approach is simple:
+
+- 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
+
+This is evidence-first, not majority vote.
+The judge is a synthesizer, not a tie-breaker by headcount.
+
+```mermaid
+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
+  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
+```
+
+## How the judge works
+
+The judge gets:
 
-`pi-fusion` is a Pi extension that runs a small panel of read-only subagents in parallel, then asks a judge agent to synthesize one final report.
+- the original prompt
+- the panel outputs
+- the panel failures and blind spots
+- the configured judge model
 
-You get:
+It produces one report that highlights:
 
 - consensus
 - disagreements
-- blind spots
 - risks
-- recommended next step
+- missing evidence
+- next step
 
-It applies the [Fusion](https://openrouter.ai/blog/announcements/fusion-beats-frontier/) idea to Pi: spend extra tokens only on questions where multiple perspectives are worth it.
+It does not edit files or spawn more subagents. It does one job: turn
+competing notes into one clear recommendation.
 
 ## Good fit
 
@@ -30,25 +83,17 @@ Use it for questions like:
 
 Do not use it for trivial edits, formatting, or obvious one-step fixes.
 
-## How it works
+## Commands
 
 ```text
-/fusion Should this extension use node:test or Vitest?
-
-1. Panelists inspect the problem independently.
-2. The judge compares their answers.
-3. Pi shows one final Markdown report.
+/fusion
+/fusion <prompt>
+/fusion --profile <name> <prompt>
+/fusion status
+/fusion stop
+/fusion init
 ```
 
-Default roles:
-
-- **Architect** — tradeoffs and failure modes
-- **Implementer** — contracts, edge cases, practical fit
-- **Tester** — regressions and verification
-- **Judge** — synthesis and recommendation
-
-Bundled agents are read-only by default. They can inspect files, but they do not edit code, commit changes, or run nested subagents.
-
 ## Quick start
 
 Requirements:
@@ -68,16 +113,7 @@ Then reload Pi:
 /reload
 ```
 
-## Commands
-
-```text
-/fusion
-/fusion <prompt>
-/fusion --profile <name> <prompt>
-/fusion status
-/fusion stop
-/fusion init
-```
+For full config examples and profile details, see [`docs/user-guide.md`](./docs/user-guide.md).
 
 ## Notes
 
@@ -85,6 +121,7 @@ Then reload Pi:
 - 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.
 - `pi-fusion` does not own the footer.
 - Prompts and inspected snippets may be sent to your configured model providers through `pi-subagents`.
 

package/docs/user-guide.md

@@ -7,9 +7,11 @@ Use this when the README is not enough.
 `pi-fusion` turns one hard question into a small review panel:
 
 ```text
-prompt → panelists in parallel → judge synthesis → final report
+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.
+
 The base Pi session stays in control. Fusion is a tool for decisions, not a replacement for normal coding.
 
 ## Commands
@@ -30,7 +32,7 @@ Notes:
 
 - Bare `/fusion` shows a short help message.
 - `/fusion status` shows the active run, last run, warnings, and subagent run IDs.
-- `/fusion stop` stops the active panel or judge run.
+- `/fusion stop` stops the active chain or fallback judge run.
 - `/fusion init` writes `.pi/fusion.json` for the current trusted project.
 - Exact one-word prompts `init`, `status`, and `stop` are reserved as `/fusion` subcommands.
 
@@ -250,3 +252,9 @@ Need the run IDs:
 ```text
 /fusion status
 ```
+
+Notes:
+
+- `Chain run` is the normal end-to-end Fusion run.
+- `Fallback judge run` appears only when Fusion had enough panel output to recover a missing judge result.
+- If `pi-subagents` completion notifications are delayed or missed, Fusion still reconciles from lifecycle artifacts written under the subagent async run directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Subagent-native multi-model deliberation for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -29,6 +29,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   pi.on("session_shutdown", () => {
     orchestrator.clearUi();
+    orchestrator.dispose();
     if (typeof unsubscribeComplete === "function") unsubscribeComplete();
   });
 }