@alexeiled/pi-fusion 0.5.0 → 0.5.2

package/README.md

@@ -142,6 +142,34 @@ Do not use it for trivial edits, formatting, or obvious one-step fixes.
 /fusion init
 ```
 
+## Plan execution RPC
+
+Other Pi extensions can control Fusion through the versioned event-bus contract
+`fusion:rpc:v1`:
+
+- emit requests on `fusion:rpc:v1:request`
+- listen for the response on `fusion:rpc:v1:reply:<requestId>` before emitting
+- send `{ "version": 1, "requestId": "...", "method": "...", "params": {} }`
+- receive `{ "version": 1, "requestId": "...", "method": "...", "success": true, "data": {} }` or a failure with a typed `error`
+
+Methods:
+
+- `ping` — return the RPC version and supported methods
+- `start` — requires `prompt` and a non-empty `operationId`; accepts optional `profile`. 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; active runs return `not_ready`
+- `cancel` — cancel the selected active run, or report that the selected terminal run was not cancelled
+- `adopt` — confirm 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`.
+
+Failure codes are `invalid_request`, `unsupported_method`, `busy`, `not_found`,
+`not_ready`, `unavailable`, `start_failed`, `cancel_failed`, and `internal`.
+`busy`, `not_ready`, and lookup failures include structured details when available.
+
 ## Quick start
 
 Requirements:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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/fusion-rpc.ts

