@pi-archimedes/core 2.7.3 → 2.9.0

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.7.3",
+  "version": "2.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -9,13 +9,15 @@
   "keywords": [
     "pi-package"
   ],
-  "description": "Core UI modules for pi-archimedes: editor, message, startup, thinking",
+  "description": "Core primitives for pi-archimedes",
   "files": [
     "src"
   ],
   "main": "./src/index.ts",
   "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",
@@ -27,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

@@ -0,0 +1,322 @@
+// ── Bridge channel (connection layer — herdr + subagent precedents) ──────
+//
+// The Client (desktop) is the server (a 0600 Unix socket / Windows named
+// pipe); the suite is the client (an ephemeral net.createConnection per
+// message, herdr-style). This module owns the socket lifecycle:
+//   - 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 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
+
+// Generation guard: bumped by __resetForTests so a stale retry chain (a retry
+// setTimeout scheduled on a detached entry after a reset) dies at the reset
+// boundary. Without it, the per-attempt ackTimer is never tracked in the entry
+// and the socket's close → finish(false) fires AFTER the reset, scheduling a
+// fresh retry timer on the now-detached entry — a timer nothing will ever
+// clear (it would also cross-wire into a fresh same-event entry from the next
+// test). A stale chain is a no-op when the timer fires (g !== generation).
+let generation = 0;
+
+// Coalescing guard: at most one in-flight connection per event type. While one
+// is in flight, a newer sendEvent for the same event queues its payload
+// (latest wins) and it is sent when the current one settles.
+const inFlight = new Map<string, { queued: unknown; timer?: ReturnType<typeof setTimeout> }>();
+
+// Track open sockets so __resetForTests can reap them (prevents test hangs).
+const openSockets = new Set<net.Socket>();
+
+export function configure(opts: { active: boolean; socketPath: string | undefined }): void {
+  active = opts.active;
+  socketPath = opts.socketPath;
+}
+
+export function isActive(): boolean {
+  return active;
+}
+
+function socketTarget(): string | undefined {
+  // env value is the bare pipe name on Windows (the Client contract — unlike
+  // PI_SUBAGENT_SOCKET, which is a full pipe path).
+  if (!socketPath) return undefined;
+  return process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+}
+
+function trackSocket(socket: net.Socket): void {
+  openSockets.add(socket);
+  socket.on("close", () => openSockets.delete(socket));
+}
+
+/** Test seam: reset the module singletons and reap any open sockets. */
+export function __resetForTests(): void {
+  active = false;
+  socketPath = undefined;
+  seq = 0;
+  generation++; // kill any stale retry chain scheduled on a detached entry
+  for (const entry of inFlight.values()) {
+    if (entry.timer) clearTimeout(entry.timer);
+  }
+  inFlight.clear();
+  for (const socket of openSockets) {
+    try { socket.destroy(); } catch { /* already closed */ }
+  }
+  openSockets.clear();
+}
+
+// ── Best-effort push ─────────────────────────────────────────────────────
+
+export function sendEvent(event: string, payload: unknown): void {
+  const existing = inFlight.get(event);
+  if (existing) {
+    existing.queued = payload; // latest wins
+    return;
+  }
+  inFlight.set(event, { queued: undefined });
+  runAttempt(event, 0, payload);
+}
+
+function runAttempt(event: string, attempt: number, payload: unknown): void {
+  const entry = inFlight.get(event);
+  if (!entry) return;
+  // Consume the latest queued payload (latest wins).
+  const framePayload = entry.queued !== undefined ? entry.queued : payload;
+  entry.queued = undefined;
+
+  const target = socketTarget();
+  if (!target) {
+    settle(event); // unreachable channel → no-op
+    return;
+  }
+
+  const frame = { v: 1, type: "push", seq: ++seq, event, payload: framePayload };
+  const socket = net.createConnection(target);
+  trackSocket(socket);
+
+  let done = false;
+  const finish = (ok: boolean) => {
+    if (done) return;
+    done = true;
+    clearTimeout(ackTimer);
+    try { socket.destroy(); } catch { /* already closed */ }
+    if (ok) {
+      settle(event);
+    } else if (attempt < 2) {
+      // Retry: initial → 500 ms → 1500 ms → drop.
+      const delay = attempt === 0 ? 500 : 1500;
+      const g = generation; // generation guard: a stale chain (a reset happened
+      // between scheduling and firing) is a no-op when it fires — the timer
+      // dies at the reset boundary instead of leaking a retry on a detached
+      // entry (the close → finish(false) that schedules it fires AFTER reset).
+      const timer = setTimeout(() => {
+        if (g !== generation) return;
+        runAttempt(event, attempt + 1, framePayload);
+      }, delay);
+      timer.unref?.();
+      entry.timer = timer;
+    } else {
+      settle(event);
+    }
+  };
+
+  // No-ack window: if the connection is alive but never acks, treat it as a
+  // failure and retry. (The Client acks promptly after receiving a push.)
+  const ackTimer = setTimeout(() => finish(false), 1000);
+  ackTimer.unref?.();
+
+  socket.on("connect", () => {
+    try { socket.write(JSON.stringify(frame) + "\n"); } catch { finish(false); }
+  });
+  socket.on("data", () => finish(true)); // first data = the ack line
+  socket.on("error", () => finish(false));
+  socket.on("close", () => finish(false));
+}
+
+function settle(event: string): void {
+  const entry = inFlight.get(event);
+  if (!entry) return;
+  if (entry.timer) { clearTimeout(entry.timer); delete entry.timer; }
+  if (entry.queued !== undefined) {
+    // A newer payload accumulated while in flight — send it (latest wins).
+    const queued = entry.queued;
+    entry.queued = undefined;
+    runAttempt(event, 0, queued);
+  } else {
+    inFlight.delete(event);
+  }
+}
+
+// ── Interactive request ───────────────────────────────────────────────────
+
+export function request<T>(
+  method: string,
+  params: unknown,
+  opts?: { toolCallId?: string | undefined; source?: string; timeoutMs?: number | null | undefined },
+): { promise: Promise<T>; cancel: () => void } {
+  const id = randomUUID();
+  const frame = {
+    v: 1,
+    type: "request",
+    id,
+    method,
+    source: opts?.source ?? "main",
+    toolCallId: opts?.toolCallId,
+    params,
+  };
+
+  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 (a transport-level failure — the
+      // desktop is effectively gone, so the subagent's fallback trigger).
+      settled = true;
+      reject(new BridgeTransportError("bridge channel unreachable"));
+      return;
+    }
+
+    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);
+      try { socket?.destroy(); } catch { /* already closed */ }
+      if (err) reject(err);
+      else resolve(value as T);
+    };
+
+    // 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
+    trackSocket(sock);
+    let buffer = "";
+
+    sock.on("connect", () => {
+      try { sock.write(JSON.stringify(frame) + "\n"); } catch { finish(new Error("failed to write request")); }
+    });
+    sock.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; result?: T; error?: string };
+          if (msg.type === "response" && msg.id === id) {
+            if (msg.error !== undefined) finish(new Error(msg.error));
+            else finish(undefined, msg.result);
+          }
+        } catch { /* malformed line — ignore */ }
+      }
+    });
+    // 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() 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 = () => {
+    finish(new BridgeCancelledError());
+  };
+
+  return { promise, cancel };
+}

