ompchamber 0.8.0 → 1.1.0

package/src/server/lib/terminal/history.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { createTerminalHistory, sanitizeReplayChunk, trimUtf8ToBytes } from '@/server/lib/terminal/history';
+
+const decode = (bytes: Uint8Array) => Buffer.from(bytes).toString('utf8');
+const encode = (text: string) => new Uint8Array(Buffer.from(text, 'utf8'));
+
+describe('trimUtf8ToBytes', () => {
+  test('keeps a short buffer whole', () => {
+    const bytes = encode('hello');
+    expect(trimUtf8ToBytes(bytes, 16)).toBe(bytes);
+  });
+
+  test('never starts inside a multi-byte character', () => {
+    // 'é' is 2 bytes, '😀' is 4 — a naive slice at the boundary would leave
+    // continuation bytes at the head and decode the whole tail as U+FFFD.
+    const bytes = encode('ab😀cd');
+    // 8 bytes cut to 5 lands inside the emoji: step forward past it.
+    expect(decode(trimUtf8ToBytes(bytes, 5))).toBe('cd');
+    // Cut to 6 lands exactly on its first byte: the emoji is kept whole.
+    expect(decode(trimUtf8ToBytes(bytes, 6))).toBe('😀cd');
+  });
+
+  test('drops the cut character instead of emitting replacement bytes', () => {
+    const bytes = encode('😀');
+    const trimmed = trimUtf8ToBytes(bytes, 1);
+    expect(decode(trimmed)).toBe('');
+  });
+});
+
+describe('sanitizeReplayChunk', () => {
+  test('keeps ordinary output byte-for-byte', () => {
+    const input = encode('\x1b[31mred\x1b[0m plain\r\n');
+    const { kept, rest } = sanitizeReplayChunk(input);
+    expect(kept).toBe(input);
+    expect(rest.length).toBe(0);
+  });
+
+  test('drops device-attribute and cursor-position queries', () => {
+    const { kept, rest } = sanitizeReplayChunk(encode('a\x1b[c b\x1b[6n c'));
+    expect(decode(kept)).toBe('a b c');
+    expect(rest.length).toBe(0);
+  });
+
+  test('drops color queries in both BEL and ST terminated forms', () => {
+    const { kept } = sanitizeReplayChunk(encode('x\x1b]11;?\x07y\x1b]10;?\x1b\\z'));
+    expect(decode(kept)).toBe('xyz');
+  });
+
+  test('keeps OSC payloads that are not queries', () => {
+    // The window-title sequence a shell emits on every prompt is not a query.
+    const input = encode('\x1b]7;file://host/tmp\x07');
+    expect(sanitizeReplayChunk(input).kept).toBe(input);
+  });
+
+  test('drops a query whose bytes straddle two chunks', () => {
+    // The split is what makes this stateful: neither chunk alone is a complete
+    // query, but their concatenation is one.
+    const history = createTerminalHistory();
+    history.append(encode('abc\x1b['));
+    history.append(encode('c done'));
+    expect(decode(history.replay())).toBe('abc done');
+  });
+
+  test('does not hold back a sequence it can see is not a query', () => {
+    const { kept, rest } = sanitizeReplayChunk(encode('a\x1b[32m'));
+    expect(decode(kept)).toBe('a\x1b[32m');
+    expect(rest.length).toBe(0);
+  });
+});
+
+describe('createTerminalHistory', () => {
+  test('accumulates appended chunks in order', () => {
+    const history = createTerminalHistory();
+    history.append(encode('one '));
+    history.append(encode('two'));
+    expect(decode(history.replay())).toBe('one two');
+  });
+
+  test('trims from the front once the cap is exceeded', () => {
+    const history = createTerminalHistory(16);
+    history.append(encode('aaaaaaaaaa'));
+    history.append(encode('bbbbbbbbbb'));
+    // Whole chunks are dropped, so the retained size lands just under the cap
+    // instead of being re-sliced on every append.
+    expect(decode(history.replay())).toBe('bbbbbbbbbb');
+  });
+
+  test('trims a single oversized chunk at a UTF-8 boundary', () => {
+    const history = createTerminalHistory(5);
+    history.append(encode('ab😀cd'));
+    // A byte-wise cut at offset 3 would land inside the emoji and decode the
+    // rest as U+FFFD; the trim steps forward to the next sequence start.
+    expect(decode(history.replay())).toBe('cd');
+  });
+
+  test('keeps the newest chunks when several are dropped', () => {
+    const history = createTerminalHistory(7);
+    history.append(encode('ab'));
+    history.append(encode('cd'));
+    history.append(encode('ef'));
+    history.append(encode('gh'));
+    // 8 bytes against a 7-byte cap drops the oldest chunk whole.
+    expect(decode(history.replay())).toBe('cdefgh');
+  });
+
+  test('clear empties the replay buffer', () => {
+    const history = createTerminalHistory();
+    history.append(encode('gone'));
+    history.clear();
+    expect(history.replay().length).toBe(0);
+  });
+});

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