@@ -0,0 +1,619 @@
+import type {
+  FusionCommandContext,
+  FusionCommandResult,
+} from "./orchestrator.js";
+import type { FusionRunStore } from "./run-store.js";
+import type { FusionPhase, FusionRun, ParsedFusionArgs } from "./types.js";
+import { isNonEmptyString, isRecord } from "./utils.js";
+
+export const FUSION_RPC_VERSION = 1;
+export const FUSION_RPC_REQUEST_EVENT = "fusion:rpc:v1:request";
+export const FUSION_RPC_REPLY_EVENT_PREFIX = "fusion:rpc:v1:reply:";
+
+export const FUSION_RPC_METHODS = [
+  "ping",
+  "start",
+  "status",
+  "result",
+  "cancel",
+  "adopt",
+] as const;
+
+export type FusionRpcMethod = (typeof FUSION_RPC_METHODS)[number];
+
+export type FusionRpcErrorCode =
+  | "invalid_request"
+  | "unsupported_method"
+  | "busy"
+  | "not_found"
+  | "not_ready"
+  | "unavailable"
+  | "start_failed"
+  | "cancel_failed"
+  | "internal";
+
+export interface FusionRpcRequestEnvelope {
+  version: typeof FUSION_RPC_VERSION;
+  requestId: string;
+  method: FusionRpcMethod;
+  params?: unknown;
+}
+
+export interface FusionRpcError {
+  code: FusionRpcErrorCode;
+  message: string;
+  details?: unknown;
+}
+
+export interface FusionRunState {
+  runId: string;
+  operationId?: string;
+  phase: FusionPhase;
+  terminal: boolean;
+  report?: string;
+  error?: string;
+}
+
+export interface FusionRpcPingData {
+  pong: true;
+  version: typeof FUSION_RPC_VERSION;
+  methods: readonly FusionRpcMethod[];
+}
+
+export interface FusionRpcStartData {
+  operationId: string;
+  replayed: boolean;
+  run: FusionRunState;
+}
+
+export interface FusionRpcStatusData {
+  run: FusionRunState;
+}
+
+export interface FusionRpcResultData {
+  run: FusionRunState;
+}
+
+export interface FusionRpcCancelData {
+  cancelled: boolean;
+  run?: FusionRunState;
+}
+
+export interface FusionRpcAdoptData {
+  adopted: true;
+  run: FusionRunState;
+}
+
+export type FusionRpcReplyEnvelope =
+  | {
+      version: typeof FUSION_RPC_VERSION;
+      requestId: string;
+      method?: FusionRpcMethod;
+      success: true;
+      data: unknown;
+    }
+  | {
+      version: typeof FUSION_RPC_VERSION;
+      requestId: string;
+      method?: FusionRpcMethod;
+      success: false;
+      error: FusionRpcError;
+    };
+
+export interface FusionRpcEventBus {
+  on(event: string, handler: (payload: unknown) => void): (() => void) | void;
+  emit(event: string, payload: unknown): void;
+}
+
+export interface FusionRpcOrchestrator {
+  startRun(
+    input: ParsedFusionArgs,
+    ctx: FusionCommandContext,
+  ): Promise<FusionCommandResult>;
+  cancelActiveRun(ctx: FusionCommandContext): Promise<FusionCommandResult>;
+}
+
+type FusionRpcRunStore = Pick<
+  FusionRunStore,
+  "getActiveRun" | "getLastRunSummary" | "getRunById" | "getRunByOperationId"
+>;
+
+export interface FusionRpcDependencies {
+  events: FusionRpcEventBus;
+  orchestrator: FusionRpcOrchestrator;
+  store: FusionRpcRunStore;
+  getContext: () => FusionCommandContext | undefined;
+}
+
+interface OperationRecord {
+  pending?: Promise<FusionRpcStartData>;
+  runId?: string;
+}
+
+interface StartParams {
+  prompt: string;
+  profile?: string;
+  operationId: string;
+}
+
+interface RunParams {
+  runId?: string;
+  operationId?: string;
+}
+
+type ObservableRun = Pick<
+  FusionRun,
+  "id" | "operationId" | "phase" | "report" | "error"
+>;
+
+const TERMINAL_PHASES = new Set<FusionPhase>(["done", "failed", "cancelled"]);
+
+export function fusionRpcReplyEvent(requestId: string): string {
+  return `${FUSION_RPC_REPLY_EVENT_PREFIX}${requestId}`;
+}
+
+export function registerFusionRpc({
+  events,
+  orchestrator,
+  store,
+  getContext,
+}: FusionRpcDependencies): () => void {
+  const operations = new Map<string, OperationRecord>();
+  const unsubscribe = events.on(FUSION_RPC_REQUEST_EVENT, (event) => {
+    void handleRequest(event);
+  });
+
+  return typeof unsubscribe === "function" ? unsubscribe : () => undefined;
+
+  async function handleRequest(event: unknown): Promise<void> {
+    const request = parseRequest(event);
+    if (request instanceof RpcRequestFailure) {
+      if (request.requestId) {
+        replyFailure(request.requestId, request.method, request.error);
+      }
+      return;
+    }
+
+    try {
+      const data = await dispatch(request);
+      replySuccess(request.requestId, request.method, data);
+    } catch (error: unknown) {
+      replyFailure(request.requestId, request.method, normalizeError(error));
+    }
+  }
+
+  async function dispatch(request: FusionRpcRequestEnvelope): Promise<unknown> {
+    switch (request.method) {
+      case "ping":
+        return {
+          pong: true,
+          version: FUSION_RPC_VERSION,
+          methods: FUSION_RPC_METHODS,
+        } satisfies FusionRpcPingData;
+      case "start":
+        return start(request.params);
+      case "status":
+        return {
+          run: stateFor(findRun(request.params, operations, store, "status")),
+        } satisfies FusionRpcStatusData;
+      case "result":
+        return result(request.params);
+      case "cancel":
+        return cancel(request.params);
+      case "adopt":
+        return adopt(request.params);
+    }
+  }
+
+  async function start(params: unknown): Promise<FusionRpcStartData> {
+    const input = parseStartParams(params);
+    const persisted = store.getRunByOperationId(input.operationId);
+    if (persisted) return startData(input.operationId, persisted, true);
+
+    const known = operations.get(input.operationId);
+    if (known?.runId) {
+      const run = store.getRunById(known.runId);
+      if (run) return startData(input.operationId, run, true);
+      operations.delete(input.operationId);
+    } else if (known?.pending) {
+      const response = await known.pending;
+      return { ...response, replayed: true };
+    }
+
+    const context = requireContext(getContext());
+    const pending = orchestrator
+      .startRun(toParsedFusionArgs(input), context)
+      .then((result) =>
+        startData(
+          input.operationId,
+          runFromStartResult(result, input.operationId, store),
+          false,
+        ),
+      );
+    operations.set(input.operationId, { pending });
+
+    try {
+      const response = await pending;
+      operations.set(input.operationId, { runId: response.run.runId });
+      return response;
+    } catch (error: unknown) {
+      operations.delete(input.operationId);
+      throw error;
+    }
+  }
+
+  function result(params: unknown): FusionRpcResultData {
+    const run = findRun(params, operations, store, "result");
+    const state = stateFor(run);
+    if (!state.terminal) {
+      throw new RpcFailure({
+        code: "not_ready",
+        message: `Fusion run ${state.runId} is not terminal.`,
+        details: { run: state },
+      });
+    }
+    return { run: state };
+  }
+
+  async function cancel(params: unknown): Promise<FusionRpcCancelData> {
+    const selector = parseRunParams(params, "cancel");
+    const selected = hasRunSelector(selector)
+      ? findRun(params, operations, store, "cancel")
+      : undefined;
+    const active = store.getActiveRun();
+
+    if (selected && TERMINAL_PHASES.has(selected.phase)) {
+      return { cancelled: false, run: stateFor(selected) };
+    }
+    if (!active) {
+      const last = selected ?? store.getLastRunSummary();
+      return last
+        ? { cancelled: false, run: stateFor(last) }
+        : { cancelled: false };
+    }
+    if (selected && selected.id !== active.id) {
+      return { cancelled: false, run: stateFor(selected) };
+    }
+
+    const context = requireContext(getContext());
+    const cancellation = await orchestrator.cancelActiveRun(context);
+    if (cancellation.status === "cancelled") {
+      return { cancelled: true, run: stateFor(cancellation.run) };
+    }
+    if (cancellation.status === "failed") {
+      throw new RpcFailure({
+        code: "cancel_failed",
+        message: cancellation.error,
+        details: { run: stateFor(active) },
+      });
+    }
+
+    const current = store.getRunById(active.id);
+    if (!current) return { cancelled: false };
+    return {
+      cancelled: current.phase === "cancelled",
+      run: stateFor(current),
+    };
+  }
+
+  function adopt(params: unknown): FusionRpcAdoptData {
+    const runId = parseAdoptParams(params);
+    const run = store.getRunById(runId);
+    if (!run) {
+      throw new RpcFailure({
+        code: "not_found",
+        message: "Fusion run was not found in this session history.",
+        details: { runId },
+      });
+    }
+    return { adopted: true, run: stateFor(run) };
+  }
+
+  function replySuccess(
+    requestId: string,
+    method: FusionRpcMethod,
+    data: unknown,
+  ): void {
+    events.emit(fusionRpcReplyEvent(requestId), {
+      version: FUSION_RPC_VERSION,
+      requestId,
+      method,
+      success: true,
+      data,
+    } satisfies FusionRpcReplyEnvelope);
+  }
+
+  function replyFailure(
+    requestId: string,
+    method: FusionRpcMethod | undefined,
+    error: FusionRpcError,
+  ): void {
+    events.emit(fusionRpcReplyEvent(requestId), {
+      version: FUSION_RPC_VERSION,
+      requestId,
+      ...(method === undefined ? {} : { method }),
+      success: false,
+      error,
+    } satisfies FusionRpcReplyEnvelope);
+  }
+}
+
+function parseRequest(
+  input: unknown,
+): FusionRpcRequestEnvelope | RpcRequestFailure {
+  if (!isRecord(input)) {
+    return new RpcRequestFailure(undefined, undefined, {
+      code: "invalid_request",
+      message: "RPC request must be an object.",
+    });
+  }
+
+  const requestId = input.requestId;
+  const method = input.method;
+  if (!isNonEmptyString(requestId)) {
+    return new RpcRequestFailure(undefined, undefined, {
+      code: "invalid_request",
+      message: "RPC requestId must be a non-empty string.",
+    });
+  }
+  if (!isMethod(method)) {
+    return new RpcRequestFailure(requestId, undefined, {
+      code: "unsupported_method",
+      message: "RPC method is unsupported.",
+    });
+  }
+  if (input.version !== FUSION_RPC_VERSION) {
+    return new RpcRequestFailure(requestId, method, {
+      code: "invalid_request",
+      message: `RPC version must be ${FUSION_RPC_VERSION}.`,
+    });
+  }
+
+  return input.params === undefined
+    ? { version: FUSION_RPC_VERSION, requestId, method }
+    : {
+        version: FUSION_RPC_VERSION,
+        requestId,
+        method,
+        params: input.params,
+      };
+}
+
+function parseStartParams(input: unknown): StartParams {
+  if (!isRecord(input)) {
+    throw invalidParams("start parameters must be an object.");
+  }
+
+  const prompt = input.prompt;
+  if (!isNonEmptyString(prompt)) {
+    throw invalidParams("start prompt must be a non-empty string.");
+  }
+
+  const operationId = input.operationId;
+  if (!isNonEmptyString(operationId)) {
+    throw invalidParams("start operationId must be a non-empty string.");
+  }
+
+  const profile = input.profile;
+  if (profile !== undefined && !isNonEmptyString(profile)) {
+    throw invalidParams(
+      "start profile must be a non-empty string when provided.",
+    );
+  }
+
+  return profile === undefined
+    ? { prompt, operationId }
+    : { prompt, operationId, profile };
+}
+
+function toParsedFusionArgs(input: StartParams): ParsedFusionArgs {
+  return input.profile === undefined
+    ? { prompt: input.prompt, operationId: input.operationId }
+    : {
+        prompt: input.prompt,
+        profile: input.profile,
+        operationId: input.operationId,
+      };
+}
+
+function findRun(
+  input: unknown,
+  operations: ReadonlyMap<string, OperationRecord>,
+  store: FusionRpcRunStore,
+  method: "status" | "result" | "cancel",
+): ObservableRun {
+  const params = parseRunParams(input, method);
+  if (params.operationId) {
+    const persisted = store.getRunByOperationId(params.operationId);
+    if (persisted) return persisted;
+
+    const operation = operations.get(params.operationId);
+    if (operation?.runId) {
+      const run = store.getRunById(operation.runId);
+      if (run) return run;
+    }
+    if (operation?.pending) {
+      const active = store.getActiveRun();
+      if (active?.operationId === params.operationId) return active;
+      throw new RpcFailure({
+        code: "not_ready",
+        message: `Fusion operation ${params.operationId} has not produced a run yet.`,
+        details: { operationId: params.operationId },
+      });
+    }
+    throw notFound({ operationId: params.operationId });
+  }
+  if (params.runId) {
+    const run = store.getRunById(params.runId);
+    if (!run) throw notFound({ runId: params.runId });
+    return run;
+  }
+
+  const run = store.getActiveRun() ?? store.getLastRunSummary();
+  if (!run) throw notFound();
+  return run;
+}
+
+function parseRunParams(
+  input: unknown,
+  method: "status" | "result" | "cancel",
+): RunParams {
+  if (input === undefined) return {};
+  if (!isRecord(input)) {
+    throw invalidParams(`${method} parameters must be an object.`);
+  }
+
+  const { operationId, runId } = input;
+  if (operationId !== undefined && !isNonEmptyString(operationId)) {
+    throw invalidParams(
+      "operationId must be a non-empty string when provided.",
+    );
+  }
+  if (runId !== undefined && !isNonEmptyString(runId)) {
+    throw invalidParams("runId must be a non-empty string when provided.");
+  }
+  if (operationId !== undefined && runId !== undefined) {
+    throw invalidParams("Specify either operationId or runId, not both.");
+  }
+
+  if (operationId !== undefined) return { operationId };
+  return runId === undefined ? {} : { runId };
+}
+
+function hasRunSelector(params: RunParams): boolean {
+  return params.operationId !== undefined || params.runId !== undefined;
+}
+
+function parseAdoptParams(input: unknown): string {
+  if (!isRecord(input) || !isNonEmptyString(input.runId)) {
+    throw invalidParams("adopt runId must be a non-empty string.");
+  }
+  return input.runId;
+}
+
+function runFromStartResult(
+  result: FusionCommandResult,
+  operationId: string,
+  store: FusionRpcRunStore,
+): ObservableRun {
+  switch (result.status) {
+    case "started":
+    case "done":
+    case "cancelled":
+      return result.run;
+    case "conflict": {
+      const active = store.getRunById(result.activeRunId);
+      throw new RpcFailure({
+        code: "busy",
+        message: `Fusion run ${result.activeRunId} is already active.`,
+        details: {
+          activeRunId: result.activeRunId,
+          ...(active ? { run: stateFor(active) } : {}),
+        },
+      });
+    }
+    case "failed":
+      throw startFailure(result.error, store.getRunByOperationId(operationId));
+    case "ignored": {
+      const persisted = store.getRunByOperationId(operationId);
+      if (persisted) return persisted;
+      throw new RpcFailure({
+        code: "internal",
+        message: "Fusion run did not start.",
+      });
+    }
+  }
+}
+
+function startData(
+  operationId: string,
+  run: ObservableRun,
+  replayed: boolean,
+): FusionRpcStartData {
+  if (run.phase === "failed") {
+    throw startFailure(run.error ?? "Fusion run failed to start.", run);
+  }
+  return {
+    operationId,
+    replayed,
+    run: stateFor(run),
+  };
+}
+
+function startFailure(message: string, run?: ObservableRun): RpcFailure {
+  return new RpcFailure({
+    code: "start_failed",
+    message,
+    ...(run ? { details: { run: stateFor(run) } } : {}),
+  });
+}
+
+function stateFor(run: ObservableRun): FusionRunState {
+  const state: FusionRunState = {
+    runId: run.id,
+    ...(run.operationId !== undefined ? { operationId: run.operationId } : {}),
+    phase: run.phase,
+    terminal: TERMINAL_PHASES.has(run.phase),
+  };
+  if (run.report !== undefined) state.report = run.report;
+  if (run.error !== undefined) state.error = run.error;
+  return state;
+}
+
+function requireContext(
+  context: FusionCommandContext | undefined,
+): FusionCommandContext {
+  if (context) return context;
+  throw new RpcFailure({
+    code: "unavailable",
+    message: "Fusion session context is unavailable.",
+  });
+}
+
+function isMethod(value: unknown): value is FusionRpcMethod {
+  return (
+    value === "ping" ||
+    value === "start" ||
+    value === "status" ||
+    value === "result" ||
+    value === "cancel" ||
+    value === "adopt"
+  );
+}
+
+function invalidParams(message: string): RpcFailure {
+  return new RpcFailure({ code: "invalid_request", message });
+}
+
+function notFound(details?: unknown): RpcFailure {
+  return new RpcFailure({
+    code: "not_found",
+    message: "Fusion run was not found.",
+    ...(details === undefined ? {} : { details }),
+  });
+}
+
+function normalizeError(error: unknown): FusionRpcError {
+  if (error instanceof RpcFailure) return error.error;
+  return {
+    code: "internal",
+    message:
+      error instanceof Error ? error.message : "Unexpected Fusion RPC error.",
+  };
+}
+
+class RpcFailure extends Error {
+  constructor(readonly error: FusionRpcError) {
+    super(error.message);
+  }
+}
+
+class RpcRequestFailure extends Error {
+  constructor(
+    readonly requestId: string | undefined,
+    readonly method: FusionRpcMethod | undefined,
+    readonly error: FusionRpcError,
+  ) {
+    super(error.message);
+  }
+}

