ompchamber 3.1.0 → 3.2.0

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/lifecycle/restart.ts

@@ -25,7 +25,7 @@ import { join as joinPath, resolve as resolvePath } from 'node:path';
 
 import { resolveBunBin } from '@/server/lib/lifecycle/bun';
 import { listInstanceRecords } from '@/server/lib/lifecycle/instance';
-import { resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
+import { isCliManaged, resolveLaunchMode, unmanagedReason } from '@/server/lib/lifecycle/launch-mode';
 
 /** Package root of the running copy: src/server/lib/lifecycle -> four levels up. */
 const PKG_ROOT = resolvePath(import.meta.dir, '..', '..', '..', '..');
@@ -45,20 +45,15 @@ export interface SelfRestartPlan {
 }
 
 /**
- * True when the CLI owns this instance's lifecycle and may replace it. `direct`
- * is every server OMPChamber did not start: `bun run dev`, `bun run start`, a
- * manual `bun src/server/index.ts`, or an external supervisor.
+ * One-line reason an instance is left running, shared by the CLI and console.
+ * The clause comes from `unmanagedReason` so `stop`, `restart` and `update`
+ * cannot classify the same `launchMode` differently.
  */
-export function isAutoRestartable(launchMode: string | null | undefined): boolean {
-  return launchMode === 'daemon' || launchMode === 'foreground';
-}
-
-/** One-line reason an instance is left running, shared by the CLI and console. */
 export function skipRestartNote(launchMode: string | null | undefined): string {
-  if (launchMode === 'direct') {
-    return 'this instance runs from source (`bun run dev` / `bun run start`) — start it again to apply the update';
-  }
-  return 'this instance is not managed by the ompchamber CLI — restart it yourself to apply the update';
+  const nextStep = launchMode === 'direct'
+    ? 'start it again to apply the update'
+    : 'restart it yourself to apply the update';
+  return `this instance ${unmanagedReason(launchMode)} — ${nextStep}`;
 }
 
 /** The record this process wrote for itself; falls back to the env it was launched with. */
@@ -89,7 +84,7 @@ export function scheduleSelfRestart(): SelfRestartPlan {
     return { restarting: false, message: 'This instance could not be identified — restart it yourself to apply the update.' };
   }
 
-  if (!isAutoRestartable(self.launchMode)) {
+  if (!isCliManaged(self.launchMode)) {
     return { restarting: false, message: skipRestartNote(self.launchMode) };
   }
 

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.

package/src/server/lib/omp/rpc/subagent-liveness.ts

@@ -21,22 +21,12 @@
  * goes stale).
  */
 
-import { parseSubagentLifecycle, parseSubagentProgress } from '@/shared/lib/omp/subagent/parse';
-import { isRecord } from '@/shared/lib/util/guards';
-import type { SubagentProgress } from '@/shared/types/omp/subagent';
+import { parseSubagentLifecycle, readSubagentProgressFrame } from '@/shared/lib/omp/subagent/parse';
 
 /** Statuses that end a subagent. Mirrors omp's own registry, which deletes an
  *  entry the moment a non-`started` lifecycle arrives. */
 const TERMINAL_STATUS: Record<string, true> = { completed: true, failed: true, aborted: true };
 
-/** Progress frames arrive AgentProgress-shaped; some wrappers nest the snapshot. */
-function readProgress(payload: unknown): SubagentProgress | undefined {
-  const direct = parseSubagentProgress(payload);
-  if (!isRecord(payload) || !isRecord(payload.progress)) return direct;
-  const nested = parseSubagentProgress(payload.progress);
-  return nested ? { ...nested, id: nested.id ?? direct?.id, index: nested.index ?? direct?.index } : direct;
-}
-
 export class SubagentLiveness {
   private readonly lastSeen = new Map<string, number>();
   /** index → key, so an id-less progress frame lands on the entry its lifecycle
@@ -54,7 +44,7 @@ export class SubagentLiveness {
     }
 
     if (frame.type === 'subagent_progress') {
-      const progress = readProgress(frame.payload);
+      const progress = readSubagentProgressFrame(frame.payload);
       if (!progress) return;
       const index = progress.index !== undefined && progress.index >= 0 ? progress.index : undefined;
       const key = progress.id ?? (index !== undefined ? this.keyByIndex.get(index) ?? `idx:${index}` : undefined);

package/src/server/lib/omp/session/file-scan.ts

@@ -37,6 +37,12 @@ export interface SessionFilePrefix {
   text: string;
   size: number;
   mtime: Date;
+  /**
+   * The same mtime as a raw `stat.mtimeMs`, for callers that key a cache on it.
+   * `Date.getTime()` truncates the fractional millisecond APFS reports, so a
+   * Date comparison never matches a fresh stat.
+   */
+  mtimeMs: number;
 }
 
 export async function readTextPrefix(filePath: string, prefixBytes: number): Promise<SessionFilePrefix> {
@@ -44,7 +50,7 @@ export async function readTextPrefix(filePath: string, prefixBytes: number): Pro
   const stat = await file.stat();
   const prefixLength = Math.min(prefixBytes, stat.size);
   const text = prefixLength > 0 ? await file.slice(0, prefixLength).text() : '';
-  return { text, size: stat.size, mtime: new Date(stat.mtimeMs) };
+  return { text, size: stat.size, mtime: new Date(stat.mtimeMs), mtimeMs: stat.mtimeMs };
 }
 
 /**