ompchamber 3.1.1 → 3.3.0

package/src/server/lib/lifecycle/flock.ts

@@ -0,0 +1,199 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `flock(2)` through `bun:ffi`, for the port-handover lock.
+ *
+ * The kernel releases a flock when the holding process dies, which is exactly
+ * the property a startup lock wants — no PID readback, no stale-holder
+ * classification, and no polling loop to detect a dead holder. The previous
+ * PID-file scheme needed all three: it wrote a PID, re-read it on every retry,
+ * asked the OS whether that PID was still OMPChamber (four `sysctl` calls per
+ * question on macOS), and deleted the file to release.
+ *
+ * `flock` is exported by `libc.dylib` / `libSystem.B.dylib` / `libc.so.6`, so it
+ * is reachable the same way `lib/lifecycle/proc/darwin.ts` reaches `sysctl`.
+ * Windows has no `flock`, and a host can refuse `dlopen` or answer `ENOLCK`
+ * (some NFS mounts) — `flockAvailable()` is a real capability probe, and every
+ * caller keeps its own fallback for the false case.
+ *
+ * **The lock file is never unlinked while it may be held.** Removing it is the
+ * classic flock race: another process that already opened the path keeps a
+ * handle on the unlinked inode and acquires it successfully while a third
+ * process creates a fresh file at the same path and also succeeds. Leaving the
+ * file in place makes the inode the lock, which is what flock is for; the file
+ * is an empty marker, one per port.
+ */
+
+import fs from 'fs';
+import { dlopen, FFIType } from 'bun:ffi';
+import type { FFIFunction, Library } from 'bun:ffi';
+
+const LOCK_EX = 2;
+/** Non-blocking: fail immediately rather than waiting inside the syscall. */
+const LOCK_NB = 4;
+
+const FLOCK_SYMBOLS = {
+  flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+} satisfies Record<string, FFIFunction>;
+
+/** Library names to try, in the order each platform resolves them. */
+const LIBC_NAMES = ['libc.dylib', 'libSystem.B.dylib', 'libc.so.6'] as const;
+
+/**
+ * Held leases and the probe result, on `globalThis` rather than in module
+ * bindings.
+ *
+ * A `bun --hot` reload re-evaluates this module while the process (and its open
+ * descriptors) lives on. A fresh module-level Map would forget that this PID
+ * already holds the port's lock, so the reloaded server would open a second fd,
+ * find the lock taken by its own previous fd, and refuse to start.
+ */
+interface FlockHost {
+  /** `lockPath` → the fd holding it and how many acquires it backs. */
+  held: Map<string, { fd: number; refs: number }>;
+  /** Tri-state capability probe: undefined until asked, then lib-or-null. */
+  available: boolean | undefined;
+  /** The opened library, shared across reloads. */
+  lib: Library<typeof FLOCK_SYMBOLS> | null | undefined;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberFlock: FlockHost | undefined;
+}
+
+function host(): FlockHost {
+  return (globalThis.__ompChamberFlock ??= { held: new Map(), available: undefined, lib: undefined });
+}
+
+/** libc with `flock`, or null when this host has none. Cached for the process. */
+function libc(): Library<typeof FLOCK_SYMBOLS> | null {
+  const state = host();
+  if (state.lib !== undefined) return state.lib;
+  state.lib = null;
+  if (process.platform === 'win32') return state.lib;
+  for (const name of LIBC_NAMES) {
+    try {
+      state.lib = dlopen(name, FLOCK_SYMBOLS);
+      return state.lib;
+    } catch {
+      // Try the next name; a host without any of them keeps the null answer.
+    }
+  }
+  return state.lib;
+}
+
+/**
+ * True when `flock(2)` actually works here — the symbol resolving is not
+ * enough, because a filesystem can answer `ENOLCK`. Probed once, on a
+ * throwaway file, so a caller can pick its mechanism up front instead of
+ * discovering mid-wait that the syscall never works.
+ */
+export function flockAvailable(): boolean {
+  const state = host();
+  if (state.available !== undefined) return state.available;
+  state.available = false;
+  const symbols = libc();
+  if (!symbols) return false;
+  const probePath = `${process.env.TMPDIR ?? '/tmp'}/ompchamber-flock-${process.pid}`;
+  let fd: number | null = null;
+  try {
+    fd = fs.openSync(probePath, 'a');
+    const ok = symbols.symbols.flock(fd, LOCK_EX | LOCK_NB) === 0;
+    fs.closeSync(fd);
+    fd = null;
+    fs.rmSync(probePath, { force: true });
+    if (!ok) {
+      // The probe file was somehow already locked — treat the capability as
+      // unproven rather than reporting a lock we do not hold.
+      state.lib = null;
+      return false;
+    }
+    state.available = true;
+    return true;
+  } catch {
+    state.lib = null;
+    return false;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Already closed.
+      }
+    }
+  }
+}
+
+export interface FlockHandle {
+  /** Release the lease. Idempotent. */
+  release: () => void;
+}
+
+/**
+ * Take `LOCK_EX | LOCK_NB` on `lockPath`, or null when another process holds
+ * it. Returns null too when `flock` is unavailable — callers must then use
+ * their own mechanism.
+ *
+ * The fd is kept open for as long as the lease lives: closing it is what
+ * releases the lock, and the kernel does the same on process death.
+ */
+export function tryFlock(lockPath: string): FlockHandle | null {
+  const state = host();
+  const existing = state.held.get(lockPath);
+  if (existing) {
+    // Re-entrant within one process: flock is per open-file-description, so a
+    // second fd here would block against our own lock.
+    existing.refs += 1;
+    return { release: () => releaseFlock(lockPath) };
+  }
+  const symbols = libc();
+  if (!symbols) return null;
+  let fd: number;
+  try {
+    // `a` creates it when absent and never truncates; the file's content is
+    // irrelevant (the inode is the lock), but the PID is useful when a human
+    // looks at the directory.
+    fd = fs.openSync(lockPath, 'a');
+  } catch {
+    return null;
+  }
+  let acquired = false;
+  try {
+    acquired = symbols.symbols.flock(fd, LOCK_EX | LOCK_NB) === 0;
+  } catch {
+    acquired = false;
+  }
+  if (!acquired) {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      // Already closed.
+    }
+    return null;
+  }
+  try {
+    fs.writeFileSync(fd, String(process.pid));
+  } catch {
+    // Informational only.
+  }
+  state.held.set(lockPath, { fd, refs: 1 });
+  return { release: () => releaseFlock(lockPath) };
+}
+
+function releaseFlock(lockPath: string): void {
+  const state = host();
+  const entry = state.held.get(lockPath);
+  if (!entry) return;
+  entry.refs -= 1;
+  if (entry.refs > 0) return;
+  state.held.delete(lockPath);
+  try {
+    fs.closeSync(entry.fd);
+  } catch {
+    // Already closed; the kernel released the lock either way.
+  }
+}