package/src/index.ts

@@ -4,7 +4,9 @@ import { registerFusionCommands } from "./commands.js";
 import {
   FusionOrchestrator,
   SUBAGENT_ASYNC_COMPLETE_EVENT,
+  type FusionCommandContext,
 } from "./orchestrator.js";
+import { registerFusionRpc } from "./fusion-rpc.js";
 import { FusionRunStore } from "./run-store.js";
 import { SubagentsRpcClient } from "./subagents-rpc.js";
 
@@ -54,9 +56,11 @@ function registerFusionTool(
 }
 
 export default function fusionExtension(pi: ExtensionAPI): void {
+  const store = new FusionRunStore({ persistence: pi });
+  let sessionContext: FusionCommandContext | undefined;
   const orchestrator = new FusionOrchestrator({
     rpc: new SubagentsRpcClient({ events: pi.events }),
-    runStore: new FusionRunStore({ persistence: pi }),
+    runStore: store,
     sendMessage: (message) => pi.sendMessage(message),
   });
 
@@ -69,14 +73,23 @@ export default function fusionExtension(pi: ExtensionAPI): void {
       void orchestrator.handleSubagentComplete(payload);
     },
   );
+  const unsubscribeRpc = registerFusionRpc({
+    events: pi.events,
+    orchestrator,
+    store,
+    getContext: () => sessionContext,
+  });
 
   pi.on("session_start", async (_event, ctx) => {
+    sessionContext = ctx;
     await orchestrator.restore(ctx);
   });
 
   pi.on("session_shutdown", () => {
+    sessionContext = undefined;
     orchestrator.clearUi();
     orchestrator.dispose();
     if (typeof unsubscribeComplete === "function") unsubscribeComplete();
+    unsubscribeRpc();
   });
 }