package/src/bridge/events.ts

@@ -0,0 +1,197 @@
+// ── Bridge events (bus subscriptions — the state machine + subagent
+//    forwarding + push events) ─────────────────────────────────────────────
+//
+// Subscribes the SIX real bus events (nothing emits agent_start/agent_settled/
+// session_start on the bus — those are pi extension events dispatched via
+// pi.on(...) and handled in registerBridge). Bus event names map to wire names
+// as explicit literals at each call site (no lookup table, no string surgery):
+//   COST_UPDATE → cost_update, TODOS_UPDATE → todos_update, TODOS_CLEAR →
+//   todos_clear. The ASK_* trio is not forwarded as pushes of their own —
+//   ASK_REQUEST drives the refcount + subagent forwarding, ASK_CANCEL cancels
+//   the pending Client request, and ASK_RESPONSE additionally triggers a
+//   `state` push (refcount-- + pushState).
+//
+// The bridge is the SOLE emitter of child-path ASK_RESPONSE (spawn.ts only
+// signals via ASK_CANCEL). Every forwarded ASK_REQUEST is eventually paired
+// with an ASK_RESPONSE (success, error, timeout, or ASK_CANCEL) so the
+// refcount never leaks.
+//
+// start() is one-way (no teardown counterpart to channel.configure({active:
+// false})). That's safe today because bridge activation is a process-constant
+// (isBridgeMode is evaluated once at session_start and never changes within a
+// process) — a future mixed-mode change (flipping active per session) would
+// need a stop() counterpart or it would leak the bus subscriptions.
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getBus, Events } from "../bus.js";
+import { sendEvent, request } from "./channel.js";
+
+let refcount = 0;
+let settled = false;
+let started = false; // the start() idempotency guard (sole writer is start())
+let sessionCtx: ExtensionContext | undefined;
+
+const pending = new Map<string, { source: string; toolCallId?: string; cancel: () => void }>();
+const unsubscribers: Array<() => void> = [];
+
+export function state(): "working" | "idle" | "blocked" {
+  return refcount > 0 ? "blocked" : (settled ? "idle" : "working");
+}
+
+function pushState(): void {
+  sendEvent("state", { state: state() });
+}
+
+// ── Pi extension events (NOT bus events — nothing emits them on the bus;
+//    they're dispatched by the extension runner via pi.on(...) and DO fire in
+//    RPC mode, since the RPC driver runs the same session machinery). ──────
+
+export function onAgentStart(): void {
+  settled = false;
+  pushState();
+}
+
+export function onAgentSettled(): void {
+  settled = true;
+  pushState();
+}
+
+export function onSessionStart(ctx?: ExtensionContext): void {
+  if (ctx) sessionCtx = ctx;
+  // Re-emitted on every session_start so a lost frame is recoverable; the
+  // payload echoes PI_ARCHIMEDES_BRIDGE_SESSION so the Client can assert the
+  // connection↔session mapping rather than infer it from the socket path.
+  // (Does NOT set `started` — start() is the sole writer of that flag, so a
+  // call-order flip can't turn start() into a permanent no-op; the session
+  // push is unconditional by design.)
+  sendEvent("session", { ...sessionRefs(), bridgeSession: process.env.PI_ARCHIMEDES_BRIDGE_SESSION });
+}
+
+function sessionRefs(): Record<string, unknown> {
+  const sm = sessionCtx?.sessionManager;
+  if (!sm) return {};
+  const refs: Record<string, unknown> = {};
+  try { refs.sessionId = sm.getSessionId?.(); } catch { /* */ }
+  try { refs.sessionFile = sm.getSessionFile?.(); } catch { /* */ }
+  try { refs.cwd = sm.getCwd?.(); } catch { /* */ }
+  try { refs.sessionName = sm.getSessionName?.(); } catch { /* */ }
+  return refs;
+}
+
+/**
+ * Subscribe the six real bus events. Idempotent (a re-start on /reload does
+ * not double-subscribe — guarded by the `started` flag; the unsubscribers are
+ * stored so a reset can tear them down).
+ */
+export function start(): void {
+  if (started) return;
+  started = true;
+
+  unsubscribers.push(getBus().on(Events.ASK_REQUEST, (payload: unknown) => {
+    const p = payload as {
+      source: string;
+      requestId: string;
+      toolCallId?: string;
+      questions: Array<{ id: string }>;
+    };
+    refcount++;
+    // A subagent ask is forwarded to the Client. A source === "main" ask is
+    // NOT forwarded here — the root's Client request comes from bridge.ask()
+    // directly; the bus event is for the refcount only.
+    if (p.source !== "main") {
+      const { cancel } = requestAskToClient(p);
+      const entry: { source: string; toolCallId?: string; cancel: () => void } = { source: p.source, cancel };
+      if (p.toolCallId !== undefined) entry.toolCallId = p.toolCallId;
+      pending.set(p.requestId, entry);
+    }
+  }));
+
+  unsubscribers.push(getBus().on(Events.ASK_RESPONSE, () => {
+    // Defensive floor: a spurious/duplicated ASK_RESPONSE must not drive the
+    // refcount negative — a negative count would make every later ask
+    // off-by-one (state reports working/idle while a prompt is pending, never
+    // blocked again). The floor keeps the machine honest. A decrement at
+    // refcount === 0 is a bug signal (by the module's own invariant, every
+    // ASK_REQUEST is paired) — log it so the protocol violation doesn't
+    // disappear without a trace.
+    if (refcount === 0) console.warn("[archimedes:bridge] unpaired ASK_RESPONSE received (refcount already 0)");
+    refcount = Math.max(0, refcount - 1);
+    pushState();
+  }));
+
+  unsubscribers.push(getBus().on(Events.ASK_CANCEL, (payload: unknown) => {
+    const p = payload as { requestId: string };
+    const entry = pending.get(p.requestId);
+    // cancel() closes the socket → the request rejects → the .catch below
+    // emits the cancelled ASK_RESPONSE → refcount-- + pending.delete. The
+    // ASK_CANCEL itself does not touch the refcount (no double-decrement).
+    if (entry) entry.cancel();
+  }));
+
+  // Bus payload types ARE the wire types — forward verbatim.
+  unsubscribers.push(getBus().on(Events.TODOS_UPDATE, (payload: unknown) => {
+    sendEvent("todos_update", payload);
+  }));
+
+  unsubscribers.push(getBus().on(Events.TODOS_CLEAR, (payload: unknown) => {
+    sendEvent("todos_clear", payload);
+  }));
+
+  unsubscribers.push(getBus().on(Events.COST_UPDATE, (payload: unknown) => {
+    sendEvent("cost_update", payload);
+  }));
+}
+
+/**
+ * Send a forwarded (subagent) ask to the Client and wire the response. The
+ * bridge is the sole emitter of child-path ASK_RESPONSE: on a settled ask it
+ * emits the Client's response verbatim; on a failure (error / timeout /
+ * cancel / child exit) it emits a cancelled ASK_RESPONSE so the refcount
+ * always pairs.
+ */
+function requestAskToClient(
+  payload: {
+    requestId: string;
+    source: string;
+    toolCallId?: string;
+    questions: Array<{ id: string }>;
+  },
+): { cancel: () => void } {
+  const opts: { toolCallId?: string; source?: string } = { source: payload.source };
+  if (payload.toolCallId !== undefined) opts.toolCallId = payload.toolCallId;
+  const handle = request<{
+    cancelled: boolean;
+    results: Array<{ id: string; selectedOptions: string[]; customInput?: string }>;
+  }>("ask", payload.questions, opts);
+
+  handle.promise
+    .then((resp) => {
+      getBus().emit(Events.ASK_RESPONSE, {
+        requestId: payload.requestId,
+        cancelled: resp.cancelled,
+        results: resp.results,
+      });
+      pending.delete(payload.requestId);
+    })
+    .catch(() => {
+      getBus().emit(Events.ASK_RESPONSE, {
+        requestId: payload.requestId,
+        cancelled: true,
+        results: payload.questions.map((q) => ({ id: q.id, selectedOptions: [] })),
+      });
+      pending.delete(payload.requestId);
+    });
+
+  return { cancel: handle.cancel };
+}
+
+/** Test seam: reset the module singletons and tear down the bus subscriptions. */
+export function __resetForTests(): void {
+  refcount = 0;
+  settled = false;
+  started = false;
+  sessionCtx = undefined;
+  pending.clear();
+  for (const u of unsubscribers) u();
+  unsubscribers.length = 0;
+}