ompchamber 3.1.0 → 3.2.0

package/src/server/lib/omp/session/telemetry-raw.ts

@@ -7,6 +7,10 @@
  * Server-side pagination for the raw messages panel. Scans the session JSONL
  * like ./telemetry.ts but materializes at most one page of `RawMessageItem`s,
  * so the payload-heavy entries never leave the server in bulk.
+ *
+ * The sliding window keeps MATCHES, and only the page that is returned is
+ * built — building every match to discard all but one page cost 48.9 ms on an
+ * 11 MB session against 1.9 ms for the page itself.
  */
 
 import type { RawMessageItem } from '@/shared/types/context';
@@ -33,14 +37,20 @@ export async function computeRawMessagesPage(
   role: RawMessageRole = 'all',
 ): Promise<RawMessagesPage> {
   const windowSize = Math.max(1, page) * pageSize;
-  const window: RawMessageItem[] = [];
+  // The window holds the last `windowSize` MATCHES, not built items. Building
+  // every match and discarding all but one page was the whole cost of this
+  // endpoint: on an 11 MB session, `buildRawItem` over all 1017 matches took
+  // 48.9 ms while building only the 50 that are returned took 1.9 ms — the scan
+  // that collects them is 0.2 ms.
+  const window: { entry: OmpMessageEntry; msg: OmpMessage; index: number }[] = [];
+  let head = 0;
   let total = 0;
   let filteredTotal = 0;
-  let header: OmpMessageEntry | undefined;
+  let cwd = '';
 
   await scanSessionEntries(filePath, (entry, index) => {
-    if (entry.type === 'session' && !header) {
-      header = entry;
+    if (entry.type === 'session') {
+      if (!cwd) cwd = entry.cwd ?? '';
       return;
     }
     if (entry.type !== 'message' || !entry.message) return;
@@ -54,8 +64,8 @@ export async function computeRawMessagesPage(
     if (role !== 'all' && msgRole !== role) return;
     filteredTotal++;
 
-    if (window.length >= windowSize) window.shift();
-    window.push(buildRawItem(entry, msg, header?.cwd ?? '', index));
+    window.push({ entry, msg, index });
+    if (window.length - head > windowSize) head++;
   });
 
   // `window` holds the last `windowSize` matches, oldest→newest, where
@@ -63,9 +73,15 @@ export async function computeRawMessagesPage(
   // rows: skip the (page-1) newest chunks, take one, flip for display. Both
   // bounds clamp at 0 so out-of-range pages return an empty list.
   const skipNewest = (Math.max(1, page) - 1) * pageSize;
-  const end = Math.max(0, window.length - skipNewest);
+  const live = window.length - head;
+  const end = Math.max(0, live - skipNewest);
   const start = Math.max(0, end - pageSize);
-  const items = window.slice(start, end).reverse();
+  const items: RawMessageItem[] = [];
+  for (let i = head + start; i < head + end; i++) {
+    const match = window[i];
+    items.push(buildRawItem(match.entry, match.msg, cwd, match.index));
+  }
+  items.reverse();
   return { items, total, filteredTotal };
 }
 

package/src/server/lib/omp/session/usage/aggregate.ts

@@ -23,7 +23,10 @@ export type UsageWindow =
   | { kind: 'custom'; from: string; to: string }
   | { kind: 'all' };
 
-const PRESET_DAYS: Record<Exclude<TimeRangeType, 'custom' | 'all'>, number> = { today: 1, '7d': 7, '30d': 30, '90d': 90 };
+const PRESET_DAYS: Record<Exclude<TimeRangeType, 'custom' | 'all' | 'today'>, number> = { '7d': 7, '30d': 30, '90d': 90 };
+
+/** Every range the tokens endpoint reports, in display order. */
+export const PRESET_RANGES: Exclude<TimeRangeType, 'custom'>[] = ['today', '7d', '30d', '90d', 'all'];
 
 const TTL_MS = 60_000;
 const cache = new Map<string, { at: number; data: UsageAggregate }>();
@@ -75,49 +78,65 @@ function bump(map: Map<string, { tokens: number; cost: number }>, key: string, t
   map.set(key, current);
 }
 
-function inRange(timestampIso: string | undefined, window: UsageWindow, now: number): boolean {
-  if (window.kind === 'all') return true;
-  if (!timestampIso) return true; // keep entries without timestamps (conservative)
-  const ts = Date.parse(timestampIso);
-  if (Number.isNaN(ts)) return true;
-  if (window.kind === 'custom') {
-    const from = Date.parse(`${window.from}T00:00:00`);
-    const to = Date.parse(`${window.to}T23:59:59.999`);
-    if (Number.isNaN(from) || Number.isNaN(to) || from > to) return true;
-    return ts >= from && ts <= to;
-  }
-  if (window.range === 'today') {
-    const d = new Date(ts);
-    const n = new Date(now);
-    return d.getFullYear() === n.getFullYear() && d.getMonth() === n.getMonth() && d.getDate() === n.getDate();
-  }
-  if (window.range === 'all') return true;
-  return now - ts <= PRESET_DAYS[window.range] * 24 * 60 * 60 * 1000;
-}
-
 function cacheKey(window: UsageWindow): string {
   if (window.kind === 'all') return 'all';
   if (window.kind === 'custom') return `custom:${window.from}:${window.to}`;
   return window.range;
 }
 
-/** Aggregate all omp session files within a time window. Cached for 60s. */
-export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregate> {
-  const key = cacheKey(window);
-  const cached = cache.get(key);
-  if (cached && Date.now() - cached.at < TTL_MS) return cached.data;
+/**
+ * One usage record, with everything a window needs to decide whether it counts.
+ *
+ * The scan that produces these is the expensive part — measured 795 ms over 455
+ * transcripts / 327 MB — so it runs ONCE and every window is derived from the
+ * same array. Aggregating per window re-read the whole tree for each of the five
+ * presets plus the active window, which is why `/api/telemetry/tokens` took
+ * 3.3 s cold.
+ */
+interface UsageRecord {
+  /** Epoch ms of the entry's timestamp, or undefined when it has none. */
+  at: number | undefined;
+  /** `YYYY-MM-DD` of `at`, or undefined. */
+  day: string | undefined;
+  model: string;
+  project: string;
+  cost: number;
+  costInput: number;
+  costOutput: number;
+  costCacheRead: number;
+  costCacheWrite: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  reasoning: number;
+  total: number;
+}
+
+interface UsageScan {
+  at: number;
+  records: UsageRecord[];
+  /** Transcripts visited, counted once for every window. */
+  scannedTranscripts: number;
+}
+
+let scanCache: UsageScan | null = null;
+
+/** Every usage record in the sessions tree, read at most once per TTL. */
+async function scanUsage(): Promise<UsageScan> {
+  if (scanCache && Date.now() - scanCache.at < TTL_MS) return scanCache;
 
   const sessionsRoot = getSessionsDir();
-  const aggregate = emptyAggregate();
-  const now = Date.now();
+  const records: UsageRecord[] = [];
+  let scannedTranscripts = 0;
   let projectDirs: string[] = [];
   try {
     projectDirs = (await fs.promises.readdir(sessionsRoot, { withFileTypes: true }))
       .filter((d) => d.isDirectory() || d.isFile())
       .map((d) => d.name);
   } catch {
-    cache.set(key, { at: Date.now(), data: aggregate });
-    return aggregate;
+    scanCache = { at: Date.now(), records, scannedTranscripts };
+    return scanCache;
   }
 
   for (const project of projectDirs) {
@@ -136,37 +155,33 @@ export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregat
     }
 
     for (const file of files) {
-      aggregate.scannedTranscripts++;
+      scannedTranscripts++;
       try {
         const ufile = Bun.file(file);
         if ((await ufile.stat()).size > 64 * 1024 * 1024) continue;
         const entries = parseJsonlLenient<OmpMessageEntry>(await ufile.text());
         for (const entry of entries) {
           if (entry.type !== 'message' || !entry.message?.usage) continue;
-          const ts = entry.timestamp;
-          if (!inRange(ts, window, now)) continue;
           const usage = entry.message.usage;
-          const cost = usage.cost?.total ?? 0;
-          const total = usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
-          aggregate.usageRecords++;
-          aggregate.costTotal += cost;
-          aggregate.costInput += usage.cost?.input ?? 0;
-          aggregate.costOutput += usage.cost?.output ?? 0;
-          aggregate.costCacheRead += usage.cost?.cacheRead ?? 0;
-          aggregate.costCacheWrite += usage.cost?.cacheWrite ?? 0;
-          aggregate.inputTokens += usage.input ?? 0;
-          aggregate.outputTokens += usage.output ?? 0;
-          aggregate.cacheReadTokens += usage.cacheRead ?? 0;
-          aggregate.cacheWriteTokens += usage.cacheWrite ?? 0;
-          aggregate.reasoningTokens += usage.reasoningTokens ?? 0;
-          if (ts) {
-            const day = ts.slice(0, 10);
-            aggregate.activeDays.add(day);
-            bump(aggregate.byDay, day, total, cost);
-          }
-          const model = entry.message.model || 'unknown';
-          bump(aggregate.byModel, model, total, cost);
-          bump(aggregate.byProject, project, total, cost);
+          const ts = entry.timestamp;
+          const parsed = ts ? Date.parse(ts) : Number.NaN;
+          records.push({
+            at: Number.isNaN(parsed) ? undefined : parsed,
+            day: ts ? ts.slice(0, 10) : undefined,
+            model: entry.message.model || 'unknown',
+            project,
+            cost: usage.cost?.total ?? 0,
+            costInput: usage.cost?.input ?? 0,
+            costOutput: usage.cost?.output ?? 0,
+            costCacheRead: usage.cost?.cacheRead ?? 0,
+            costCacheWrite: usage.cost?.cacheWrite ?? 0,
+            input: usage.input ?? 0,
+            output: usage.output ?? 0,
+            cacheRead: usage.cacheRead ?? 0,
+            cacheWrite: usage.cacheWrite ?? 0,
+            reasoning: usage.reasoningTokens ?? 0,
+            total: usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0),
+          });
         }
       } catch {
         // Unreadable transcript — skip rather than failing the whole report.
@@ -174,8 +189,108 @@ export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregat
     }
   }
 
-  const data = aggregate;
+  scanCache = { at: Date.now(), records, scannedTranscripts };
+  return scanCache;
+}
+
+/** Fold the scanned records that fall inside `window` into an aggregate. */
+function foldWindow(records: readonly UsageRecord[], window: UsageWindow, now: number, scannedTranscripts: number): UsageAggregate {
+  const aggregate = emptyAggregate();
+  aggregate.scannedTranscripts = scannedTranscripts;
+  const bounds = windowBounds(window, now);
+  for (const record of records) {
+    // An entry with no usable timestamp is kept by EVERY window — a missing
+    // date is not evidence of age, and this matches the previous per-record
+    // behaviour.
+    if (record.at !== undefined && (record.at < bounds.from || record.at > bounds.to)) continue;
+    aggregate.usageRecords++;
+    aggregate.costTotal += record.cost;
+    aggregate.costInput += record.costInput;
+    aggregate.costOutput += record.costOutput;
+    aggregate.costCacheRead += record.costCacheRead;
+    aggregate.costCacheWrite += record.costCacheWrite;
+    aggregate.inputTokens += record.input;
+    aggregate.outputTokens += record.output;
+    aggregate.cacheReadTokens += record.cacheRead;
+    aggregate.cacheWriteTokens += record.cacheWrite;
+    aggregate.reasoningTokens += record.reasoning;
+    if (record.day) {
+      aggregate.activeDays.add(record.day);
+      bump(aggregate.byDay, record.day, record.total, record.cost);
+    }
+    bump(aggregate.byModel, record.model, record.total, record.cost);
+    bump(aggregate.byProject, record.project, record.total, record.cost);
+  }
+  return aggregate;
+}
+
+interface WindowBounds {
+  /** Inclusive epoch-ms bounds; `-Infinity`/`Infinity` for an unbounded side. */
+  from: number;
+  to: number;
+}
+
+/**
+ * Epoch-ms bounds for a window, computed once per fold.
+ *
+ * `today` is a local CALENDAR day (`setHours(0,0,0,0)`), not "the last 24h":
+ * the panel's "today" tab counts the day the user is in, and the previous
+ * implementation compared year/month/date for the same reason.
+ */
+function windowBounds(window: UsageWindow, now: number): WindowBounds {
+  if (window.kind === 'custom') {
+    const from = Date.parse(`${window.from}T00:00:00`);
+    const to = Date.parse(`${window.to}T23:59:59.999`);
+    if (Number.isNaN(from) || Number.isNaN(to) || from > to) return { from: -Infinity, to: Infinity };
+    return { from, to };
+  }
+  if (window.kind === 'all') return { from: -Infinity, to: Infinity };
+  switch (window.range) {
+    case 'all':
+      return { from: -Infinity, to: Infinity };
+    case 'today': {
+      const start = new Date(now);
+      start.setHours(0, 0, 0, 0);
+      const end = new Date(start);
+      end.setDate(end.getDate() + 1);
+      return { from: start.getTime(), to: end.getTime() - 1 };
+    }
+    default:
+      return { from: now - PRESET_DAYS[window.range] * 24 * 60 * 60 * 1000, to: Infinity };
+  }
+}
+
+/** Aggregate all omp session files within a time window. Cached for 60s. */
+export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregate> {
+  const key = cacheKey(window);
+  const cached = cache.get(key);
+  if (cached && Date.now() - cached.at < TTL_MS) return cached.data;
+
+  const scan = await scanUsage();
+  const data = foldWindow(scan.records, window, Date.now(), scan.scannedTranscripts);
   if (cache.size > 20) cache.clear();
   cache.set(key, { at: Date.now(), data });
   return data;
 }
+
+/**
+ * Aggregate EVERY preset range plus `window` from one scan.
+ *
+ * The tokens endpoint needs all six, and folding them from one scan costs the
+ * fold (linear in records) rather than six more tree reads.
+ */
+export async function aggregateUsageWindows(
+  window: UsageWindow,
+): Promise<{ ranges: Record<Exclude<TimeRangeType, 'custom'>, UsageAggregate>; active: UsageAggregate }> {
+  const scan = await scanUsage();
+  const now = Date.now();
+  const ranges = {} as Record<Exclude<TimeRangeType, 'custom'>, UsageAggregate>;
+  for (const range of PRESET_RANGES) {
+    ranges[range] = foldWindow(scan.records, { kind: 'preset', range }, now, scan.scannedTranscripts);
+  }
+  const active = foldWindow(scan.records, window, now, scan.scannedTranscripts);
+  // Cache each fold under its own key so a later single-window call reuses it.
+  for (const range of PRESET_RANGES) cache.set(range, { at: now, data: ranges[range] });
+  cache.set(cacheKey(window), { at: now, data: active });
+  return { ranges, active };
+}

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();
+  });
+});