package/src/orchestrator.ts

@@ -21,6 +21,7 @@ import {
   clearFusionUi,
   extractFusionProgressCounts,
   formatProgressCounts,
+  isTerminalFusionProgress,
   publishFusionStatus,
   type FusionProgressCounts,
   type FusionUi,
@@ -165,6 +166,9 @@ export class FusionOrchestrator {
       run = this.runStore.startRun({
         prompt: args.prompt,
         profileName: resolved.name,
+        ...(args.operationId !== undefined
+          ? { operationId: args.operationId }
+          : {}),
         phase: "panel",
       });
     } catch (error: unknown) {
@@ -187,6 +191,8 @@ export class FusionOrchestrator {
       const spawnResult = await this.rpc.spawn(
         buildPanelSpawnParams(resolved.profile, args.prompt),
       );
+      const spawnError = extractSubagentFailure(spawnResult);
+      if (spawnError) throw new FusionArgsError(spawnError);
       const panelRunId = extractSubagentRunId(spawnResult);
       if (!panelRunId) {
         throw new FusionArgsError(
@@ -516,13 +522,17 @@ export class FusionOrchestrator {
       return { status: "ignored" };
     }
 
-    const extracted = extractPanelResults(
-      snapshot.resultPayload ?? snapshot.statusPayload ?? payload,
-      {
-        panel: profile.panel,
-        limit: profile.panel.length,
-      },
-    );
+    const lifecyclePayload =
+      snapshot.resultPayload ?? snapshot.statusPayload ?? payload;
+    const lifecycleError = extractSubagentFailure(lifecyclePayload);
+    if (!hasLifecycleResults(lifecyclePayload) && lifecycleError) {
+      return this.failActiveRun(lifecycleError);
+    }
+
+    const extracted = extractPanelResults(lifecyclePayload, {
+      panel: profile.panel,
+      limit: profile.panel.length,
+    });
     if (!extracted.ok) {
       return this.failActiveRun(
         `${extracted.error.message} (${extracted.error.path})`,
@@ -627,16 +637,20 @@ export class FusionOrchestrator {
       return { status: "ignored" };
     }
 
-    const extracted = extractPanelResults(
-      snapshot.resultPayload ?? snapshot.statusPayload ?? payload,
-      {
-        panel: profile.panel,
-        limit: profile.panel.length,
-        ...(active.panelStoppedIndices
-          ? { stoppedPanelIndices: active.panelStoppedIndices }
-          : {}),
-      },
-    );
+    const lifecyclePayload =
+      snapshot.resultPayload ?? snapshot.statusPayload ?? payload;
+    const lifecycleError = extractSubagentFailure(lifecyclePayload);
+    if (!hasLifecycleResults(lifecyclePayload) && lifecycleError) {
+      return this.failActiveRun(lifecycleError);
+    }
+
+    const extracted = extractPanelResults(lifecyclePayload, {
+      panel: profile.panel,
+      limit: profile.panel.length,
+      ...(active.panelStoppedIndices
+        ? { stoppedPanelIndices: active.panelStoppedIndices }
+        : {}),
+    });
     if (!extracted.ok) {
       return this.failActiveRun(
         `${extracted.error.message} (${extracted.error.path})`,
@@ -741,6 +755,8 @@ export class FusionOrchestrator {
 
     try {
       const spawnResult = await this.rpc.spawn(decision.params);
+      const spawnError = extractSubagentFailure(spawnResult);
+      if (spawnError) throw new FusionArgsError(spawnError);
       const judgeRunId = extractSubagentRunId(spawnResult);
       if (!judgeRunId) {
         throw new FusionArgsError(decision.missingRunIdError);
@@ -788,9 +804,14 @@ export class FusionOrchestrator {
       return { status: "ignored" };
     }
 
-    const output = extractJudgeOutput(
-      snapshot.resultPayload ?? snapshot.statusPayload ?? payload,
-    );
+    const lifecyclePayload =
+      snapshot.resultPayload ?? snapshot.statusPayload ?? payload;
+    const lifecycleError = extractSubagentFailure(lifecyclePayload);
+    if (!hasLifecycleResults(lifecyclePayload) && lifecycleError) {
+      return this.failActiveRun(lifecycleError);
+    }
+
+    const output = extractJudgeOutput(lifecyclePayload);
     if (!output.ok) return this.failActiveRun(output.error);
 
     const judgeModel = this.activeProfile
@@ -849,12 +870,18 @@ export class FusionOrchestrator {
       );
     }
 
+    const statusIsTerminal =
+      isTerminalSubagentState(extractSubagentState(statusPayload)) ||
+      isTerminalFusionProgress(statusPayload);
+    const eventIsTerminal =
+      isTerminalSubagentState(extractSubagentState(input.eventPayload)) ||
+      isTerminalFusionProgress(input.eventPayload);
     const eventHasResults = hasResultsArray(input.eventPayload);
     if (eventPayloadMatches && eventHasResults) {
       return {
         statusPayload,
         resultPayload: input.eventPayload,
-        resultIsTerminal: true,
+        resultIsTerminal: eventIsTerminal || statusIsTerminal,
       };
     }
 
@@ -871,17 +898,14 @@ export class FusionOrchestrator {
     }
 
     if (hasResultsArray(statusPayload)) {
-      const resultIsTerminal =
-        eventPayloadMatches ||
-        isTerminalSubagentState(extractSubagentState(statusPayload));
       return {
         statusPayload,
         resultPayload: statusPayload,
-        resultIsTerminal,
+        resultIsTerminal: statusIsTerminal,
       };
     }
 
-    if (isTerminalSubagentState(extractSubagentState(statusPayload))) {
+    if (statusIsTerminal) {
       return {
         statusPayload,
         resultPayload: statusPayload,
@@ -893,9 +917,7 @@ export class FusionOrchestrator {
       return {
         statusPayload,
         resultPayload: input.eventPayload,
-        resultIsTerminal: isTerminalSubagentState(
-          extractSubagentState(input.eventPayload),
-        ),
+        resultIsTerminal: eventIsTerminal,
       };
     }
 
@@ -1525,6 +1547,38 @@ function isTerminalSubagentState(state: string | undefined): boolean {
   );
 }
 
+function hasLifecycleResults(payload: unknown): boolean {
+  return hasResultsArray(payload) || findStepsArray(payload).length > 0;
+}
+
+function extractSubagentFailure(payload: unknown): string | undefined {
+  if (!isRecord(payload)) return undefined;
+  const direct = firstNonBlankString(payload.error, payload.errorMessage);
+  if (direct) return direct;
+  if (isRecord(payload.details)) {
+    const detailsError = firstNonBlankString(
+      payload.details.error,
+      payload.details.errorMessage,
+    );
+    if (detailsError) return detailsError;
+  }
+  if (payload.isError === true && Array.isArray(payload.content)) {
+    for (const item of payload.content) {
+      const contentText = isRecord(item)
+        ? firstNonBlankString(item.text)
+        : undefined;
+      if (contentText) return contentText;
+    }
+  }
+  const text = firstNonBlankString(
+    payload.text,
+    isRecord(payload.details) ? payload.details.text : undefined,
+  );
+  if (text && /^error(?:\s|:)/i.test(text)) return text;
+  if (isRecord(payload.data)) return extractSubagentFailure(payload.data);
+  return undefined;
+}
+
 function firstNonBlankStringFromPayload(payload: unknown): string | undefined {
   if (!isRecord(payload)) return undefined;
   const direct = firstNonBlankString(

package/src/run-store.ts

@@ -23,6 +23,7 @@ export type FusionRunSummary = Omit<
     | "id"
     | "prompt"
     | "profileName"
+    | "operationId"
     | "phase"
     | "createdAt"
     | "updatedAt"
@@ -39,6 +40,7 @@ export interface FusionRunStartInput {
   id?: string;
   prompt: string;
   profileName: string;
+  operationId?: string;
   phase?: Exclude<FusionPhase, FusionTerminalPhase>;
   createdAt?: number;
 }
@@ -96,6 +98,8 @@ export class FusionRunStoreError extends Error {
 export class FusionRunStore {
   private activeRun: FusionRun | undefined;
   private lastRunSummary: FusionRunSummary | undefined;
+  private readonly runsById = new Map<string, FusionRun>();
+  private readonly runIdsByOperationId = new Map<string, string>();
   private readonly now: () => number;
   private readonly idFactory: () => string;
   private readonly persistence: FusionRunStorePersistence | undefined;
@@ -116,22 +120,44 @@ export class FusionRunStore {
       : undefined;
   }
 
+  getRunById(id: string): FusionRun | undefined {
+    const run = this.runsById.get(id);
+    return run ? cloneRun(run) : undefined;
+  }
+
+  getRunByOperationId(operationId: string): FusionRun | undefined {
+    const runId = this.runIdsByOperationId.get(operationId);
+    return runId ? this.getRunById(runId) : undefined;
+  }
+
   startRun(input: FusionRunStartInput): FusionRun {
     if (this.activeRun) {
       throw new FusionRunStoreError(
         `Fusion run ${this.activeRun.id} is already active.`,
       );
     }
+    if (
+      input.operationId !== undefined &&
+      this.runIdsByOperationId.has(input.operationId)
+    ) {
+      throw new FusionRunStoreError(
+        `Fusion operation ${input.operationId} already has a run.`,
+      );
+    }
     const createdAt = input.createdAt ?? this.now();
     const run: FusionRun = {
       id: input.id ?? this.idFactory(),
       prompt: input.prompt,
       profileName: input.profileName,
+      ...(input.operationId !== undefined
+        ? { operationId: input.operationId }
+        : {}),
       phase: input.phase ?? "chain",
       createdAt,
       updatedAt: createdAt,
     };
     this.activeRun = run;
+    this.rememberRun(run);
     this.persistRun(run);
     return cloneRun(run);
   }
@@ -140,6 +166,7 @@ export class FusionRunStore {
     const active = this.requireActiveRun(id);
     const updated = applyPatch(active, patch, patch.updatedAt ?? this.now());
     this.activeRun = updated;
+    this.rememberRun(updated);
     this.persistRun(updated);
     return cloneRun(updated);
   }
@@ -171,6 +198,7 @@ export class FusionRunStore {
     const summary = toRunSummary(finished);
     this.activeRun = undefined;
     this.lastRunSummary = summary;
+    this.rememberRun(finished);
     this.persistRun(summary);
     return cloneRun(finished);
   }
@@ -178,7 +206,12 @@ export class FusionRunStore {
   restoreFromEntries(
     entries: readonly unknown[],
   ): FusionRunSummary | undefined {
-    const latestState = readLastFusionRunState(entries);
+    const states = readFusionRunStates(entries);
+    this.runsById.clear();
+    this.runIdsByOperationId.clear();
+    for (const state of states) this.rememberRun(state);
+
+    const latestState = states.at(-1);
     const summary = readLastFusionRunSummary(entries);
     this.activeRun =
       latestState && !isTerminalPhase(latestState.phase)
@@ -208,6 +241,16 @@ export class FusionRunStore {
     this.persistence?.appendEntry(FUSION_RUN_ENTRY_TYPE, cloneRun(run));
   }
 
+  private rememberRun(run: FusionRun): void {
+    this.runsById.set(run.id, cloneRun(run));
+    if (
+      run.operationId !== undefined &&
+      !this.runIdsByOperationId.has(run.operationId)
+    ) {
+      this.runIdsByOperationId.set(run.operationId, run.id);
+    }
+  }
+
   private requireActiveRun(id: string): FusionRun {
     if (!this.activeRun) {
       throw new FusionRunStoreError("No active fusion run.");
@@ -325,6 +368,7 @@ function toRunSummary(
     id: run.id,
     prompt: run.prompt,
     profileName: run.profileName,
+    ...(run.operationId !== undefined ? { operationId: run.operationId } : {}),
     phase: run.phase,
     createdAt: run.createdAt,
     updatedAt: run.updatedAt,
@@ -341,6 +385,7 @@ function cloneRun(run: FusionRun): FusionRun {
     id: run.id,
     prompt: run.prompt,
     profileName: run.profileName,
+    ...(run.operationId !== undefined ? { operationId: run.operationId } : {}),
     phase: run.phase,
     createdAt: run.createdAt,
     updatedAt: run.updatedAt,
@@ -396,6 +441,9 @@ function isFusionRunState(value: unknown): value is FusionRun {
   if (!isNonEmptyString(value.id)) return false;
   if (typeof value.prompt !== "string") return false;
   if (!isNonEmptyString(value.profileName)) return false;
+  if (value.operationId !== undefined && !isNonEmptyString(value.operationId)) {
+    return false;
+  }
   if (!isFusionPhase(value.phase)) return false;
   if (!isFiniteNumber(value.createdAt)) return false;
   if (!isFiniteNumber(value.updatedAt)) return false;

package/src/status.ts

@@ -92,6 +92,20 @@ export function formatProgressCounts(progress: FusionProgressCounts): string {
   return `${progress.completed}/${total} done, ${progress.running} running, ${progress.failed} failed`;
 }
 
+export function isTerminalFusionProgress(payload: unknown): boolean {
+  const progressPayload = findTerminalProgressPayload(payload);
+  const progress = progressPayload
+    ? extractFusionProgressCounts(progressPayload)
+    : undefined;
+  return Boolean(
+    progress &&
+    progress.total !== undefined &&
+    progress.total > 0 &&
+    progress.pending === 0 &&
+    progress.running === 0,
+  );
+}
+
 type ProgressStatus = "pending" | "running" | "completed" | "failed";
 
 function findProgressContainer(
@@ -116,6 +130,23 @@ function findProgressContainer(
   return undefined;
 }
 
+function findTerminalProgressPayload(payload: unknown): unknown {
+  if (!isRecord(payload)) return undefined;
+  if (Array.isArray(payload.progress)) return { progress: payload.progress };
+  if (Array.isArray(payload.steps)) return { steps: payload.steps };
+  if (isRecord(payload.details)) {
+    if (Array.isArray(payload.details.progress)) {
+      return { progress: payload.details.progress };
+    }
+    if (Array.isArray(payload.details.steps)) {
+      return { steps: payload.details.steps };
+    }
+  }
+  return isRecord(payload.data)
+    ? findTerminalProgressPayload(payload.data)
+    : undefined;
+}
+
 function classifyProgressItem(value: unknown): ProgressStatus {
   if (!isRecord(value)) return "failed";
   if (value.success === true) return "completed";

package/src/types.ts

@@ -78,6 +78,7 @@ export interface FusionConfig {
 export interface ParsedFusionArgs {
   prompt: string;
   profile?: string;
+  operationId?: string;
 }
 
 export interface PanelOutput {
@@ -120,6 +121,7 @@ export interface FusionRun {
   id: string;
   prompt: string;
   profileName: string;
+  operationId?: string;
   phase: FusionPhase;
   createdAt: number;
   updatedAt: number;