@pi-archimedes/core 2.8.0 → 2.9.1

package/README.md

@@ -1,8 +1,8 @@
 # @pi-archimedes/core
 
-**A terminal worth spending your day in — plus the plumbing that keeps the rest of the suite talking.**
+**Foundational non-UI runtime for the Pi Archimedes suite.**
 
-Core is the face of every session: the animated splash screen on launch, the framed editor where you type, the border spinner that works while the agent works, and clean, labelled thinking blocks. Under the surface it runs the shared event bus through which the other components pass costs, todos, and questions — and the text, colour, and settings utilities they all build on.
+Core is the foundational runtime that keeps the rest of the suite talking. It provides the shared event bus, message handling, settings-io, pure text/color/tool-render utilities, overlay chrome, and a startup profiler.
 
 ## Install
 
@@ -12,7 +12,7 @@ Standalone:
 pi install npm:@pi-archimedes/core
 ```
 
-Or the full suite instead (which includes core and the ten optional components):
+Or the full suite instead:
 
 ```bash
 pi install npm:pi-archimedes
@@ -24,37 +24,16 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0:
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent
 ```
 
-After installing Pi, choose one installation command above, then `cd` into your project and run `pi`. Inside the session, `/login` signs you into a supported provider and `/model` picks a model; the full walkthrough, including API-key setup, is in the repo's [setup section](https://github.com/danielcherubini/pi-archimedes#setup) and Pi's own [quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md). A session that's already running picks up the extension with `/reload`.
+After installing Pi, choose one installation command above, then `cd` into your project and run `pi`. Inside the session, `/login` signs you into a supported provider and `/model` picks a model.
 
 ## What you get
 
-- **Splash screen** — an animated greeting when the session launches, in one of nine reveal styles (`diagonal`, `top-right`, `bottom-left`, `bottom-right`, `center-out`, `wave`, `horizontal`, `vertical`, `vertical-up`).
-- **Framed editor** — your input in a clean bordered frame, with a double-press guard on the quit key (`Ctrl+C` by default) so a stray keystroke doesn't end the session.
-- **Working spinner on the border** — one of ten animating styles (`pendulum`, `typing`, `pulse`, `marquee`, `wave-rows`, `columns`, `cascade`, `diagonal-swipe`, `rain`, `sparkle`) traces the editor frame while the agent works, replacing Pi's native "Working" line. When `editorSpinLabel` is at its default, the label switches to a random quip per busy episode — re-picked on a subtle random 15–45 s timer while long episodes continue; set a custom value to pin a label (an empty value still hides it).
-- **Thinking blocks** — chain-of-thought output gets a consistent label, colour, and layout; `codeUnindent` strips the common indentation so code in reasoning reads flush.
 - **The bus** (`@pi-archimedes/core/bus`) — a global pub/sub event system: `COST_UPDATE`, `ASK_REQUEST`, `TODOS_UPDATE`, `TODOS_CLEAR`… subagent costs flow to the footer through it, subagent todos to the task board, subagent questions to the ask UI.
 - **Shared utilities** — text truncation and width measurement, colour formatting, settings I/O, and startup profiling.
-
-## Settings
-
-Settings live in `~/.pi/agent/settings.json` under `archimedes.core`. The file is **strict JSON — no comments or trailing commas** (unlike the MCP server config files, which accept both).
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `editorSpinBorder` | bool | `true` | Show the animated border spinner while the agent works |
-| `editorSpinStyle` | string | `pendulum` | One of the ten spinner styles |
-| `editorSpinSpeed` | string | `normal` | `slow`, `normal`, or `fast` |
-| `editorSpinLabel` | string | `Working` | Label shown alongside the border spinner; the default is replaced by a random quip per busy episode (re-picked on a subtle random 15–45 s timer while long episodes continue) — set a custom value to pin it (empty still hides it) |
-| `animationStyle` | string | `vertical-up` | Splash-screen reveal style (the nine styles above) |
-| `labelText` | string | `Thinking...` | Prefix before thinking blocks |
-| `labelColor` | string | `255,215,0` | RGB string for the thinking label |
-| `codeUnindent` | bool | `true` | Strip common indentation from code blocks in thinking sections |
-| `mutedTheme` | bool | `false` | Stored, but **not yet effective** — the current thinking renderer doesn't consult it, so treat it as a pending toggle |
-
-In the suite, `/archimedes` offers panel controls for the settings that have them; `/reload` applies any that are read at startup.
+- **Overlay Chrome** — shared base for UI components.
 
 ## Part of the suite
 
-In [pi-archimedes](https://github.com/danielcherubini/pi-archimedes), core is always registered — it isn't one of the `/plugins` toggles — and it underpins what the other components share: the bus that feeds subagent costs to the footer, subagent todos to the task board, and subagent questions to the ask UI, plus the chrome and colour utilities the TUIs use. The diff renderer is standalone and does not depend on core's chrome — it only shares the suite when it loads.
+In [pi-archimedes](https://github.com/danielcherubini/pi-archimedes), core is always registered — it isn't one of the `/plugins` toggles — and it underpins what the other components share: the bus that feeds subagent costs to the footer, subagent todos to the task board, and subagent questions to the ask UI. The diff renderer is standalone and does not depend on core's chrome — it only shares the suite when it loads.
 
 ← [Back to pi-archimedes](https://github.com/danielcherubini/pi-archimedes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -9,7 +9,7 @@
   "keywords": [
     "pi-package"
   ],
-  "description": "Core UI modules for pi-archimedes: editor, message, startup, thinking",
+  "description": "Core primitives for pi-archimedes",
   "files": [
     "src"
   ],
@@ -17,6 +17,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./bridge": "./src/bridge/index.ts",
+    "./bridge/channel": "./src/bridge/channel.ts",
     "./bus": "./src/bus.ts",
     "./chrome": "./src/chrome.ts",
     "./text": "./src/text.ts",
@@ -28,12 +29,12 @@
     "./tool-render": "./src/tool-render.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0"
+    "@earendil-works/pi-coding-agent": ">=0.85.0",
+    "@earendil-works/pi-tui": ">=0.85.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/bridge/channel.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  request,
+  configure,
+  __resetForTests,
+  BridgeCancelledError,
+  BridgeTransportError,
+} from "./channel.js";
+
+// The cancel contract between core and the subagent package is TYPED:
+// dispatchViaBridge matches `instanceof BridgeCancelledError` (not the
+// message string). These tests pin that contract at the source.
+
+afterEach(() => {
+  __resetForTests();
+});
+
+describe("request() cancel contract", () => {
+  it("cancel() settles the promise deterministically with a BridgeCancelledError", async () => {
+    // Unreachable socket path: the connect fails asynchronously; the
+    // synchronous cancel() wins the race and settles first.
+    configure({ active: true, socketPath: "/tmp/bridge-does-not-exist-xyz" });
+    const handle = request("test_method", { a: 1 });
+    handle.cancel();
+    await expect(handle.promise).rejects.toBeInstanceOf(BridgeCancelledError);
+    await expect(handle.promise).rejects.toHaveProperty("name", "BridgeCancelledError");
+  });
+
+  it("a BridgeCancelledError is NOT a BridgeTransportError (never a fork-fallback trigger)", async () => {
+    configure({ active: true, socketPath: "/tmp/bridge-does-not-exist-xyz" });
+    const handle = request("test_method", { a: 1 });
+    handle.cancel();
+    const err = await handle.promise.catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(BridgeCancelledError);
+    expect(err).not.toBeInstanceOf(BridgeTransportError);
+  });
+
+  it("cancel() is idempotent (a second settle is a no-op, same error)", async () => {
+    configure({ active: true, socketPath: "/tmp/bridge-does-not-exist-xyz" });
+    const handle = request("test_method", { a: 1 });
+    handle.cancel();
+    handle.cancel();
+    const err = await handle.promise.catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(BridgeCancelledError);
+  });
+
+  it("an unreachable channel (no cancel) still rejects with a BridgeTransportError", async () => {
+    configure({ active: true, socketPath: undefined });
+    const handle = request("test_method", { a: 1 });
+    await expect(handle.promise).rejects.toBeInstanceOf(BridgeTransportError);
+  });
+});

package/src/bridge/channel.ts

@@ -6,16 +6,63 @@
 //   - sendEvent: best-effort push (initial + 2 retries at 500/1500 ms, then
 //     drop; coalesced to at most one in-flight connection per event type).
 //   - request: interactive (a single request/response over one connection;
-//     5-minute timeout (unref'd) → immediate reject + socket destroy;
+//     5-minute timeout by default (unref'd, overridable per-request —
+//     `timeoutMs: null` = no timeout) → immediate reject + socket destroy;
 //     connection close = immediate cancel; unreachable channel → fail fast).
 //     Returns a cancellable handle ({ promise, cancel }).
 //
 // The `active` flag does NOT depend on a successful connection (lazy,
 // per-message connect). A failed connect is a no-op.
+//
+// Failure taxonomy: a response frame carrying `error` rejects with a plain
+// Error (the desktop answered — it is alive and the outcome is authoritative);
+// a transport-level failure (unreachable socket / mid-connection error / a
+// clean close before any response) rejects with BridgeTransportError — the
+// subagent's fallback trigger. A timeout is ALSO "no response frame" but is
+// deliberately a plain Error (ambiguous liveness — the desktop may still be
+// working on a long request) so it can never trigger a fork fallback (double
+// execution); a deliberate cancel() is a plain Error for the same reason — a
+// cancel must never fork either.
 
 import * as net from "node:net";
 import { randomUUID } from "node:crypto";
 
+/**
+ * A transport-level failure: the connection never delivered a response
+ * frame (unreachable socket / ECONNREFUSED, a mid-connection error, or a
+ * clean close before any response — the desktop is effectively gone).
+ * Distinct from a response-carrying error (the desktop answered with an
+ * `error` — it is alive and the outcome is authoritative).
+ *
+ * A timeout is also "no response frame" but is DELIBERATELY NOT a
+ * BridgeTransportError: it is an ambiguous-liveness outcome (the desktop may
+ * still be working on a long request) and must never trigger a fork
+ * fallback (double execution) — it rejects with a plain Error. Callers that
+ * cannot tolerate a 5-minute silence should pass a smaller `timeoutMs`.
+ */
+export class BridgeTransportError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BridgeTransportError";
+  }
+}
+
+/**
+ * A deliberate cancel: the caller (the tool's AbortSignal, or the desktop's
+ * lifecycle via the abort wiring) aborted the request. Distinct from
+ * BridgeTransportError (the desktop is gone — the fork-fallback trigger) and
+ * from a timeout (ambiguous liveness): the request was intentionally
+ * aborted, so callers map it to a FAILED outcome — never a fork fallback.
+ * This class is the cancel contract between core and the subagent package
+ * (matched with `instanceof`, NOT the message string).
+ */
+export class BridgeCancelledError extends Error {
+  constructor() {
+    super("bridge request cancelled");
+    this.name = "BridgeCancelledError";
+  }
+}
+
 let active = false;
 let socketPath: string | undefined;
 let seq = 0; // starts at 0; the first frame is seq: 1
@@ -161,7 +208,7 @@ function settle(event: string): void {
 export function request<T>(
   method: string,
   params: unknown,
-  opts?: { toolCallId?: string; source?: string },
+  opts?: { toolCallId?: string | undefined; source?: string; timeoutMs?: number | null | undefined },
 ): { promise: Promise<T>; cancel: () => void } {
   const id = randomUUID();
   const frame = {
@@ -177,17 +224,24 @@ export function request<T>(
   let settled = false;
   let socket: net.Socket | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
+  // The settle helper (assigned in the executor below — the executor runs
+  // synchronously, so it is assigned before any caller can invoke cancel()).
+  let finish: (err?: Error, value?: T) => void = () => {};
 
   const promise = new Promise<T>((resolve, reject) => {
     const target = socketTarget();
     if (!target) {
-      // Unreachable channel → fail fast.
+      // Unreachable channel → fail fast (a transport-level failure — the
+      // desktop is effectively gone, so the subagent's fallback trigger).
       settled = true;
-      reject(new Error("bridge channel unreachable"));
+      reject(new BridgeTransportError("bridge channel unreachable"));
       return;
     }
 
-    const finish = (err?: Error, value?: T) => {
+    finish = (err?: Error, value?: T) => {
+      // Idempotent: the socket's close handler (fired by the destroy below)
+      // must NOT double-settle a request already settled by a timeout or a
+      // deterministic cancel.
       if (settled) return;
       settled = true;
       if (timer) clearTimeout(timer);
@@ -196,11 +250,28 @@ export function request<T>(
       else resolve(value as T);
     };
 
-    // 5-minute timeout (unref'd) → immediate reject + socket destroy.
-    timer = setTimeout(() => {
-      finish(new Error("bridge request timed out"));
-    }, 5 * 60 * 1000);
-    timer.unref?.();
+    // Timeout: `timeoutMs: null` = NO timeout (skip the timer entirely —
+    // dispatch_subagent, whose cancel path is the desktop's lifecycle, not a
+    // timer); `timeoutMs: undefined` = the 5-minute default. Note: `??`
+    // cannot express this (it falls back for null AND undefined) — hence the
+    // explicit undefined check. A NEGATIVE value is clamped to 1 ms (the
+    // minimum setTimeout delay — `null`, not a negative, is the "never"
+    // case). The timer is unref'd so a pending request never keeps the
+    // process alive.
+    //
+    // A timeout is an AMBIGUOUS-LIVENESS outcome (the desktop may still be
+    // working on a long request) — it is deliberately NOT a
+    // BridgeTransportError, so it can never trigger a fork fallback (double
+    // execution); callers that cannot tolerate a 5-minute silence should pass
+    // a smaller `timeoutMs` or `null`.
+    const rawTimeoutMs = opts?.timeoutMs === undefined ? 5 * 60 * 1000 : opts!.timeoutMs;
+    if (rawTimeoutMs !== null) {
+      const delay = rawTimeoutMs < 0 ? 1 : rawTimeoutMs; // clamp negatives to the 1 ms minimum
+      timer = setTimeout(() => {
+        finish(new Error("bridge request timed out"));
+      }, delay);
+      timer.unref?.();
+    }
 
     socket = net.createConnection(target);
     const sock = socket; // capture non-undefined for the handlers below
@@ -226,17 +297,25 @@ export function request<T>(
         } catch { /* malformed line — ignore */ }
       }
     });
-    // error / close before a response → cancel.
-    sock.on("error", () => finish(new Error("bridge channel error")));
-    sock.on("close", () => finish(new Error("bridge channel closed before response")));
+    // error / close before a response → a transport-level failure (the
+    // desktop is effectively gone). A response frame carrying `error` still
+    // rejects with a plain Error — the desktop answered, so its outcome is
+    // authoritative (NOT a transport failure). (A deterministic cancel()
+    // settles first — the close it triggers is a no-op here.)
+    sock.on("error", () => finish(new BridgeTransportError("bridge channel error")));
+    sock.on("close", () => finish(new BridgeTransportError("bridge channel closed before response")));
   });
 
-  // cancel() closes the socket (→ the promise rejects with a cancel error) and
-  // is idempotent. A bare Promise cannot be cancelled, so the ASK_CANCEL path
-  // needs this surface.
+  // cancel() settles the promise DETERMINISTICALLY with a BridgeCancelledError
+  // (NOT a BridgeTransportError): a deliberate cancel is NOT "the desktop is
+  // gone", so a dispatch-like caller must map it to a FAILED outcome, never a
+  // fork fallback (a deliberate cancel must never fork — forking would spawn
+  // a fresh child pi for a task the user just cancelled). The socket destroy
+  // (inside finish) still delivers the desktop's EOF → the subagent session
+  // cancels. Idempotent: finish() no-ops a second settle, and the close
+  // handler (fired by the destroy) is a no-op once settled.
   const cancel = () => {
-    if (settled) return;
-    try { socket?.destroy(); } catch { /* already closed */ }
+    finish(new BridgeCancelledError());
   };
 
   return { promise, cancel };

package/src/bridge/index.test.ts

@@ -12,9 +12,10 @@ import {
   confirm,
   password,
   registerBridge,
+  dispatch,
   BridgeInactiveError,
 } from "./index.js";
-import { configure, sendEvent, request, __resetForTests as resetChannel } from "./channel.js";
+import { configure, sendEvent, request, BridgeTransportError, __resetForTests as resetChannel } from "./channel.js";
 import {
   state,
   start,
@@ -175,6 +176,11 @@ describe("inactive API", () => {
     clearBridgeEnv();
     await expect(password({ command: "sudo apt install", reason: "test" })).resolves.toBe("");
   });
+
+  it("dispatch throws BridgeInactiveError", () => {
+    clearBridgeEnv();
+    expect(() => dispatch({ agentName: "a", task: "t", systemPrompt: null, model: null, thinking: null, tools: null }, "tool-1")).toThrow(BridgeInactiveError);
+  });
 });
 
 // ── 3. State machine ─────────────────────────────────────────────────────
@@ -382,6 +388,146 @@ describe("request round-trip + cancel", () => {
   });
 });
 
+// ── 8b. request timeout override + BridgeTransportError ─────────────────
+
+describe("request timeout override + BridgeTransportError", () => {
+  it("timeoutMs: null does NOT reject at 5 minutes (no timer)", async () => {
+    vi.useFakeTimers();
+    try {
+      const sockPath = tempSocketPath();
+      const server = await startServer(sockPath, () => {
+        /* accept but never respond */
+      });
+
+      configure({ active: true, socketPath: sockPath });
+      const { promise } = request("dispatch_subagent", { task: "x" }, { toolCallId: "t1", source: "main", timeoutMs: null });
+      let settled = false;
+      promise.then(() => { settled = true; }, () => { settled = true; });
+
+      // Advance 6 minutes of fake time — the 5-minute timer (if any) would
+      // have fired. The promise must still be pending.
+      await vi.advanceTimersByTimeAsync(6 * 60 * 1000);
+      expect(settled).toBe(false);
+
+      server.close();
+      try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("the default (timeoutMs omitted) still rejects after 5 minutes", async () => {
+    vi.useFakeTimers();
+    try {
+      const sockPath = tempSocketPath();
+      const server = await startServer(sockPath, () => {
+        /* accept but never respond */
+      });
+
+      configure({ active: true, socketPath: sockPath });
+      const { promise } = request("ask", { questions: [makeQuestion()] });
+      // Attach the handler BEFORE advancing (a rejection during the advance
+      // with no handler attached would be an unhandled rejection).
+      const outcome = promise.then(() => null, (e: unknown) => e);
+
+      await vi.advanceTimersByTimeAsync(6 * 60 * 1000);
+      const err = await outcome;
+      expect(err).toBeInstanceOf(Error);
+      expect((err as Error).message).toBe("bridge request timed out");
+
+      server.close();
+      try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("a negative timeoutMs is clamped to the 1 ms minimum (the timer still fires — NOT 'no timer')", async () => {
+    vi.useFakeTimers();
+    try {
+      const sockPath = tempSocketPath();
+      const server = await startServer(sockPath, () => {
+        /* accept but never respond */
+      });
+
+      configure({ active: true, socketPath: sockPath });
+      const { promise } = request("ask", { questions: [makeQuestion()] }, { timeoutMs: -5000 });
+      // `null` is the "never" case; a negative value is clamped to the 1 ms
+      // minimum, so a short advance must fire the timeout (not skip it).
+      const outcome = promise.then(() => null, (e: unknown) => e);
+
+      await vi.advanceTimersByTimeAsync(2);
+      const err = await outcome;
+      expect(err).toBeInstanceOf(Error);
+      expect((err as Error).message).toBe("bridge request timed out");
+
+      server.close();
+      try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("a mid-connection close (no response frame) rejects with a BridgeTransportError", async () => {
+    const sockPath = tempSocketPath();
+    const server = net.createServer((socket) => {
+      // Accept then destroy — the desktop is effectively gone.
+      socket.destroy();
+    });
+    await new Promise<void>((resolve) => server.listen(sockPath, resolve));
+
+    configure({ active: true, socketPath: sockPath });
+    const { promise } = request("ask", { questions: [makeQuestion()] });
+    const err = await promise.catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(BridgeTransportError);
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("a response-carrying error frame rejects with a plain Error (NOT BridgeTransportError)", async () => {
+    const sockPath = tempSocketPath();
+    const server = net.createServer((socket) => {
+      let buffer = "";
+      socket.on("data", (chunk: Buffer) => {
+        buffer += chunk.toString("utf-8");
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            const msg = JSON.parse(trimmed) as { type?: string; id?: string };
+            if (msg.type === "request" && msg.id) {
+              socket.write(JSON.stringify({ v: 1, type: "response", id: msg.id, error: "cancelled" }) + "\n");
+            }
+          } catch { /* malformed — ignore */ }
+        }
+      });
+      socket.on("error", () => { /* connection dropped */ });
+    });
+    await new Promise<void>((resolve) => server.listen(sockPath, resolve));
+
+    configure({ active: true, socketPath: sockPath });
+    const { promise } = request("dispatch_subagent", { task: "x" }, { toolCallId: "t1", source: "main", timeoutMs: null });
+    const err = await promise.catch((e: unknown) => e);
+    // The desktop answered — it is alive and the outcome is authoritative.
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(BridgeTransportError);
+    expect((err as Error).message).toBe("cancelled");
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("an unreachable channel (no socket target) rejects with a BridgeTransportError", async () => {
+    configure({ active: true, socketPath: "/tmp/definitely-does-not-exist-bridge2.sock" });
+    const { promise } = request("ask", { questions: [makeQuestion()] });
+    const err = await promise.catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(BridgeTransportError);
+  });
+});
+
 // ── 6. seq counter ───────────────────────────────────────────────────────
 
 describe("seq counter", () => {

package/src/bridge/index.ts

@@ -14,6 +14,8 @@ import type { AskResponsePayload, AskRequestPayload } from "../bus.js";
 import * as channel from "./channel.js";
 import * as events from "./events.js";
 
+export { BridgeTransportError, BridgeCancelledError } from "./channel.js";
+
 export class BridgeInactiveError extends Error {
   constructor() {
     super("bridge is not active");
@@ -30,7 +32,54 @@ function eventsState(): "working" | "idle" | "blocked" {
 }
 
 export function getBridge() {
-  return { active: channelActive(), ask, confirm, password, state: eventsState };
+  return { active: channelActive(), ask, confirm, password, dispatch, state: eventsState };
+}
+
+/**
+ * Delegate a subagent task to the Client (desktop) instead of forking a
+ * child pi process. The desktop runs the subagent session (a full ACP
+ * session on its worker runtime) and answers with the final output +
+ * metrics.
+ *
+ * The request opts OUT of the 5-minute timeout (`timeoutMs: null`): the
+ * desktop's lifecycle (parent close / EOF / app exit) is the cancel path —
+ * the tool's AbortSignal cancels the request (the promise settles
+ * deterministically with a BridgeCancelledError — NOT a
+ * BridgeTransportError, so it can never trigger a fork fallback) and the
+ * socket close delivers the desktop's EOF → the subagent session cancels.
+ * An unreachable bridge rejects with BridgeTransportError (the subagent's
+ * fork-fallback trigger); a response-carrying `error` (incl. the terminal
+ * `"cancelled"` frame) is authoritative and never a fallback.
+ */
+export interface DispatchParams {
+  agentName: string;
+  task: string;
+  systemPrompt: string | null;
+  model: string | null;
+  thinking: string | null;
+  tools: string[] | null;
+}
+
+export interface DispatchResult {
+  output: string;
+  metrics: { inputTokens: number; outputTokens: number; cost: number; durationMs: number };
+}
+
+export function dispatch(params: DispatchParams, toolCallId: string | undefined, signal?: AbortSignal): Promise<DispatchResult> {
+  if (!channelActive()) throw new BridgeInactiveError();
+  const handle = channel.request<DispatchResult>("dispatch_subagent", params, { toolCallId, source: "main", timeoutMs: null });
+  if (signal) {
+    // Same abort wiring as ask (see there for the full rationale): a
+    // pre-aborted signal cancels immediately, the listener is removed on
+    // settle via the .then(onFulfilled, onRejected) form.
+    if (signal.aborted) handle.cancel();
+    else signal.addEventListener("abort", handle.cancel, { once: true });
+    handle.promise.then(
+      () => { signal?.removeEventListener("abort", handle.cancel); },
+      () => { signal?.removeEventListener("abort", handle.cancel); },
+    );
+  }
+  return handle.promise;
 }
 
 /**
@@ -48,7 +97,8 @@ export function ask(params: { questions: AskRequestPayload["questions"] }, toolC
     // "abort" event (it fires exactly once, at abort time), so an addEventListener
     // alone would leave the request lingering until the Client responds or the
     // 5-minute timeout — call cancel() directly in that case. cancel() is
-    // idempotent and settles the promise via the socket-close handler, so both
+    // idempotent and settles the promise deterministically (the
+    // socket-close handler it triggers is a no-op once settled), so both
     // branches coexist safely. The listener is removed on settle; the
     // .then(onFulfilled, onRejected) form (not .finally) avoids an unhandled
     // rejection from the derived promise when the request rejects.