@@ -0,0 +1,205 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Server-side scrollback for a PTY session, plus the replay sanitizer.
+ *
+ * Two failure modes this module exists to prevent, both silent when wrong:
+ *
+ * 1. Trimming must be UTF-8-safe. A byte slice at the cap boundary can land
+ *    inside a multi-byte sequence, and every byte after it decodes as U+FFFD —
+ *    the whole tail of the scrollback turns into replacement characters.
+ * 2. A replayed buffer must not contain terminal *queries*. A live client
+ *    answers `CSI c` (device attributes), `CSI 6n` (cursor position) and
+ *    `OSC 10/11;?` (colors) by writing the reply into the PTY, so replaying a
+ *    query makes those bytes arrive at the shell prompt as stray input. Live
+ *    output is byte-for-byte untouched; only the replay copy is filtered.
+ *
+ * Filtering is streaming: a control sequence split across two PTY reads is
+ * carried into the next chunk instead of being emitted half-parsed.
+ */
+
+const MAX_HISTORY_BYTES = 512 * 1024;
+
+/** Longest partial sequence held back before it is flushed as ordinary data. */
+const MAX_PENDING_BYTES = 128;
+
+const ESC = 0x1b;
+const BEL = 0x07;
+const CSI = 0x5b; // [
+const OSC = 0x5d; // ]
+/** DCS / SOS / PM / APC — string sequences terminated by ST only. */
+const STRING_INTROS: Record<number, true> = { 0x50: true, 0x58: true, 0x5e: true, 0x5f: true };
+
+const EMPTY = new Uint8Array(0);
+
+export interface TerminalHistory {
+  append(chunk: Uint8Array): void;
+  /** The replay buffer. Views into it stay valid until the next `append`. */
+  replay(): Uint8Array;
+  clear(): void;
+}
+
+export function createTerminalHistory(maxBytes = MAX_HISTORY_BYTES): TerminalHistory {
+  let chunks: Uint8Array[] = [];
+  let total = 0;
+  let pending: Uint8Array = EMPTY;
+
+  return {
+    append(chunk) {
+      if (chunk.length === 0) return;
+      const input = pending.length === 0 ? chunk : joinParts([pending, chunk]);
+      const { kept, rest } = sanitizeReplayChunk(input);
+      pending = rest;
+      if (kept.length > 0) {
+        chunks.push(kept);
+        total += kept.length;
+      }
+      // Drop whole chunks first: re-slicing the buffer on every append would
+      // copy up to 512 KiB per PTY read, which a chatty program turns into a
+      // memcpy storm. Only the boundary chunk is trimmed byte-wise.
+      while (total > maxBytes && chunks.length > 1) {
+        total -= chunks[0].length;
+        chunks.shift();
+      }
+      if (total > maxBytes && chunks.length === 1) {
+        chunks[0] = trimUtf8ToBytes(chunks[0], maxBytes);
+        total = chunks[0].length;
+      }
+    },
+    replay() {
+      if (chunks.length === 0) return EMPTY;
+      return chunks.length === 1 ? chunks[0] : joinParts(chunks);
+    },
+    clear() {
+      chunks = [];
+      total = 0;
+      pending = EMPTY;
+    },
+  };
+}
+
+/** Keep the last `maxBytes`, never starting inside a multi-byte sequence. */
+export function trimUtf8ToBytes(bytes: Uint8Array, maxBytes: number): Uint8Array {
+  if (bytes.length <= maxBytes) return bytes;
+  let start = bytes.length - maxBytes;
+  // 10xxxxxx is a continuation byte: step forward to the next sequence start.
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start += 1;
+  return bytes.subarray(start);
+}
+
+/**
+ * Split `input` into the bytes that may be replayed and the trailing fragment
+ * of an unfinished control sequence. Dropped sequences are queries only.
+ */
+export function sanitizeReplayChunk(input: Uint8Array): { kept: Uint8Array; rest: Uint8Array } {
+  const parts: Uint8Array[] = [];
+  let from = 0;
+  let i = 0;
+  let dropped = false;
+
+  while (i < input.length) {
+    if (input[i] !== ESC) {
+      i += 1;
+      continue;
+    }
+    const scan = scanEscape(input, i);
+    if (scan === null) {
+      if (i > from) parts.push(input.subarray(from, i));
+      const rest = input.subarray(i);
+      // A program that opened a string sequence and never closed it must not
+      // swallow the rest of the scrollback: emit the fragment and move on.
+      if (rest.length > MAX_PENDING_BYTES) {
+        parts.push(rest);
+        return { kept: joinParts(parts), rest: EMPTY };
+      }
+      return { kept: joinParts(parts), rest };
+    }
+    if (scan.drop) {
+      if (i > from) parts.push(input.subarray(from, i));
+      from = scan.end;
+      dropped = true;
+    }
+    i = scan.end;
+  }
+
+  if (!dropped) return { kept: input, rest: EMPTY };
+  if (from < input.length) parts.push(input.subarray(from));
+  return { kept: joinParts(parts), rest: EMPTY };
+}
+
+interface EscapeScan {
+  /** Index just past the sequence. */
+  end: number;
+  /** True when the sequence is a query the replay must not contain. */
+  drop: boolean;
+}
+
+/** Null means the sequence is not complete within `input`. */
+function scanEscape(input: Uint8Array, start: number): EscapeScan | null {
+  const kind = input[start + 1];
+  if (kind === undefined) return null;
+  if (kind === CSI) return scanCsi(input, start);
+  if (kind === OSC) return scanOsc(input, start);
+  if (STRING_INTROS[kind] === true) return scanString(input, start);
+  // Every other escape is two bytes (ESC c, ESC 7, ESC M, …). Emitting the
+  // pair leaves the remaining bytes identical to the input either way.
+  return { end: start + 2, drop: false };
+}
+
+function scanCsi(input: Uint8Array, start: number): EscapeScan | null {
+  for (let i = start + 2; i < input.length; i += 1) {
+    const byte = input[i];
+    // 0x40–0x7e is the final byte; params/intermediates are below it.
+    if (byte >= 0x40 && byte <= 0x7e) {
+      return { end: i + 1, drop: isCsiQuery(input, start + 2, i) };
+    }
+  }
+  return null;
+}
+
+function isCsiQuery(input: Uint8Array, from: number, final: number): boolean {
+  const finalByte = input[final];
+  if (finalByte === 0x63) return true; // 'c' — DA1/DA2 device-attributes request
+  const params = asciiOf(input, from, final);
+  if (finalByte === 0x6e) return /^\??[56]$/.test(params); // 'n' — DSR / cursor position
+  if (finalByte === 0x70) return params.includes('$') && params.includes('2031'); // DECRQM mode query
+  return false;
+}
+
+function scanOsc(input: Uint8Array, start: number): EscapeScan | null {
+  for (let i = start + 2; i < input.length; i += 1) {
+    const byte = input[i];
+    if (byte === BEL) return { end: i + 1, drop: isOscQuery(input, start + 2, i) };
+    if (byte === ESC && input[i + 1] === 0x5c) return { end: i + 2, drop: isOscQuery(input, start + 2, i) };
+  }
+  return null;
+}
+
+/** Color queries: `OSC 10;?`, `OSC 11;?`, `OSC 12;?` and palette `OSC 4;n;?`. */
+function isOscQuery(input: Uint8Array, from: number, to: number): boolean {
+  const body = asciiOf(input, from, to);
+  const fields = body.split(';');
+  if (!/^(4|10|11|12)$/.test(fields[0])) return false;
+  return fields.length > 1 && fields[fields.length - 1] === '?';
+}
+
+function scanString(input: Uint8Array, start: number): EscapeScan | null {
+  for (let i = start + 2; i < input.length; i += 1) {
+    if (input[i] === ESC && input[i + 1] === 0x5c) return { end: i + 2, drop: false };
+  }
+  return null;
+}
+
+function asciiOf(input: Uint8Array, from: number, to: number): string {
+  let out = '';
+  for (let i = from; i < to; i += 1) out += String.fromCharCode(input[i]);
+  return out;
+}
+
+function joinParts(parts: Uint8Array[]): Uint8Array {
+  if (parts.length === 1) return parts[0];
+  return Buffer.concat(parts);
+}

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

