@pi-archimedes/core 2.10.3 → 2.11.0

package/src/bridge/events.ts

@@ -1,9 +1,9 @@
-// ── Bridge events (bus subscriptions — the state machine + subagent
-//    forwarding + push events) ─────────────────────────────────────────────
+// ── Bridge events (host-event-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
+// Subscribes the SIX channel-vocabulary 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). Channel 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 —
@@ -16,19 +16,25 @@
 // 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";
+// The subscriptions live on the CALLER's host handle (`pi.events`), which this
+// module does not own — see `start()` / `stop()` for why the pair is mandatory
+// now that the transport is the host's.
+
+import type { EventBus, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Events, emitOn } from "../events.js";
+import { diag } from "../log.js";
 import { sendEvent, request } from "./channel.js";
 
 let refcount = 0;
 let settled = false;
-let started = false; // the start() idempotency guard (sole writer is start())
+/** The handle the current subscription set was made on, or undefined when there is no subscription set. */
+let subscribedOn: EventBus | undefined;
+/**
+ * Bumped by every teardown. A Client reply that settles after its own
+ * subscription set is gone carries the generation it was asked on, and drops
+ * itself when that number is no longer current — see `requestAskToClient`.
+ */
+let generation = 0;
 let sessionCtx: ExtensionContext | undefined;
 
 const pending = new Map<string, { source: string; toolCallId?: string; cancel: () => void }>();
@@ -79,15 +85,23 @@ function sessionRefs(): Record<string, unknown> {
 }
 
 /**
- * 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).
+ * Subscribe the six channel-vocabulary events on a host handle.
+ *
+ * Idempotent by teardown, not by an early return: it stops any previous
+ * subscription set first, so it can be called once per `session_start` without
+ * double-delivering. A "we already started, bail out" flag would be wrong
+ * here — the host drops every subscription of a runtime when that runtime is
+ * invalidated (session replacement, `/reload`), so the second `session_start`
+ * of a process genuinely needs new subscriptions.
+ *
+ * @param events the caller's `pi.events` — the relay never reaches for a bus
+ *               of its own, which is the whole point of the migration
  */
