ompchamber 3.1.1 → 3.2.0

package/src/server/lib/terminal/runtime.server.ts

@@ -273,6 +273,9 @@ export function forgetTerminal(id: string): void {
   if (!session) return;
   sessions.delete(id);
   clearPendingResize(id);
+  // Close each viewer's socket, not just forget it: the record is going away,
+  // so a socket left open would sit on a terminal that can never answer it.
+  for (const viewer of session.viewers) viewer.drop();
   session.viewers.clear();
   if (session.status === 'running') signalGroup(session, 'SIGKILL');
   closeTerminalStream(session);

package/src/server/lib/terminal/session.server.ts

@@ -41,7 +41,15 @@ export const TERMINATION_GRACE_MS = 1000;
 
 /** A socket attached to a terminal. Output is raw PTY bytes; control is JSON. */
 export interface TerminalViewer {
-  send(frame: string | Uint8Array): void;
+  /**
+   * Deliver one frame. Returns false when the viewer could not accept it —
+   * the socket's send buffer is over its high-water mark — which the session
+   * treats as "this viewer is gone": a PTY producer cannot be paused, so the
+   * alternative is buffering unbounded output in a socket nobody is reading.
+   */
+  send(frame: string | Uint8Array): boolean;
+  /** Detach this viewer. Called when `send` reports it cannot keep up. */
+  drop(): void;
 }
 
 export interface TerminalSession {
@@ -63,6 +71,25 @@ export interface TerminalSession {
   lastActivity: number;
 }
 
+/**
+ * Deliver `frame` to every viewer, dropping the ones that cannot keep up.
+ *
+ * `Bun.ServerWebSocket.send` returns the bytes queued, or `-1` when the socket
+ * is over its high-water mark and the frame was NOT sent (verified on 1.4.2:
+ * 40 sends of 1 MiB to a socket nobody reads all return `-1`). A viewer that
+ * reports `-1` is closed rather than skipped — skipping would leave xterm's
+ * parser mid-sequence, so the honest outcome is a reconnect that replays the
+ * scrollback. The PTY cannot be paused, so this is the only backpressure a
+ * terminal has.
+ */
+export function fanOut(session: TerminalSession, frame: string | Uint8Array): void {
+  for (const viewer of session.viewers) {
+    if (viewer.send(frame)) continue;
+    session.viewers.delete(viewer);
+    viewer.drop();
+  }
+}
+
 /** A rejected attach, carrying the code the client shows to the user. */
 export class TerminalRuntimeError extends Error {
   constructor(
@@ -118,7 +145,7 @@ export async function createSession(request: AttachRequest): Promise<TerminalSes
     data(_term, bytes) {
       session.history.append(bytes);
       session.lastActivity = Date.now();
-      for (const viewer of session.viewers) viewer.send(bytes);
+      fanOut(session, bytes);
     },
   });
   session.term = term;
@@ -145,7 +172,7 @@ export async function createSession(request: AttachRequest): Promise<TerminalSes
     session.signal = proc.signalCode ?? null;
     session.lastActivity = Date.now();
     const frame = JSON.stringify({ t: 'exit', exitCode: session.exitCode, signal: session.signal });
-    for (const viewer of session.viewers) viewer.send(frame);
+    fanOut(session, frame);
   });
 
   return session;