@@ -0,0 +1,338 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The terminal registry: which shells are live, who is watching them, and when
+ * they die.
+ *
+ * One real shell per terminal id, created on the first `attach` (there is no
+ * separate create endpoint to race against), kept alive while clients come and
+ * go, and killed through the process group so the commands it started die with
+ * it. Session mechanics live in `session.server.ts`; this module owns the map,
+ * the viewer sets, the idle reaper and process-exit cleanup.
+ */
+
+import path from 'path';
+import { detectBusyShells, type ShellProcess } from '@/server/lib/terminal/foreground';
+import {
+  TERMINATION_GRACE_MS,
+  TerminalRuntimeError,
+  closeTerminalStream,
+  createSession,
+  signalGroup,
+  snapshotOf,
+  type AttachRequest,
+  type TerminalSession,
+  type TerminalViewer,
+} from '@/server/lib/terminal/session.server';
+import { TERMINAL_MAX_INPUT_BYTES, clampTerminalSize, type TerminalSnapshot } from '@/shared/lib/workspace/terminal/protocol';
+
+const MAX_TERMINALS = 8;
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const IDLE_SWEEP_MS = 60 * 1000;
+/** Quiet period before a resize burst is committed to the PTY. */
+const RESIZE_SETTLE_MS = 120;
+
+export interface TerminalAttachment {
+  snapshot: TerminalSnapshot;
+  /** Retained scrollback, to be sent after the `ready` frame. */
+  replay: Uint8Array;
+}
+
+/**
+ * The registry lives on `globalThis`, not in a module-local binding.
+ *
+ * `bun run --hot` re-evaluates this module on every server-file edit, but the
+ * PTY children are detached sessions that keep running. A module-local `Map`
+ * would be replaced by a fresh empty one on each reload, leaving the previous
+ * shells alive with nothing tracking them — unreachable from the client, never
+ * counted, never reaped, and still holding their slots. Anchoring the map to
+ * the process keeps a reload from orphaning anything.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminals: Map<string, TerminalSession> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalSweep: ReturnType<typeof setInterval> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalResizes: Map<string, ReturnType<typeof setTimeout>> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
+}
+
+const sessions: Map<string, TerminalSession> = (globalThis.__ompChamberTerminals ??= new Map());
+
+function getSweepTimer() {
+  return globalThis.__ompChamberTerminalSweep;
+}
+
+function setSweepTimer(timer: ReturnType<typeof setInterval> | undefined) {
+  globalThis.__ompChamberTerminalSweep = timer;
+  return timer;
+}
+
+function getResizeTimers(): Map<string, ReturnType<typeof setTimeout>> {
+  return (globalThis.__ompChamberTerminalResizes ??= new Map());
+}
+
+/**
+ * Attach `viewer` to `request.id`, creating the shell when the id is unknown.
+ *
+ * Registration and history capture happen in one synchronous block: Bun cannot
+ * interleave a PTY `data` callback inside it, so the viewer can neither miss
+ * output nor receive it twice.
+ *
+ * The cap counts *live* shells only. An exited shell is a corpse holding a
+ * scrollback nobody is reading, and letting corpses consume the budget is how
+ * a session that restarted a shell a few times hits the limit with nothing
+ * running: every restart leaves its predecessor behind.
+ */
+export async function attachTerminal(viewer: TerminalViewer, request: AttachRequest): Promise<TerminalAttachment> {
+  let session = sessions.get(request.id);
+  if (!session) {
+    reclaimExitedTerminals();
+    if ((await countLiveTerminals()) >= MAX_TERMINALS) {
+      throw new TerminalRuntimeError('capacity', `Terminal limit reached (${MAX_TERMINALS} busy shells)`);
+    }
+    const created = await createSession(request);
+    sessions.set(request.id, created);
+    // An exit with nobody watching is the common case for a replaced shell
+    // (restart, repo switch): reap it as soon as it lands instead of leaving
+    // the record for the sweep, which is up to a minute of holding a slot.
+    void created.proc?.exited.then(() => {
+      if (created.viewers.size === 0) forgetTerminal(created.id);
+    });
+    ensureSweeper();
+    session = created;
+  }
+
+  const replay = session.history.replay();
+  const snapshot = snapshotOf(session);
+  session.viewers.add(viewer);
+  session.lastActivity = Date.now();
+  return { snapshot, replay };
+}
+
+/**
+ * Shells that are actually doing work, which is what the cap budgets.
+ *
+ * Two things are deliberately excluded: an exited shell (a corpse with a
+ * scrollback) and a shell sitting at its prompt — the PTY's foreground process
+ * group tells them apart exactly (see `foreground.ts`). Counting idle shells
+ * is how a panel that was restarted or switched a few times pins the budget
+ * with nothing running, and the next attach is refused.
+ */
+export async function countLiveTerminals(): Promise<number> {
+  const running: ShellProcess[] = [];
+  for (const session of sessions.values()) {
+    if (session.status !== 'running' || !session.proc) continue;
+    running.push({ id: session.id, pid: session.proc.pid });
+  }
+  const busy = await detectBusyShells(running);
+  return busy.size;
+}
+
+/**
+ * Drop exited shells that nobody is watching.
+ *
+ * Run before a create, not only on the idle sweep: the sweep is a minute away,
+ * and a burst of restarts inside that window would otherwise be rejected while
+ * every corpse in the way is already dead.
+ */
+export function reclaimExitedTerminals(): number {
+  let reclaimed = 0;
+  for (const [id, session] of sessions) {
+    if (session.status !== 'exited') continue;
+    if (session.viewers.size > 0) continue;
+    forgetTerminal(id);
+    reclaimed += 1;
+  }
+  return reclaimed;
+}
+
+export function detachTerminal(viewer: TerminalViewer, id: string): void {
+  const session = sessions.get(id);
+  if (!session) return;
+  session.viewers.delete(viewer);
+  session.lastActivity = Date.now();
+  // The last viewer leaving a finished shell leaves nothing behind worth
+  // keeping: no process to reattach to, and a scrollback nobody will read.
+  if (session.status === 'exited' && session.viewers.size === 0) forgetTerminal(id);
+}
+
+/**
+ * Live terminal summaries, optionally narrowed to one scope, so a client can
+ * adopt a shell it does not have an id for (a reloaded page, a second tab).
+ *
+ * `busy` marks a shell with a foreground command — the panel shows it as
+ * running, and the cap budgets it. One `ps` for the whole list.
+ */
+export async function listTerminals(root?: string | null, repo?: string | null): Promise<TerminalSnapshot[]> {
+  const scope = root ? (repo && repo !== '.' ? path.join(root, repo) : root) : null;
+  const running: ShellProcess[] = [];
+  const out: TerminalSnapshot[] = [];
+  for (const session of sessions.values()) {
+    if (scope && !isWithin(session.cwd, scope)) continue;
+    if (session.status === 'running' && session.proc) {
+      running.push({ id: session.id, pid: session.proc.pid });
+    }
+    out.push(snapshotOf(session));
+  }
+  const busy = await detectBusyShells(running);
+  return out.map((snapshot) => ({ ...snapshot, busy: busy.has(snapshot.id) }));
+}
+
+function isWithin(target: string, root: string): boolean {
+  return target === root || target.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+}
+
+export function writeTerminalInput(id: string, data: Uint8Array): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  if (data.length === 0 || data.length > TERMINAL_MAX_INPUT_BYTES) return;
+  session.lastActivity = Date.now();
+  try {
+    session.term.write(data);
+  } catch {
+    // The PTY closed between the status check and the write.
+  }
+}
+
+export function resizeTerminal(id: string, cols: number, rows: number): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  const size = clampTerminalSize(cols, rows);
+  if (size.cols === session.cols && size.rows === session.rows) return;
+  session.cols = size.cols;
+  session.rows = size.rows;
+  session.lastActivity = Date.now();
+  try {
+    session.term.resize(size.cols, size.rows);
+  } catch {
+    return;
+  }
+  // resize() updates the winsize but never signals the child, so a TUI would
+  // not repaint. Deliver SIGWINCH ourselves.
+  signalGroup(session, 'SIGWINCH');
+}
+
+/**
+ * Debounce for `resizeTerminal`.
+ *
+ * A panel drag produces a burst of sizes — the pointer moves in steps and
+ * xterm's FitAddon refits on every animation frame — and each accepted size
+ * sends SIGWINCH. The shell answers every one of them by redrawing its prompt,
+ * so a single drag used to print the prompt a dozen times (measured: 10
+ * SIGWINCH in one second for one drag).
+ *
+ * Only the trailing size matters: the PTY ends at the final grid either way,
+ * and a repaint of an intermediate size is invisible work. A single timeout is
+ * reused so the burst coalesces into one signal.
+ */
+const resizeTimers = getResizeTimers();
+
+export function resizeTerminalDebounced(id: string, cols: number, rows: number): void {
+  const pending = resizeTimers.get(id);
+  if (pending) clearTimeout(pending);
+  resizeTimers.set(
+    id,
+    setTimeout(() => {
+      resizeTimers.delete(id);
+      resizeTerminal(id, cols, rows);
+    }, RESIZE_SETTLE_MS),
+  );
+}
+
+/**
+ * Kill the shell for `id`, keeping the record and its viewers: the process exit
+ * is what reports the real exit code, so nothing is synthesized here.
+ *
+ * SIGHUP, not SIGTERM. An interactive shell ignores SIGTERM — verified on
+ * macOS: `kill -TERM` to a zsh process group left it alive indefinitely, while
+ * SIGHUP terminated it in ~150 ms along with its background jobs. SIGHUP is
+ * also the semantically right signal: the terminal is going away.
+ */
+export function closeTerminal(id: string): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  signalGroup(session, 'SIGHUP');
+  setTimeout(() => {
+    if (session.status === 'running') signalGroup(session, 'SIGKILL');
+  }, TERMINATION_GRACE_MS).unref?.();
+}
+
+/**
+ * Drop a session record and release its PTY stream. Used by the idle reaper and
+ * when a client closes a terminal it does not intend to reopen — there are no
+ * viewers left to inform, so a running shell is killed outright.
+ */
+export function forgetTerminal(id: string): void {
+  const session = sessions.get(id);
+  if (!session) return;
+  sessions.delete(id);
+  clearPendingResize(id);
+  session.viewers.clear();
+  if (session.status === 'running') signalGroup(session, 'SIGKILL');
+  closeTerminalStream(session);
+}
+
+function clearPendingResize(id: string): void {
+  const pending = resizeTimers.get(id);
+  if (pending) {
+    clearTimeout(pending);
+    resizeTimers.delete(id);
+  }
+}
+
+/**
+ * Kill every shell at process exit. Synchronous by contract — `exit` handlers
+ * cannot await — so it escalates straight to SIGKILL: a detached shell is its
+ * own session and would otherwise outlive the server.
+ */
+export function disposeAllTerminals(): void {
+  clearInterval(setSweepTimer(undefined));
+  for (const [id, session] of sessions) {
+    clearPendingResize(id);
+    session.viewers.clear();
+    signalGroup(session, 'SIGKILL');
+    closeTerminalStream(session);
+  }
+  sessions.clear();
+}
+
+function ensureSweeper(): void {
+  if (getSweepTimer() !== undefined) return;
+  setSweepTimer(setInterval(() => {
+    // Exited shells are reaped on exit and on detach; this catches the one
+    // that finished while a viewer was still attached to it.
+    reclaimExitedTerminals();
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      // A live shell is only reaped when nobody watches it: an attached
+      // terminal is idle by definition while the user reads its output.
+      if (session.viewers.size > 0) continue;
+      if (now - session.lastActivity < IDLE_TIMEOUT_MS) continue;
+      forgetTerminal(id);
+    }
+  }, IDLE_SWEEP_MS));
+  getSweepTimer()!.unref();
+}
+
+/**
+ * Register process-wide cleanup exactly once. A `bun --hot` reload re-evaluates
+ * this module while the shells live on, so the guard keeps a reload from
+ * stacking duplicate signal handlers.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
+}
+
+if (!globalThis.__ompChamberTerminalCleanupInstalled) {
+  globalThis.__ompChamberTerminalCleanupInstalled = true;
+  process.once('exit', disposeAllTerminals);
+  process.once('SIGINT', disposeAllTerminals);
+  process.once('SIGTERM', disposeAllTerminals);
+}