package/src/server/lib/lifecycle/identity.ts

@@ -37,7 +37,11 @@ export type ProcessState = 'dead' | 'matched' | 'mismatched' | 'unknown';
  */
 export function isProcessAlive(pid: number): boolean {
   if (!Number.isFinite(pid) || pid <= 0) return false;
-  return processProbe.isAlive(pid) && !processProbe.isZombie(pid);
+  const liveness = processProbe.liveness(pid);
+  // A zombie is NOT alive: it holds no port and will never run again. An
+  // `unknown` (a probe that could not answer) keeps the previous bias and
+  // counts as alive, so a sandboxed host cannot make a live server look dead.
+  return liveness === 'alive' || liveness === 'unknown';
 }
 
 /**

package/src/server/lib/lifecycle/listener.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The HTTP listener this process is serving on.
+ *
+ * Two consumers need it and neither can import it: the shell renderer, which
+ * asks the listener for its own `/_shell` route (Bun renders an HTML route only
+ * while serving), and the dev asset proxy, which asks it for the assets Bun's
+ * own routing table owns. The reference is injected rather than imported because
+ * `index.ts` owns the listener and imports both of them — a direct import would
+ * be a cycle.
+ */
+
+type Listener = { url: URL } | null;
+
+let listener: Listener = null;
+
+/** Called by the server entry once its listener is up. */
+export function setListener(server: { url: URL }): void {
+  listener = server;
+}
+
+/** The listener's base URL, or null before it is up. */
+export function listenerUrl(): URL | null {
+  return listener?.url ?? null;
+}

package/src/server/lib/lifecycle/port-guard.ts

@@ -22,6 +22,7 @@
 
 import fs from 'fs';
 
+import { flockAvailable, tryFlock } from '@/server/lib/lifecycle/flock';
 import { getProcessState } from '@/server/lib/lifecycle/identity';
 import { describeOccupant, findOccupant } from '@/server/lib/lifecycle/occupant';
 import { getLockPath } from '@/server/lib/lifecycle/paths';