-export function start(): void {
-  if (started) return;
-  started = true;
+export function start(events: EventBus): void {
+  stop();
+  subscribedOn = events;
 
-  unsubscribers.push(getBus().on(Events.ASK_REQUEST, (payload: unknown) => {
+  unsubscribers.push(events.on(Events.ASK_REQUEST, (payload: unknown) => {
     const p = payload as {
       source: string;
       requestId: string;
@@ -106,7 +120,7 @@ export function start(): void {
     }
   }));
 
-  unsubscribers.push(getBus().on(Events.ASK_RESPONSE, () => {
+  unsubscribers.push(events.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
@@ -114,12 +128,12 @@ export function start(): void {
     // 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)");
+    if (refcount === 0) diag("core", "[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) => {
+  unsubscribers.push(events.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
@@ -129,25 +143,62 @@ export function start(): void {
   }));
 
   // Bus payload types ARE the wire types — forward verbatim.
-  unsubscribers.push(getBus().on(Events.TODOS_UPDATE, (payload: unknown) => {
+  unsubscribers.push(events.on(Events.TODOS_UPDATE, (payload: unknown) => {
     sendEvent("todos_update", payload);
   }));
 
-  unsubscribers.push(getBus().on(Events.TODOS_CLEAR, (payload: unknown) => {
+  unsubscribers.push(events.on(Events.TODOS_CLEAR, (payload: unknown) => {
     sendEvent("todos_clear", payload);
   }));
 
-  unsubscribers.push(getBus().on(Events.COST_UPDATE, (payload: unknown) => {
+  unsubscribers.push(events.on(Events.COST_UPDATE, (payload: unknown) => {
     sendEvent("cost_update", payload);
   }));
 }
 
+/**
+ * Tear the subscription set down. The counterpart `start()` needs, and the
+ * reason the relay survives a replacement session: the host unsubscribes a
+ * runtime's handles when it invalidates it, so without an explicit teardown
+ * the module-level state (refcount, pending asks, "am I subscribed") would
+ * outlive the subscriptions it describes.
+ *
+ * Also releases the asks that died with the session — a Client request that
+ * can never be answered would otherwise pin the state machine at `blocked` for
+ * every session after this one.
+ *
+ * Safe to call when nothing is subscribed.
+ */
+export function stop(): void {
+  // Retire in-flight replies BEFORE anything else: their callbacks run on the
+  // next microtask, which is after a same-tick `start()` has re-subscribed, so
+  // they need to be told they are stale rather than left to find the new set.
+  // Nothing waits on the dropped reply: this teardown runs from
+  // `session_shutdown`, and the replacement that fired it already aborted the
+  // turn (`AgentSessionRuntime.teardownCurrent` → `session.abort()`), whose
+  // AbortSignal is what kills the child that asked (`subagent/spawn.ts`'s abort
+  // handler). The ask's requester is gone with the session.
+  generation++;
+  for (const unsubscribe of unsubscribers.splice(0)) unsubscribe();
+  subscribedOn = undefined;
+  // Cancel first, then drop: a cancelled Client request settles asynchronously
+  // and its paired ASK_RESPONSE finds no listener by then (the refcount is
+  // reset below, not decremented, so the pair cannot double-count).
+  for (const [, entry] of pending) entry.cancel();
+  pending.clear();
+  refcount = 0;
+}
+
 /**
  * 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.
+ *
+ * The answer rides back out on the handle this subscription set was started
+ * on — the same handle `subagent/spawn.ts` is listening on to write it down the
+ * child's socket.
  */
 function requestAskToClient(
   payload: {
@@ -159,39 +210,47 @@ function requestAskToClient(
 ): { cancel: () => void } {
   const opts: { toolCallId?: string; source?: string } = { source: payload.source };
   if (payload.toolCallId !== undefined) opts.toolCallId = payload.toolCallId;
+  // The generation this ask belongs to. `stop()` cancels the request and bumps
+  // it, so the settle callback below (a microtask later) can tell whether it is
+  // still answering into the subscription set that asked — otherwise a reply to
+  // a dead session decrements the live session's refcount and reports a pending
+  // prompt as answered.
   const handle = request<{
     cancelled: boolean;
     results: Array<{ id: string; selectedOptions: string[]; customInput?: string }>;
   }>("ask", payload.questions, opts);
 
+  const askedAtGeneration = generation;
+  const answer = (response: { cancelled: boolean; results: unknown[] }): void => {
+    if (askedAtGeneration !== generation) return;
+    emitOn(subscribedOn, Events.ASK_RESPONSE, {
+      requestId: payload.requestId,
+      cancelled: response.cancelled,
+      results: response.results,
+    });
+  };
+
   handle.promise
     .then((resp) => {
-      getBus().emit(Events.ASK_RESPONSE, {
-        requestId: payload.requestId,
-        cancelled: resp.cancelled,
-        results: resp.results,
-      });
+      answer({ 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: [] })),
-      });
+      answer({ 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. */
+/** Test seam: reset the module singletons and tear down the subscriptions. */
 export function __resetForTests(): void {
+  generation++;
   refcount = 0;
   settled = false;
-  started = false;
   sessionCtx = undefined;
   pending.clear();
   for (const u of unsubscribers) u();
   unsubscribers.length = 0;
+  subscribedOn = undefined;
 }

package/src/bridge/index.test.ts

@@ -5,7 +5,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
-import { getBus, Events } from "../bus.js";
+import { Events } from "../events.js";
 import {
   getBridge,
   ask,
@@ -57,13 +57,40 @@ function makeFakeCtx(mode: "tui" | "rpc" | "json" | "print"): { mode: string } {
 /** Register the bridge and fire its session_start handler with the given ctx. */
 function registerAndFireSessionStart(ctx: { mode: string }): void {
   const onSpy = vi.fn();
-  registerBridge({ on: onSpy } as unknown as ExtensionAPI);
+  registerBridge({ on: onSpy, events: bus } as unknown as ExtensionAPI);
   const calls = onSpy.mock.calls as Array<[string, (e: unknown, ctx: unknown) => void]>;
   const startCall = calls.find((c) => c[0] === "session_start");
   expect(startCall).toBeTruthy();
   startCall![1](null, ctx);
 }
 
+/**
+ * The host handle the relay subscribes on, stood in for by the same
+ * emit/on/unsubscribe contract pi's `createEventBus()` implements. Per test,
+ * because the relay's subscriptions now live on the handle rather than on a
+ * process-wide singleton.
+ */
+function fakeBus() {
+  const listeners = new Map<string, Array<(data: unknown) => void>>();
+  return {
+    emit(channel: string, data: unknown): void {
+      for (const handler of [...(listeners.get(channel) ?? [])]) handler(data);
+    },
+    on(channel: string, handler: (data: unknown) => void): () => void {
+      const subs = listeners.get(channel) ?? [];
+      subs.push(handler);
+      listeners.set(channel, subs);
+      return () => {
+        const current = listeners.get(channel) ?? [];
+        const idx = current.indexOf(handler);
+        if (idx !== -1) current.splice(idx, 1);
+      };
+    },
+  };
+}
+
+let bus: ReturnType<typeof fakeBus>;
+
 function tempSocketPath(): string {
   return path.join(os.tmpdir(), `bridge-test-${randomUUID()}.sock`);
 }
@@ -109,6 +136,7 @@ function startServer(
 beforeEach(() => {
   for (const k of ENV_KEYS) savedEnv[k] = process.env[k];
   clearBridgeEnv();
+  bus = fakeBus();
   resetChannel();
   resetEvents();
 });
@@ -187,7 +215,7 @@ describe("inactive API", () => {
 
 describe("state machine", () => {
   it("onAgentSettled → idle; onAgentStart → working", () => {
-    start();
+    start(bus);
     onAgentSettled();
     expect(state()).toBe("idle");
     onAgentStart();
@@ -195,41 +223,41 @@ describe("state machine", () => {
   });
 
   it("ASK_REQUEST → blocked; stays blocked through onAgentSettled; ASK_RESPONSE → idle (settled)", () => {
-    start();
+    start(bus);
     onAgentSettled(); // settled = true
-    getBus().emit(Events.ASK_REQUEST, { source: "main", requestId: "r1", questions: [makeQuestion()] });
+    bus.emit(Events.ASK_REQUEST, { source: "main", requestId: "r1", questions: [makeQuestion()] });
     expect(state()).toBe("blocked");
     onAgentSettled(); // still blocked (refcount > 0)
     expect(state()).toBe("blocked");
-    getBus().emit(Events.ASK_RESPONSE, { requestId: "r1", cancelled: false, results: [] });
+    bus.emit(Events.ASK_RESPONSE, { requestId: "r1", cancelled: false, results: [] });
     expect(state()).toBe("idle"); // settled
   });
 
   it("ASK_RESPONSE → working (not settled)", () => {
-    start();
+    start(bus);
     onAgentStart(); // settled = false
-    getBus().emit(Events.ASK_REQUEST, { source: "main", requestId: "r2", questions: [makeQuestion()] });
+    bus.emit(Events.ASK_REQUEST, { source: "main", requestId: "r2", questions: [makeQuestion()] });
     expect(state()).toBe("blocked");
-    getBus().emit(Events.ASK_RESPONSE, { requestId: "r2", cancelled: false, results: [] });
+    bus.emit(Events.ASK_RESPONSE, { requestId: "r2", cancelled: false, results: [] });
     expect(state()).toBe("working"); // not settled
   });
 
   it("an unpaired ASK_RESPONSE does not drive the refcount negative (floor at 0)", () => {
-    start();
+    start(bus);
     onAgentSettled(); // settled = true
     expect(state()).toBe("idle");
 
     // A spurious/duplicated ASK_RESPONSE with no matching ASK_REQUEST must not
     // push the refcount below zero (the floor keeps the machine honest).
-    getBus().emit(Events.ASK_RESPONSE, { requestId: "orphan", cancelled: false, results: [] });
+    bus.emit(Events.ASK_RESPONSE, { requestId: "orphan", cancelled: false, results: [] });
     expect(state()).toBe("idle"); // floor at 0 (not -1)
 
     // A legitimate ask is still blocked (the floor prevented the negative count).
-    getBus().emit(Events.ASK_REQUEST, { source: "main", requestId: "r3", questions: [makeQuestion()] });
+    bus.emit(Events.ASK_REQUEST, { source: "main", requestId: "r3", questions: [makeQuestion()] });
     expect(state()).toBe("blocked");
 
     // ...and it still unblocks cleanly.
-    getBus().emit(Events.ASK_RESPONSE, { requestId: "r3", cancelled: false, results: [] });
+    bus.emit(Events.ASK_RESPONSE, { requestId: "r3", cancelled: false, results: [] });
     expect(state()).toBe("idle"); // settled
   });
 });
@@ -243,13 +271,13 @@ describe("ASK_CANCEL flow", () => {
       /* accept but never respond */
     });
 
-    start();
+    start(bus);
     configure({ active: true, socketPath: sockPath });
 
     const responses: unknown[] = [];
-    const unsub = getBus().on(Events.ASK_RESPONSE, (p) => responses.push(p));
+    const unsub = bus.on(Events.ASK_RESPONSE, (p) => responses.push(p));
 
-    getBus().emit(Events.ASK_REQUEST, {
+    bus.emit(Events.ASK_REQUEST, {
       source: "subagent:x",
       requestId: "sub-req-1",
       questions: [makeQuestion()],
@@ -259,7 +287,7 @@ describe("ASK_CANCEL flow", () => {
     // Give the forwarded request a moment to connect to the (silent) server.
     await new Promise((r) => setTimeout(r, 50));
 
-    getBus().emit(Events.ASK_CANCEL, { requestId: "sub-req-1", source: "subagent:x" });
+    bus.emit(Events.ASK_CANCEL, { requestId: "sub-req-1", source: "subagent:x" });
 
     // The cancel closes the socket → the request rejects → a cancelled ASK_RESPONSE is emitted.
     await vi.waitFor(() => {
@@ -278,8 +306,8 @@ describe("ASK_CANCEL flow", () => {
   });
 
   it("ASK_CANCEL with no pending entry is a no-op (no crash, refcount untouched)", () => {
-    start();
-    getBus().emit(Events.ASK_CANCEL, { requestId: "does-not-exist", source: "subagent:x" });
+    start(bus);
+    bus.emit(Events.ASK_CANCEL, { requestId: "does-not-exist", source: "subagent:x" });
     expect(state()).toBe("working"); // refcount still 0
   });
 });
@@ -684,13 +712,13 @@ describe("subagent ask success path", () => {
     });
     await new Promise<void>((resolve) => server.listen(sockPath, resolve));
 
-    start();
+    start(bus);
     configure({ active: true, socketPath: sockPath });
 
     const responses: unknown[] = [];
-    const unsub = getBus().on(Events.ASK_RESPONSE, (p) => responses.push(p));
+    const unsub = bus.on(Events.ASK_RESPONSE, (p) => responses.push(p));
 
-    getBus().emit(Events.ASK_REQUEST, {
+    bus.emit(Events.ASK_REQUEST, {
       source: "subagent:x",
       requestId: "sub-req-2",
       toolCallId: "child-tool-1",

package/src/bridge/index.ts

@@ -10,7 +10,7 @@
 // password → "" (cancel).
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { AskResponsePayload, AskRequestPayload } from "../bus.js";
+import type { AskResponsePayload, AskRequestPayload } from "../events.js";
 import * as channel from "./channel.js";
 import * as events from "./events.js";
 
@@ -144,16 +144,24 @@ function isBridgeMode(ctx: { mode: string }): boolean {
 }
 
 /**
- * Subscribe the pi EXTENSION events (NOT the bus — nothing emits
- * agent_start/agent_settled/session_start on the bus). The extension events DO
- * fire in RPC mode (the RPC driver runs the same session machinery).
+ * Subscribe the pi EXTENSION events (NOT the channel vocabulary — nothing emits
+ * agent_start/agent_settled/session_start onto the event bus). The extension
+ * events DO fire in RPC mode (the RPC driver runs the same session machinery).
+ *
+ * The relay's own subscriptions are opened at `session_start` (activation is
+ * decided there) and closed at `session_shutdown`, which is registered here at
+ * the top level — never inside the `session_start` handler (AGENTS.md: nested
+ * registration accumulates handlers across `/reload`). It is not just hygiene:
+ * the host drops a runtime's event-bus subscriptions when the runtime is
+ * invalidated, so a relay that never tears down ends up describing itself with
+ * state whose subscriptions no longer exist.
  */
 export function registerBridge(pi: ExtensionAPI): void {
   pi.on("session_start", (_e, ctx) => {
     const active = isBridgeMode(ctx);
     channel.configure({ active, socketPath: process.env.PI_ARCHIMEDES_BRIDGE_SOCKET });
     if (active) {
-      events.start();
+      events.start(pi.events);
       events.onSessionStart(ctx);
     }
   });
@@ -163,4 +171,9 @@ export function registerBridge(pi: ExtensionAPI): void {
   pi.on("agent_settled", () => {
     if (channelActive()) events.onAgentSettled();
   });
+  // Unconditional: an inactive bridge never subscribed, and stop() on nothing
+  // subscribed is a no-op — the safe direction for a teardown.
+  pi.on("session_shutdown", () => {
+    events.stop();
+  });
 }

package/src/bridge/self-usage.test.ts

@@ -1,30 +1,57 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getBus, Events } from "../bus.js";
+import { Events } from "../events.js";
 import { registerSelfUsage } from "./self-usage.js";
 
 /**
- * Bus discipline (load-bearing): the bus has NO reset seam, `emit` with zero
- * subscribers queues the payload globally, and `on()` replays queued events
- * WITHOUT removing them. So EVERY test subscribes a per-test listener FIRST,
- * then invokes the handler, asserts only on that test's captured array, and
- * unsubscribes via the `on` return value.
+ * The emitter emits on the handle it was handed (`pi.events`), so every test
+ * builds its own handle and subscribes its own listener before invoking the
+ * handler. Nothing is process-wide any more, so there is no queue and no replay
+ * to design around — which is the point of the migration.
  */
+function fakeBus() {
+  const listeners = new Map<string, Array<(data: unknown) => void>>();
+  return {
+    emit(channel: string, data: unknown): void {
+      for (const handler of [...(listeners.get(channel) ?? [])]) handler(data);
+    },
+    on(channel: string, handler: (data: unknown) => void): () => void {
+      const subs = listeners.get(channel) ?? [];
+      subs.push(handler);
+      listeners.set(channel, subs);
+      return () => {
+        const current = listeners.get(channel) ?? [];
+        const idx = current.indexOf(handler);
+        if (idx !== -1) current.splice(idx, 1);
+      };
+    },
+  };
+}
+
+/** The handle this test's emitter was handed. Fresh per test. */
+let bus: ReturnType<typeof fakeBus>;
+
+beforeEach(() => {
+  bus = fakeBus();
+});
+
+/** Subscribe to COST_UPDATE on that handle. */
 function captureCostUpdates(): { events: unknown[]; done: () => void } {
-  const events: unknown[] = [];
-  const unsub = getBus().on(Events.COST_UPDATE, (p) => events.push(p));
-  return { events, done: unsub };
+  const captured: unknown[] = [];
+  const unsub = bus.on(Events.COST_UPDATE, (p: unknown) => captured.push(p));
+  return { events: captured, done: unsub };
 }
 
 /**
  * Register and capture the turn_end handler, using the repo's mock-ExtensionAPI
  * idiom (verbatim from bridge/index.test.ts — a plain object fails `tsc` with
  * TS2740; the `as unknown as ExtensionAPI` cast and the `mock.calls` re-typing
- * are BOTH required).
+ * are BOTH required). The handle the emitter gets is this test's bus, so the
+ * test can subscribe to the same one.
  */
 function registerAndGetTurnEndHandler(): (e: unknown, ctx: unknown) => void {
   const onSpy = vi.fn();
-  registerSelfUsage({ on: onSpy } as unknown as ExtensionAPI);
+  registerSelfUsage({ on: onSpy, events: bus } as unknown as ExtensionAPI);
   const calls = onSpy.mock.calls as Array<[string, (e: unknown, ctx: unknown) => void]>;
   const handler = calls.find(([event]) => event === "turn_end")![1];
   expect(handler).toBeTruthy();
@@ -144,3 +171,54 @@ describe("bridge independence", () => {
     }
   });
 });
+
+// ── 5. the queue is gone, and nothing needed it ───────────────────────
+
+describe("no pre-subscriber queue", () => {
+  /**
+   * The retired `globalThis` bus queued an emit that had no listener and replayed
+   * it to whoever subscribed next. The host bus does not: an emit with no
+   * subscriber is dropped. That is the property the migration had to answer for,
+   * so it is pinned here rather than assumed.
+   *
+   * Dropping is safe for this emitter, and the reason is call order: it fires at
+   * `turn_end`, and its one consumer (`bridge/events.ts`) subscribes at
+   * `session_start`, which pi always fires first — a turn cannot end before its
+   * session started. Every other emitter in the suite is later still (a tool
+   * call, a child's socket, a child's stdout). So no ordering guard was kept, and
+   * this is precisely the case that would need one if that ever stopped holding.
+   */
+  it("an emit with no subscriber is not replayed to the next subscriber", () => {
+    const handler = registerAndGetTurnEndHandler();
+    handler(
+      {
+        type: "turn_end",
+        turnIndex: 0,
+        message: assistantMessage({ usage: { input: 5, output: 1, cost: { total: 0.5 } } }),
+      },
+      { mode: "tui" },
+    );
+
+    const { events, done } = captureCostUpdates();
+    expect(events).toHaveLength(0);
+    done();
+  });
+
+  it("the same emit DOES reach a subscriber that was already listening", () => {
+    const handler = registerAndGetTurnEndHandler();
+    const { events, done } = captureCostUpdates();
+    try {
+      handler(
+        {
+          type: "turn_end",
+          turnIndex: 0,
+          message: assistantMessage({ usage: { input: 5, output: 1, cost: { total: 0.5 } } }),
+        },
+        { mode: "tui" },
+      );
+      expect(events).toHaveLength(1);
+    } finally {
+      done();
+    }
+  });
+});

package/src/bridge/self-usage.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getBus, Events } from "../bus.js";
+import { Events, emitOn } from "../events.js";
 
 /**
  * Minimal structural mirror of the pi-ai `Usage` type (core does not depend on
@@ -16,16 +16,29 @@ interface UsageLike {
 /**
  * Emit the session's OWN usage as a per-turn COST_UPDATE (source "main").
  * Per design decision 1-3: per-turn (turn_end), delta (the turn's usage is
- * not cumulative), NOT gated on bridge mode (the TUI footer's
- * CostAccumulator sums it — the footer's cost line becomes the true session
- * cost; in bridge mode the existing events.ts forwarder carries it to the
- * desktop). `reasoning` is excluded (a subset of `output` — double-count).
+ * not cumulative), NOT gated on bridge mode. `reasoning` is excluded (a subset
+ * of `output` — double-count).
+ *
+ * Who listens now (Task 9 of the pi 1.x alignment changed this): the bridge
+ * forwarder in `./events.ts` relays it to the desktop as a `cost_update` frame.
+ * The TUI's consumer is **gone** — the footer's `CostAccumulator` was deleted
+ * with it, because the footer reads usage from the session entries and those
+ * already carry the main agent's assistant usage; keeping the accumulator would
+ * have counted the main session's money twice. So on a plain TUI this emit has
+ * no in-suite subscriber left, and the host bus drops it (unlike the old bus,
+ * which queued it for a subscriber that never came). Deleting the emitter is a
+ * bridge-contract question, not part of the transport migration: `cost_update`
+ * is a frame the Archimedes Client may render.
+ *
+ * Ordering is safe without a queue. The forwarder subscribes at `session_start`
+ * and this fires at `turn_end`, which pi always fires later — see
+ * `self-usage.test.ts` for the executable version of that claim.
  */
 export function registerSelfUsage(pi: ExtensionAPI): void {
   pi.on("turn_end", (event) => {
     const usage = (event.message as { usage?: UsageLike } | undefined)?.usage;
     if (!usage) return;
-    getBus().emit(Events.COST_UPDATE, {
+    emitOn(pi.events, Events.COST_UPDATE, {
       source: "main",
       inputTokens: usage.input ?? 0,
       outputTokens: usage.output ?? 0,