package/src/server/routes/agent/command.test.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The spawn guard on POST /api/agent/:sessionId.
+ *
+ * This route is the chamber's ONLY lazy-spawn path: a command posted for a
+ * session it does not manage starts an `omp` child for it. That is right for a
+ * prompt — the user asked for work — and wrong for a read. The sidebar renders
+ * a subagent roster row for every session in the list, and the roster probes
+ * `get_subagents` to seed itself, so an unguarded route booted a whole omp
+ * process per finished session merely LOOKED at (measured: the process count
+ * grew on a session whose liveness probe had just answered `running: false`).
+ *
+ * Both observer-only commands have RPC-free on-disk equivalents, which is what
+ * a finished session is served from, so refusing them for a dead session costs
+ * the client nothing.
+ *
+ * No module is mocked. The assertions are about which response comes back
+ * BEFORE the spawn path is reached, so the real registry (empty for these ids)
+ * and the real on-disk resolver are exactly the inputs that matter. The
+ * "prompt" case proves the guard is not a blanket refusal: it reaches the
+ * resolver and 404s for an id with no session file — a spawn was attempted.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { sendCommand } from '@/server/routes/agent/command';
+
+/** Ids that no chamber instance manages and no session file backs. */
+const DEAD = 'spawn-guard-dead-session';
+const UNKNOWN = 'spawn-guard-unknown-session';
+
+function post(sessionId: string, body: Record<string, unknown>): Promise<Response> {
+  return sendCommand({
+    params: { sessionId },
+    request: new Request(`http://localhost/api/agent/${sessionId}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }),
+  } as never) as Promise<Response>;
+}
+
+async function payload(response: Response): Promise<Record<string, unknown>> {
+  return (await response.json()) as Record<string, unknown>;
+}
+
+describe('agent command spawn guard', () => {
+  test('refuses a roster snapshot for a session that is not running', async () => {
+    const response = await post(DEAD, { type: 'get_subagents' });
+    expect(response.status).toBe(409);
+    expect(await payload(response)).toMatchObject({ code: 'session_not_running' });
+  });
+
+  test('refuses a transcript page for a session that is not running', async () => {
+    const response = await post(DEAD, { type: 'get_subagent_messages', subagentId: 'child' });
+    expect(response.status).toBe(409);
+    expect(await payload(response)).toMatchObject({ code: 'session_not_running' });
+  });
+
+  test('does not refuse a command that asks for work', async () => {
+    const response = await post(UNKNOWN, { type: 'prompt', message: 'hello' });
+    // It reached the spawn path and failed there (no session file on disk),
+    // which is the opposite of the guard's 409.
+    expect(response.status).not.toBe(409);
+  });
+});

package/src/server/routes/agent/command.ts

@@ -5,6 +5,7 @@ import { WebRpcError, getRpcSession, resolveSpawnCwd, startRpcSession, type Agen
 import { getSpawnApprovalMode, reconcileSpawnApprovalMode } from '@/server/lib/omp/rpc/session-registry';
 import { isApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { loadPersistedAccessMode } from '@/shared/lib/omp/config/access-mode.server';
+import { OBSERVER_ONLY_COMMANDS } from '@/server/lib/omp/rpc/constants';
 import { rpcErrorResponse } from '@/server/lib/omp/rpc/errors';
 
 // POST /api/agent/:sessionId — send a command to an existing session (or spawn
@@ -39,6 +40,19 @@ export async function sendCommand({ params, request }: ActionFunctionArgs) {
       }
     }
 
+    // Observer-only reads must never boot an omp child. This route is the spawn
+    // path, so a roster snapshot (`get_subagents`) or a transcript page
+    // (`get_subagent_messages`) posted for a session the chamber is not
+    // managing would start a whole process just to answer a read — measured:
+    // opening a FINISHED session's roster row grew the omp process count, and
+    // the sidebar renders those rows for every session in the list. Both reads
+    // have RPC-free on-disk equivalents (`GET /api/sessions/:id/subagents[/:sub]`),
+    // which is what a dead session is served from; the live registry is only
+    // consulted while a process exists to answer for.
+    if (OBSERVER_ONLY_COMMANDS.has(body.type)) {
+      return json({ error: 'Session is not managed by the chamber', code: 'session_not_running' }, { status: 409 });
+    }
+
     const resolved = await resolveSessionPathOr404(sessionId);
     if ('response' in resolved) return resolved.response;
     const { filePath, recordedCwd } = resolved;

package/src/server/routes/agent/ws.test.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Regression test for the observer WebSocket routes' connection state.
+ *
+ * The bug this pins: `agent/ws.ts` and `btw/ws.ts` kept per-connection state in
+ * a `WeakMap` keyed by the `ws` object. Elysia's Bun adapter builds a NEW
+ * `ElysiaWS` wrapper for every callback and hands `pong` the RAW socket, so
+ * every lookup missed — the pong never cleared `awaitingPong`, the second
+ * heartbeat tore down a socket the client was still reading, and `close` leaked
+ * the interval and the session subscription for the life of the process.
+ *
+ * These assertions run through a real listener on purpose: the failure lived in
+ * the framework's callback identity, which a unit-level fake of `ws` cannot
+ * reproduce. That also makes the heartbeat a REAL timer here — the property
+ * under test is "the socket outlives N keepalive cycles", so the clock is the
+ * thing being measured. The interval is shrunk to 60ms to keep it cheap.
+ */
+
+import { afterAll, beforeAll, describe, expect, mock, test } from 'bun:test';
+import { Elysia } from 'elysia';
+
+/** Heartbeat for the test — several beats must fit inside a test timeout. */
+const HEARTBEAT_MS = 60;
+
+// The route reads the cadence constant at module scope, so the module is
+// replaced BEFORE the route module is imported.
+mock.module('@/shared/lib/workspace/refresh-cadence', () => ({
+  STREAM_HEARTBEAT_MS: HEARTBEAT_MS,
+  SIDEBAR_IDLE_REFRESH_MS: 30_000,
+  SIDEBAR_STREAM_POLL_MS: 8_000,
+  SIDEBAR_REVALIDATE_THROTTLE_MS: 1_000,
+  PANEL_REFRESH_MS: 5_000,
+  FILE_MUTATION_THROTTLE_MS: 500,
+  GIT_STATUS_POLL_MS: 15_000,
+  GIT_STATUS_EVENT_THROTTLE_MS: 1_000,
+  REPO_DISCOVERY_POLL_MS: 1_500,
+  TODO_REFRESH_EVENT_THROTTLE_MS: 400,
+  BROWSER_POLL_MS: 1_000,
+  SIDEBAR_DATA_TTL_MS: 4_000,
+  SESSION_META_RETRY_SCHEDULE_MS: [250],
+}));
+
+const { agentWsRoutes } = await import('@/server/routes/agent/ws');
+
+/** The live session the route subscribes to; records its own lifecycle. */
+interface SessionStub {
+  isAlive: () => boolean;
+  onEvent: (listener: (event: unknown) => void) => () => void;
+  listeners: Set<(event: unknown) => void>;
+  unsubscribes: number;
+}
+
+function makeSession(): SessionStub {
+  const stub: SessionStub = {
+    isAlive: () => true,
+    listeners: new Set(),
+    unsubscribes: 0,
+    onEvent(listener) {
+      stub.listeners.add(listener);
+      return () => {
+        stub.unsubscribes += 1;
+        stub.listeners.delete(listener);
+      };
+    },
+  };
+  return stub;
+}
+
+let session = makeSession();
+const app = new Elysia().use(agentWsRoutes);
+let baseUrl = '';
+
+beforeAll(async () => {
+  (globalThis as { __ompSessions?: unknown }).__ompSessions = {
+    get: (id: string) => (id === 'test-session' ? session : undefined),
+  };
+  await app.listen({ port: 0, hostname: '127.0.0.1' });
+  const port = (app.server as { port?: number } | null)?.port;
+  if (!port) throw new Error('test listener did not report a port');
+  baseUrl = `ws://127.0.0.1:${port}`;
+});
+
+afterAll(async () => {
+  await app.stop();
+});
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** One client, its received frames, and the promises for its lifecycle. */
+function connect(sessionId: string) {
+  const frames: unknown[] = [];
+  const client = new WebSocket(`${baseUrl}/api/agent/${sessionId}/ws`);
+  const opened = Promise.withResolvers<void>();
+  const closed = Promise.withResolvers<number>();
+  client.onopen = () => opened.resolve();
+  client.onmessage = (event) => {
+    try {
+      frames.push(JSON.parse(String(event.data)));
+    } catch {
+      // A non-JSON frame would be a protocol bug; assertions read `frames`.
+    }
+  };
+  client.onclose = (event) => closed.resolve(event.code);
+  return { client, frames, opened: opened.promise, closed: closed.promise };
+}
+
+describe('agent observer WebSocket', () => {
+  test('survives many heartbeats instead of being torn down by its own keepalive', async () => {
+    session = makeSession();
+    const { client, closed } = connect('test-session');
+    // Five beats: the old code closed the socket at the second one.
+    await sleep(HEARTBEAT_MS * 5);
+    expect(client.readyState).toBe(WebSocket.OPEN);
+    client.close();
+    await closed;
+  });
+
+  test('delivers the connected greeting and live session frames', async () => {
+    session = makeSession();
+    const { client, frames, opened, closed } = connect('test-session');
+    await opened;
+    for (const listener of session.listeners) listener({ type: 'agent_start' });
+    await sleep(30);
+    expect(frames).toEqual([
+      { type: 'connected', sessionId: 'test-session' },
+      { type: 'agent_start' },
+    ]);
+    client.close();
+    await closed;
+  });
+
+  test('releases the session subscription when the client disconnects', async () => {
+    session = makeSession();
+    const { client, opened, closed } = connect('test-session');
+    await opened;
+    expect(session.listeners.size).toBe(1);
+    client.close();
+    await closed;
+    await sleep(30);
+    expect(session.unsubscribes).toBe(1);
+    expect(session.listeners.size).toBe(0);
+  });
+
+  test('refuses a session the chamber does not manage', async () => {
+    const { opened, closed, client } = connect('unknown-session');
+    const outcome = await Promise.race([
+      opened.then(() => 'opened' as const),
+      closed.then(() => 'closed' as const),
+      sleep(400).then(() => 'timeout' as const),
+    ]);
+    // The upgrade is rejected before `open` runs, so the client never opens.
+    expect(outcome).not.toBe('opened');
+    client.close();
+  });
+});

package/src/server/routes/agent/ws.ts

@@ -9,7 +9,7 @@
  *
  * Same frame vocabulary (JSON objects with a `type`, first frame `connected`),
  * same backpressure policy (replaceable `message_update` frames collapse to the
- * latest one while the client is behind) — the policy itself now lives in
+ * latest one while the client is behind) — the policy itself lives in
  * `createEventCoalescer`, shared with the SSE route — but carried by one duplex
  * socket: no per-event HTTP framing, no browser reconnect storm, and
  * protocol-level ping/pong keepalive instead of a comment frame every 30s.
@@ -17,18 +17,18 @@
  * Transport-only by design. It reads the live session registry off `globalThis`
  * (the map the server build populates) and duck-types the wrapper, so the
  * registry contract survives any HTTP framework owning the port.
+ *
+ * **Per-connection state lives on `ws.data`, not in a `WeakMap` keyed by the
+ * `ws` object.** Elysia's Bun adapter builds a fresh wrapper per callback and
+ * hands `pong` the raw socket, so a WeakMap lookup always missed: the pong
+ * never cleared `awaitingPong` and the second heartbeat closed a healthy
+ * socket at 60s, while `close` leaked the interval and the session
+ * subscription. `attachObserverStream` owns the lifecycle; see
+ * `@/server/lib/observer-ws` for the measurements.
  */
 
 import { Elysia, t } from 'elysia';
-import { createEventCoalescer, type EventCoalescer } from '@/server/lib/sse';
-import { STREAM_HEARTBEAT_MS } from '@/shared/lib/workspace/refresh-cadence';
-
-/** Coalesce `message_update` frames once this many bytes sit unsent. */
-const HIGH_WATER_BYTES = 256 * 1024;
-
-/** Longest a coalesced frame may wait before it is flushed anyway, so a burst
- *  that ends while the socket is still busy never strands the newest update. */
-const FLUSH_DELAY_MS = 50;
+import { attachObserverStream, createObserverState, type ObserverConnectionState } from '@/server/lib/observer-ws';
 
 interface AgentEventSession {
   isAlive?: () => boolean;
@@ -48,15 +48,8 @@ function findAgentSession(sessionId: string): AgentEventSession | null {
   return session;
 }
 
-interface ConnectionState {
-  closed: boolean;
-  unsubscribe: (() => void) | null;
-  heartbeat: ReturnType<typeof setInterval> | null;
-  awaitingPong: boolean;
-  coalescer: EventCoalescer | null;
-}
-
-const connections = new WeakMap<object, ConnectionState>();
+/** Elysia's ws context, narrowed to the per-connection store this route adds. */
+type AgentWsData = { params: { sessionId: string }; observer?: ObserverConnectionState };
 
 export const agentWsRoutes = new Elysia({ prefix: '/api/agent' }).ws('/:sessionId/ws', {
   params: t.Object({ sessionId: t.String() }),
@@ -68,81 +61,24 @@ export const agentWsRoutes = new Elysia({ prefix: '/api/agent' }).ws('/:sessionI
   },
 
   open(ws) {
-    const sessionId = ws.data.params.sessionId;
+    const data = ws.data as unknown as AgentWsData;
+    const sessionId = data.params.sessionId;
     const session = findAgentSession(sessionId);
     if (!session) {
       ws.close();
       return;
     }
 
-    const state: ConnectionState = {
-      closed: false,
-      unsubscribe: null,
-      heartbeat: null,
-      awaitingPong: false,
-      coalescer: null,
-    };
-    connections.set(ws, state);
+    const state = createObserverState();
+    data.observer = state;
+    const { push } = attachObserverStream(state, ws);
 
-    const teardown = () => {
-      if (state.closed) return;
-      state.closed = true;
-      state.coalescer?.dispose();
-      state.coalescer = null;
-      if (state.heartbeat !== null) {
-        clearInterval(state.heartbeat);
-        state.heartbeat = null;
-      }
-      if (state.unsubscribe) {
-        try {
-          state.unsubscribe();
-        } catch {
-          // Subscriber cleanup is best-effort.
-        }
-        state.unsubscribe = null;
-      }
-      try {
-        ws.close();
-      } catch {
-        // Already gone.
-      }
-    };
-
-    state.coalescer = createEventCoalescer({
-      send: (_event, data) => {
-        try {
-          ws.send(JSON.stringify(data));
-        } catch {
-          teardown();
-        }
-      },
-      isBackpressured: () => ((ws.raw as { bufferedAmount?: number }).bufferedAmount ?? 0) > HIGH_WATER_BYTES,
-      flushDelayMs: FLUSH_DELAY_MS,
-    });
-
-    // Protocol-level keepalive: a client that misses a full ping cycle is gone,
-    // and a live one answers without any application-level traffic.
-    state.heartbeat = setInterval(() => {
-      if (state.closed) return;
-      if (state.awaitingPong) {
-        teardown();
-        return;
-      }
-      state.awaitingPong = true;
-      if (!state.coalescer?.flush()) return;
-      try {
-        (ws.raw as { ping?: () => void }).ping?.();
-      } catch {
-        teardown();
-      }
-    }, STREAM_HEARTBEAT_MS);
-
-    state.unsubscribe = session.onEvent((event) => state.coalescer?.push('', event));
-    state.coalescer.push('', { type: 'connected', sessionId });
+    state.unsubscribe = session.onEvent((event) => push('', event));
+    push('', { type: 'connected', sessionId });
   },
 
   pong(ws) {
-    const state = connections.get(ws);
+    const state = (ws.data as unknown as AgentWsData).observer;
     if (state) state.awaitingPong = false;
   },
 
@@ -151,18 +87,7 @@ export const agentWsRoutes = new Elysia({ prefix: '/api/agent' }).ws('/:sessionI
   },
 
   close(ws) {
-    const state = connections.get(ws);
-    if (!state || state.closed) return;
-    state.closed = true;
-    state.coalescer?.dispose();
-    state.coalescer = null;
-    if (state.heartbeat !== null) clearInterval(state.heartbeat);
-    if (state.unsubscribe) {
-      try {
-        state.unsubscribe();
-      } catch {
-        // Subscriber cleanup is best-effort.
-      }
-    }
+    const state = (ws.data as unknown as AgentWsData).observer;
+    if (state) state.teardown();
   },
 });

package/src/server/routes/btw/ws.ts

@@ -12,105 +12,43 @@
  * A client that attaches replays nothing: the socket's first `btw_state` is
  * the session's current history, so a reload lands on the same panel a live
  * stream would have produced.
+ *
+ * **Per-connection state lives on `ws.data`, not in a `WeakMap` keyed by the
+ * `ws` object** — Elysia's Bun adapter hands `pong` the raw socket and a fresh
+ * wrapper to every other callback, so a WeakMap lookup always missed and the
+ * second heartbeat closed a healthy socket. See `@/server/lib/observer-ws`.
  */
 
 import { Elysia, t } from 'elysia';
-import { createEventCoalescer, type EventCoalescer } from '@/server/lib/sse';
-import { STREAM_HEARTBEAT_MS } from '@/shared/lib/workspace/refresh-cadence';
+import { attachObserverStream, createObserverState, type ObserverConnectionState } from '@/server/lib/observer-ws';
 import { btwStateFor, subscribeBtw } from '@/server/lib/btw/registry.server';
 import type { BtwFrame } from '@/shared/types';
 
-/** Coalesce frames once this many bytes sit unsent. */
-const HIGH_WATER_BYTES = 256 * 1024;
-
-/** Longest a coalesced frame may wait before it is flushed anyway. */
-const FLUSH_DELAY_MS = 50;
-
-interface ConnectionState {
-  closed: boolean;
-  unsubscribe: (() => void) | null;
-  heartbeat: ReturnType<typeof setInterval> | null;
-  awaitingPong: boolean;
-  coalescer: EventCoalescer | null;
-}
-
-const connections = new WeakMap<object, ConnectionState>();
+/** Elysia's ws context, narrowed to the per-connection store this route adds. */
+type BtwWsData = { params: { sessionId: string }; observer?: ObserverConnectionState };
 
 export const btwWsRoutes = new Elysia({ prefix: '/api/btw' }).ws('/:sessionId/ws', {
   params: t.Object({ sessionId: t.String() }),
 
   open(ws) {
-    const sessionId = ws.data.params.sessionId;
-    const state: ConnectionState = { closed: false, unsubscribe: null, heartbeat: null, awaitingPong: false, coalescer: null };
-    connections.set(ws, state);
-    // Unchecked: Elysia exposes the server socket untyped. Both members are
-    // optional, so an absent one degrades (no byte count / no keepalive)
-    // instead of failing.
-    const raw = ws.raw as { bufferedAmount?: number; ping?: () => void };
-
-    const teardown = () => {
-      if (state.closed) return;
-      state.closed = true;
-      state.coalescer?.dispose();
-      state.coalescer = null;
-      if (state.heartbeat !== null) {
-        clearInterval(state.heartbeat);
-        state.heartbeat = null;
-      }
-      if (state.unsubscribe) {
-        try {
-          state.unsubscribe();
-        } catch {
-          // Subscriber cleanup is best-effort.
-        }
-        state.unsubscribe = null;
-      }
-      try {
-        ws.close();
-      } catch {
-        // Already gone.
-      }
-    };
-
-    state.coalescer = createEventCoalescer({
-      send: (_event, data) => {
-        try {
-          ws.send(JSON.stringify(data));
-        } catch {
-          teardown();
-        }
-      },
-      isBackpressured: () => (raw.bufferedAmount ?? 0) > HIGH_WATER_BYTES,
-      flushDelayMs: FLUSH_DELAY_MS,
-    });
-
-    state.heartbeat = setInterval(() => {
-      if (state.closed) return;
-      if (state.awaitingPong) {
-        teardown();
-        return;
-      }
-      state.awaitingPong = true;
-      if (!state.coalescer?.flush()) return;
-      try {
-        raw.ping?.();
-      } catch {
-        teardown();
-      }
-    }, STREAM_HEARTBEAT_MS);
-
-    const push = (frame: BtwFrame) => state.coalescer?.push('', frame);
-    state.unsubscribe = subscribeBtw(sessionId, push);
-    push({ type: 'connected', sessionId });
+    const data = ws.data as unknown as BtwWsData;
+    const sessionId = data.params.sessionId;
+    const state = createObserverState();
+    data.observer = state;
+    const { push } = attachObserverStream(state, ws);
+
+    const send = (frame: BtwFrame) => push('', frame);
+    state.unsubscribe = subscribeBtw(sessionId, send);
+    send({ type: 'connected', sessionId });
     void btwStateFor(sessionId)
-      .then((snapshot) => push({ type: 'btw_state', state: snapshot }))
+      .then((snapshot) => send({ type: 'btw_state', state: snapshot }))
       .catch((error: unknown) => {
-        push({ type: 'btw_error', topicId: null, message: error instanceof Error ? error.message : String(error) });
+        send({ type: 'btw_error', topicId: null, message: error instanceof Error ? error.message : String(error) });
       });
   },
 
   pong(ws) {
-    const state = connections.get(ws);
+    const state = (ws.data as unknown as BtwWsData).observer;
     if (state) state.awaitingPong = false;
   },
 
@@ -119,18 +57,7 @@ export const btwWsRoutes = new Elysia({ prefix: '/api/btw' }).ws('/:sessionId/ws
   },
 
   close(ws) {
-    const state = connections.get(ws);
-    if (!state || state.closed) return;
-    state.closed = true;
-    state.coalescer?.dispose();
-    state.coalescer = null;
-    if (state.heartbeat !== null) clearInterval(state.heartbeat);
-    if (state.unsubscribe) {
-      try {
-        state.unsubscribe();
-      } catch {
-        // Subscriber cleanup is best-effort.
-      }
-    }
+    const state = (ws.data as unknown as BtwWsData).observer;
+    if (state) state.teardown();
   },
 });