@@ -48,13 +49,27 @@ export interface PortLock {
  * Two starters racing on one free port would each probe it as free and then
  * fight over the bind, with the loser reporting a bare `EADDRINUSE` against a
  * process it cannot identify yet. Holding the lock across probe-and-bind makes
- * the loser fail with a message that names the actual situation. A lock whose
- * holder is dead (or is not OMPChamber, i.e. a recycled PID) is reclaimed.
+ * the loser fail with a message that names the actual situation.
  *
- * Returns null when another starter holds the lock through the wait window.
+ * The mechanism is `flock(2)` when the host has it (see `flock.ts`): the kernel
+ * releases it on process death, so there is no stale-holder case to detect and
+ * no polling loop. The PID-file path below stays as the fallback for a host
+ * without `flock` (Windows, a filesystem answering `ENOLCK`); it needs the
+ * extra machinery — PID readback, `getProcessState` classification, and
+ * reclaiming a lock whose holder died or whose PID was recycled.
  */
 export async function acquirePortLock(port: number, waitMs = LOCK_WAIT_MS): Promise<PortLock | null> {
   const lockPath = getLockPath(port);
+  if (flockAvailable()) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+      const handle = tryFlock(lockPath);
+      if (handle) return handle;
+      if (Date.now() >= deadline) return null;
+      await Bun.sleep(150);
+    }
+  }
+
   const deadline = Date.now() + waitMs;
   for (;;) {
     try {

package/src/server/lib/lifecycle/proc/darwin.ts

@@ -28,7 +28,7 @@
 import { dlopen, FFIType, ptr } from 'bun:ffi';
 import type { FFIFunction, Library } from 'bun:ffi';
 
-import type { ProcessProbe } from '@/server/lib/lifecycle/proc/types';
+import type { ProcessLiveness, ProcessProbe } from '@/server/lib/lifecycle/proc/types';
 
 /** `sysctl` MIB pieces. */
 const CTL_KERN = 1;
@@ -45,8 +45,21 @@ const KINFO_PROC_BYTES = 648;
 const P_STAT_OFFSET = 36;
 /** Darwin `p_stat` values. */
 const SZOMB = 5;
+/** `p_stat` values that mean "exited but not yet reaped". */
 const SZOMB_LIKE = new Set([SZOMB, 6 /* SDEAD */]);
 
+/**
+ * Scratch for the `sysctl(KERN_PROC_PID)` call below, at module scope.
+ *
+ * One `isProcessAlive` asks this question twice (liveness then zombie), and
+ * `getProcessState` asks it twice more — so the buffers are reused rather than
+ * reallocated per call, the same reasoning as `bsdInfo` further down. Safe
+ * because the whole probe is synchronous: no `await` can interleave a caller.
+ */
+const procMib = new Int32Array([CTL_KERN, KERN_PROC, KERN_PROC_PID, 0]);
+const procSize = new BigUint64Array([BigInt(KINFO_PROC_BYTES)]);
+const procBuffer = new Uint8Array(KINFO_PROC_BYTES);
+
 /** Upper bound on a command line block; the kernel truncates instead. */
 const ARGV_BUFFER_BYTES = 262_144;
 const PATH_BUFFER_BYTES = 4096;
@@ -106,24 +119,27 @@ const BSDINFO_PID_OFFSET = 12;
 const BSDINFO_TPGID_OFFSET = 112;
 
 /**
- * `p_stat` for a live PID, or null when the PID does not exist.
+ * `p_stat` for a PID, `'absent'` when the kernel says no such process, or null
+ * when the call itself failed.
  *
- * A zero-length result is the kernel saying "no such process"; the call itself
- * failing (rc !== 0) is reported as null too, and callers then fall back.
+ * The two failure modes are NOT the same question and callers must not merge
+ * them: `sysctl(KERN_PROC_PID)` answers rc=0 with a zero-length reply for a PID
+ * that does not exist (verified: 999999 → rc 0, size 0), while a sandbox denies
+ * the call with a non-zero rc. Reading the second as "dead" would let a sandbox
+ * report a live server as gone.
  */
-function procStatus(pid: number): number | null {
+function procStatus(pid: number): number | 'absent' | null {
   const bound = bindLibs();
   if (bound === null) return null;
-  const mib = new Int32Array([CTL_KERN, KERN_PROC, KERN_PROC_PID, pid]);
-  const size = new BigUint64Array([BigInt(KINFO_PROC_BYTES)]);
-  const buffer = new Uint8Array(KINFO_PROC_BYTES);
+  procMib[3] = pid;
+  procSize[0] = BigInt(KINFO_PROC_BYTES);
   try {
-    if (bound.libc.symbols.sysctl(ptr(mib), 4, ptr(buffer), ptr(size), null, 0) !== 0) return null;
+    if (bound.libc.symbols.sysctl(ptr(procMib), 4, ptr(procBuffer), ptr(procSize), null, 0) !== 0) return null;
   } catch {
     return null;
   }
-  if (Number(size[0]) === 0) return null;
-  return buffer[P_STAT_OFFSET];
+  if (Number(procSize[0]) === 0) return 'absent';
+  return procBuffer[P_STAT_OFFSET];
 }
 
 /**
@@ -197,21 +213,40 @@ function signalAlive(pid: number): boolean {
   }
 }
 
+/**
+ * Liveness in one lookup, for both the probe and its own `isAlive`/`isZombie`
+ * shims. A method calling `this` would break the moment a caller destructured
+ * the probe, and the session registry does pass probes around by reference.
+ */
+function darwinLiveness(pid: number): ProcessLiveness {
+  const status = procStatus(pid);
+  if (status === 'absent') return 'dead';
+  if (status !== null) return SZOMB_LIKE.has(status) ? 'zombie' : 'alive';
+  // The syscall itself failed (sandbox). A path or a signal still separates
+  // "exists" from "gone" — a path read answers for root-owned PIDs, and signal
+  // 0 answers for the rest — so only a PID that fails both is reported dead.
+  // Anything else is `unknown`, which callers treat as alive-but-unverified.
+  if (executablePath(pid) !== null || signalAlive(pid)) return 'alive';
+  return 'unknown';
+}
+
 export const darwinProbe: ProcessProbe = {
   commandLine(pid) {
     const args = argvOf(pid);
     if (args && args.length > 0) return args.join(' ');
     return executablePath(pid);
   },
+  liveness: darwinLiveness,
   isAlive(pid) {
-    const status = procStatus(pid);
-    if (status !== null) return !SZOMB_LIKE.has(status);
-    // The syscall itself failed (sandbox) — liveness alone is all that is left.
-    return executablePath(pid) !== null || signalAlive(pid);
+    // `procStatus` already reports a zombie as not-alive, so the old
+    // `isAlive && !isZombie` pair asked it twice for one answer.
+    const liveness = darwinLiveness(pid);
+    // `unknown` keeps the previous fallback's bias: a sandboxed host must not
+    // make a live server look dead.
+    return liveness === 'alive' || liveness === 'unknown';
   },
   isZombie(pid) {
-    const status = procStatus(pid);
-    return status !== null && SZOMB_LIKE.has(status);
+    return darwinLiveness(pid) === 'zombie';
   },
   /**
    * `e_tpgid` — the field `ps -o tpgid=` prints. `proc_pidinfo` is the cheap

package/src/server/lib/lifecycle/proc/linux.ts

@@ -49,6 +49,20 @@ function statTail(pid: number): string[] | null {
  */
 const TPGID_FIELD = 5;
 
+/**
+ * `{ state, tpgid }` from ONE `/proc/<pid>/stat` read.
+ *
+ * `isZombie` and `foregroundGroup` both need this file, and the terminal cap
+ * asks both about the same shell; reading it once per question instead of twice
+ * is why the two are resolved together.
+ */
+function procStat(pid: number): { state: string; tpgid: number } | null {
+  const fields = statTail(pid);
+  if (fields === null) return null;
+  const tpgid = Number(fields[TPGID_FIELD]);
+  return { state: fields[STATE_FIELD], tpgid: Number.isFinite(tpgid) ? tpgid : 0 };
+}
+
 export const linuxProbe: ProcessProbe = {
   commandLine(pid) {
     const raw = readFile(`/proc/${pid}/cmdline`);
@@ -59,22 +73,30 @@ export const linuxProbe: ProcessProbe = {
     // Kernel threads have no argv — `comm` is all the identity there is.
     return readFile(`/proc/${pid}/comm`)?.trim() || null;
   },
+  liveness(pid) {
+    // A `/proc` entry exists for a zombie too, so the state field is what
+    // separates a corpse from a running process.
+    const stat = procStat(pid);
+    if (stat === null) {
+      // No `stat` file: either the PID is gone or the read failed. `existsSync`
+      // keeps the previous answer for a process with no readable stat.
+      return fs.existsSync(`/proc/${pid}`) ? 'unknown' : 'dead';
+    }
+    return ZOMBIE_STATES.has(stat.state) ? 'zombie' : 'alive';
+  },
   isAlive(pid) {
     // A `/proc` entry exists for a zombie too, so liveness is "the directory is
     // there"; `isZombie` is what separates a corpse from a running process.
     return fs.existsSync(`/proc/${pid}`);
   },
   isZombie(pid) {
-    const fields = statTail(pid);
-    if (fields === null) return false;
-    return ZOMBIE_STATES.has(fields[STATE_FIELD]);
+    const stat = procStat(pid);
+    return stat !== null && ZOMBIE_STATES.has(stat.state);
   },
   foregroundGroup(pid) {
     // Already read for `isZombie` on the same question, so this costs no extra
     // syscall beyond the file read itself.
-    const fields = statTail(pid);
-    if (fields === null) return null;
-    const tpgid = Number(fields[TPGID_FIELD]);
-    return Number.isFinite(tpgid) ? tpgid : null;
+    const stat = procStat(pid);
+    return stat === null ? null : stat.tpgid;
   },
 };

package/src/server/lib/lifecycle/proc/ps.ts

@@ -67,6 +67,13 @@ export const psProbe: ProcessProbe = {
     const row = processTable().find((entry) => entry.pid === pid);
     return row && row.command.length > 0 ? row.command : null;
   },
+  liveness(pid) {
+    // The table already carries the state column, so liveness and zombie-ness
+    // are one lookup; the signal check stays for the no-`ps` case.
+    const row = processTable().find((entry) => entry.pid === pid);
+    if (row) return row.state.startsWith('Z') ? 'zombie' : 'alive';
+    return signalAlive(pid) ? 'unknown' : 'dead';
+  },
   isAlive(pid) {
     if (!signalAlive(pid)) return false;
     const row = processTable().find((entry) => entry.pid === pid);

package/src/server/lib/lifecycle/proc/types.ts

@@ -11,9 +11,26 @@
  * PID is never worth failing a request over, and a platform that cannot answer
  * says so (`null` / `false`) so the caller can fall back.
  */
+export type ProcessLiveness =
+  /** The PID exists and is running. */
+  | 'alive'
+  /** Exited, waiting for its parent to reap it: holds no port, never runs again. */
+  | 'zombie'
+  /** No such process. */
+  | 'dead'
+  /** The platform could not answer — callers must NOT read this as "dead". */
+  | 'unknown';
+
 export interface ProcessProbe {
   /** Command line of a live PID, or null when unreadable. */
   commandLine(pid: number): string | null;
+  /**
+   * Liveness in ONE lookup. This is the question `identity.ts` actually asks,
+   * and asking it as `isAlive(pid) && !isZombie(pid)` made the macOS probe
+   * issue the identical `sysctl(KERN_PROC_PID)` twice for the same PID
+   * (measured 21.3 µs against 5.3 µs for the single read).
+   */
+  liveness(pid: number): ProcessLiveness;
   /** True when the PID exists. */
   isAlive(pid: number): boolean;
   /** True when the PID is defunct — exited but not yet reaped by its parent.

package/src/server/lib/lifecycle/proc/win32.ts

@@ -40,6 +40,11 @@ export const win32Probe: ProcessProbe = {
   commandLine() {
     return null;
   },
+  liveness(pid) {
+    // No zombie state is observable on Windows (a process object lives until
+    // its last handle closes), so signal 0 is the whole answer.
+    return signalAlive(pid) ? 'alive' : 'dead';
+  },
   isAlive: signalAlive,
   isZombie() {
     return false;

package/src/server/lib/observer-ws.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared lifecycle for the chamber's observer WebSocket streams (agent events,
+ * BTW frames). Both routes hand-rolled the same connection state — an
+ * unsubscribe slot, a ping/pong keepalive, a latest-wins coalescer, and a
+ * teardown that releases all three — so the policy lives here once, exactly as
+ * `createSseStream` and `createEventCoalescer` own the SSE side.
+ *
+ * **Per-connection state must live on `ws.data`, never in a `WeakMap` keyed by
+ * the `ws` object.** Elysia's Bun adapter constructs a NEW `ElysiaWS` wrapper
+ * for every callback and hands `pong` the RAW `ServerWebSocket` rather than a
+ * wrapper at all (verified on 1.4.30: `open` receives `ElysiaWS`, `pong`
+ * receives the raw socket, and a `WeakMap` lookup in either misses). A missed
+ * `pong` lookup never clears `awaitingPong`, so the second heartbeat tears down
+ * a socket the client is still reading — every observer stream died at 60s
+ * (measured: a fresh chamber instance closed a healthy socket at 60.005ms with
+ * `STREAM_HEARTBEAT_MS` = 30s). A missed `close` lookup leaks the interval, the
+ * coalescer and the session subscription for the process's lifetime.
+ *
+ * `ws.data` is one object shared by every callback, so it is the only stable
+ * key. The routes keep their own store object in it and pass it here.
+ */
+
+import { createEventCoalescer, type EventCoalescer } from '@/server/lib/sse';
+import { STREAM_HEARTBEAT_MS } from '@/shared/lib/workspace/refresh-cadence';
+
+/** Coalesce replaceable 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 frame. */
+const FLUSH_DELAY_MS = 50;
+
+/** The Bun server socket, narrowed to the two members this module reads. */
+interface ObserverRawSocket {
+  bufferedAmount?: number;
+  ping?: () => void;
+}
+
+/** The Elysia `ws` context, narrowed to the members this module uses. */
+export interface ObserverSocket {
+  raw: unknown;
+  send: (data: string) => unknown;
+  close: () => void;
+}
+
+/** State a route keeps on `ws.data`; `closed` is also read by its own guards. */
+export interface ObserverConnectionState {
+  closed: boolean;
+  unsubscribe: (() => void) | null;
+  heartbeat: ReturnType<typeof setInterval> | null;
+  awaitingPong: boolean;
+  coalescer: EventCoalescer | null;
+  /** Idempotent release, installed by `attachObserverStream`. The route's
+   *  `close` handler calls it; before attach it is a no-op. */
+  teardown: () => void;
+}
+
+/** A fresh state object for `ws.data`. */
+export function createObserverState(): ObserverConnectionState {
+  return {
+    closed: false,
+    unsubscribe: null,
+    heartbeat: null,
+    awaitingPong: false,
+    coalescer: null,
+    teardown: () => {},
+  };
+}
+
+/** What an attached connection exposes back to its route. */
+export interface ObserverStream {
+  /** Emit one frame through the coalescer (latest-wins while backpressured). */
+  push: (event: string, data: unknown) => void;
+}
+
+/**
+ * Attach the coalescer + keepalive to one accepted connection. Teardown is
+ * installed on `state` (the route's `close` handler calls it) and is idempotent
+ * from any path: a heartbeat, a send failure, or the route's own exit.
+ *
+ * The first frame is the route's own `connected` greeting, pushed by the caller.
+ */
+export function attachObserverStream(state: ObserverConnectionState, ws: ObserverSocket): ObserverStream {
+  // 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 ObserverRawSocket;
+
+  const teardown = (): void => {
+    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,
+  });
+
+  // Protocol-level keepalive: a client that misses a full ping cycle is gone,
+  // and a live one answers without any application-level traffic. The pong
+  // arrives on the route's `pong` handler, which clears `awaitingPong` through
+  // the SAME state object.
+  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);
+
+  state.teardown = teardown;
+  return { push: (event, data) => state.coalescer?.push(event, data) };
+}

package/src/server/lib/omp/rpc/constants.ts

@@ -125,6 +125,15 @@ export const PASSTHROUGH_COMMANDS = new Set([
   'login',
 ]);
 
+// Commands that only READ live process state, with an RPC-free on-disk
+// equivalent. A live session answers them on the fast path; for one the chamber
+// does not manage, the spawn path must refuse them (409) rather than boot an
+// omp child to answer a read. The sidebar renders a roster row for every
+// session in the list, so an unconditional probe started a process per finished
+// session merely looked at (measured: the omp process count grew on a session
+// whose liveness probe had just reported `running: false`).
+export const OBSERVER_ONLY_COMMANDS = new Set(['get_subagents', 'get_subagent_messages']);
+
 // Commands that can carry user-attached images to the model. All of them must
 // pass the same server-side per-image/count/aggregate validation before the
 // payload reaches omp — a client is free to POST any of them directly.