ompchamber 0.3.0 → 0.5.0

package/src/server/lib/omp/core/startup.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Startup gate: the chamber must not run without a resolvable `omp` binary.
+ *
+ * Every live capability — RPC agent sessions, config get/set, session state,
+ * model lists, updates — shells out to that binary (see ./cli.ts), so a missing
+ * install is not a degraded mode to browse into: the UI would open onto an
+ * empty shell whose every action fails. Both entry points call this before
+ * binding a port (src/server/index.ts) or spawning a detached server
+ * (src/cli/lib/commands/serve.js), turning the failure into one actionable line
+ * instead of a health check that never passes.
+ *
+ * `MOCK=true` is exempt by definition — demo mode exists to run on presets
+ * without a real omp install.
+ */
+
+import { resolveOmpBin } from '@/server/lib/omp/core/cli';
+import { getAgentDir, getConfigRoot } from '@/server/lib/omp/core/paths';
+import { isMockMode } from '@/server/mock.server';
+
+/** Null when the app may start; otherwise the message to print before exiting. */
+export function ompStartupError(): string | null {
+  if (isMockMode()) return null;
+  if (resolveOmpBin()) return null;
+  return [
+    'omp binary not found — OMPChamber cannot start.',
+    'Agent sessions, omp config, session state and updates all run through the `omp` CLI,',
+    'so the binary must be resolvable before the server starts.',
+    'Install AI Oh-My-Pi and put `omp` on your PATH, or set OMPCHAMBER_OMP_BIN=/path/to/omp.',
+    'To run on demo data without an omp install, start with MOCK=true.',
+  ].join('\n');
+}
+
+interface OmpStartupPaths {
+  /** Resolved `omp` executable, or null when unresolved (mock mode). */
+  bin: string | null;
+  /** `~/.omp` — PI_CONFIG_DIR rename applied. */
+  configDir: string;
+  /** `~/.omp/agent` — PI_CODING_AGENT_DIR override applied. */
+  agentDir: string;
+}
+
+/** Startup banner lines. The caller owns the prefix.
+ *
+ *  These are the locations the running process actually uses: the executable it
+ *  spawns and the agent tree it reads. Printing them makes a misdirected install
+ *  (two omps on PATH, a stray PI_CODING_AGENT_DIR) visible in the log instead of
+ *  inferred from empty session lists. */
+export function ompStartupLogLines(): string[] {
+  const paths: OmpStartupPaths = {
+    bin: resolveOmpBin(),
+    configDir: getConfigRoot(),
+    agentDir: getAgentDir(),
+  };
+  return [
+    `omp binary:     ${paths.bin ?? 'not found (MOCK mode — presets only)'}`,
+    `omp config dir: ${paths.configDir}`,
+    `omp agent dir:  ${paths.agentDir}`,
+  ];
+}

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

@@ -70,12 +70,22 @@ export interface WebSessionState {
 }
 
 export const IDLE_DESTROY_MS = 10 * 60 * 1000;
+// Longest a subagent may go without a frame before the wrapper stops counting
+// it as live work. A terminal frame lost to a protocol hiccup would otherwise
+// pin the session's omp process (and its whole process group) open forever; the
+// price of the window is at most one idle omp process.
+export const SUBAGENT_STALE_MS = 30 * 60 * 1000;
 export const READY_TIMEOUT_MS = 120_000;
 export const GET_STATE_TIMEOUT_MS = 5_000;
 export const PROMPT_ACK_TIMEOUT_MS = 30_000;
 export const NON_TERMINAL_CONTINUATION_GRACE_MS = 2_000;
 export const AWAITING_AGENT_START_TIMEOUT_MS = 10_000;
 export const RESTARTING_MESSAGE = 'This session is restarting — retry in a moment.';
+// A command timeout is not proof an omp child is wedged: omp runs RPC handlers
+// one at a time, so a slow `get_state`/`prompt` ack can simply be queued behind
+// the running turn. That session keeps its process — only a session that is
+// idle AND unresponsive is reset.
+export const SESSION_BUSY_MESSAGE = 'The OMP session is busy with the running turn; retry once it settles.';
 
 export class WebRpcError extends Error {
   readonly code: string;

package/src/server/lib/omp/rpc/lifecycle.test.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The wrapper's lifecycle rules: which conditions may reclaim a session's omp
+ * process. A reset kills the whole process group, so a wrong answer here
+ * destroys a live turn and every subagent under it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'bun:test';
+
+import { AgentSessionWrapper, WebRpcError } from '@/server/lib/omp/rpc/manager';
+import { RpcCommandTimeoutError, type RpcProcess } from '@/server/lib/omp/rpc/process';
+
+/** Commands whose ack is fabricated as timed out; everything else resolves, so
+ *  only the timeout policy is under test. */
+const TIMED_OUT_COMMANDS: Record<string, true> = { get_state: true, prompt: true };
+
+interface StubProcess {
+  proc: RpcProcess;
+  emit(frame: Record<string, unknown>): void;
+  disposeCount(): number;
+}
+
+function makeProc(): StubProcess {
+  let listener: ((frame: unknown) => void) | null = null;
+  let disposals = 0;
+  const proc = {
+    isAlive: true,
+    pid: 4242,
+    onFrame(next: (frame: unknown) => void) {
+      listener = next;
+      return () => {
+        listener = null;
+      };
+    },
+    sendCommand(command: { type: string }) {
+      if (TIMED_OUT_COMMANDS[command.type] === true) {
+        return Promise.reject(new RpcCommandTimeoutError(command.type, 1));
+      }
+      return Promise.resolve(undefined);
+    },
+    sendFrame() {},
+    async dispose() {
+      disposals += 1;
+    },
+  };
+  return {
+    proc: proc as unknown as RpcProcess,
+    emit: (frame) => listener?.(frame),
+    disposeCount: () => disposals,
+  };
+}
+
+async function rejectionOf(operation: Promise<unknown>): Promise<WebRpcError> {
+  const error = await operation.then(() => null, (caught: unknown) => caught);
+  expect(error).toBeInstanceOf(WebRpcError);
+  return error as WebRpcError;
+}
+
+describe('AgentSessionWrapper lifecycle', () => {
+  // Every command arms the wrapper's idle timer; keep the clock fake so a test
+  // never schedules a real ten-minute window.
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test('resets a session that ignores commands while idle', async () => {
+    const stub = makeProc();
+    const wrapper = new AgentSessionWrapper(stub.proc, '/tmp');
+
+    const error = await rejectionOf(wrapper.send({ type: 'get_state' }));
+
+    expect(error.code).toBe('session_unresponsive');
+    expect(stub.disposeCount()).toBe(1);
+  });
+
+  test('keeps the process when a get_state times out mid-turn', async () => {
+    const stub = makeProc();
+    const wrapper = new AgentSessionWrapper(stub.proc, '/tmp');
+    wrapper.start();
+    stub.emit({ type: 'agent_start' });
+
+    const error = await rejectionOf(wrapper.send({ type: 'get_state' }));
+
+    expect(error.code).toBe('session_busy');
+    expect(stub.disposeCount()).toBe(0);
+    expect(wrapper.isRunning()).toBe(true);
+  });
+
+  test('keeps the process when a prompt ack times out mid-turn', async () => {
+    const stub = makeProc();
+    const wrapper = new AgentSessionWrapper(stub.proc, '/tmp');
+    wrapper.start();
+    stub.emit({ type: 'agent_start' });
+
+    const error = await rejectionOf(wrapper.send({ type: 'prompt', message: 'hi' }));
+
+    expect(error.code).toBe('session_busy');
+    expect(stub.disposeCount()).toBe(0);
+  });
+
+  test('idle reclaim waits for subagents that outlive the turn', () => {
+    const stub = makeProc();
+    const wrapper = new AgentSessionWrapper(stub.proc, '/tmp', null, { idleDestroyMs: 20 });
+    wrapper.start();
+
+    stub.emit({ type: 'agent_start' });
+    stub.emit({ type: 'agent_end', isTerminal: true });
+    stub.emit({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'started', index: 0 } });
+    expect(wrapper.isRunning()).toBe(false);
+    expect(wrapper.isBusy()).toBe(true);
+
+    vi.advanceTimersByTime(200);
+    expect(stub.disposeCount()).toBe(0);
+
+    stub.emit({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'completed', index: 0 } });
+    expect(wrapper.isBusy()).toBe(false);
+
+    vi.advanceTimersByTime(200);
+    expect(stub.disposeCount()).toBe(1);
+  });
+
+  test('force_reset reclaims a process whose turn will not stop', async () => {
+    const stub = makeProc();
+    const wrapper = new AgentSessionWrapper(stub.proc, '/tmp');
+    stub.emit({ type: 'agent_start' });
+
+    await wrapper.send({ type: 'force_reset' });
+
+    expect(stub.disposeCount()).toBe(1);
+  });
+});

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

@@ -20,8 +20,9 @@ import { PendingUiDialogs } from '@/server/lib/omp/rpc/pending-ui-dialogs';
 import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 import { notifyRunningChange } from '@/server/lib/omp/rpc/session-registry';
 import { dispatchSessionCommand } from '@/server/lib/omp/rpc/session-commands';
+import { SubagentLiveness } from '@/server/lib/omp/rpc/subagent-liveness';
 import { markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
-import { GET_STATE_TIMEOUT_MS, IDLE_DESTROY_MS, NON_TERMINAL_CONTINUATION_GRACE_MS, READY_TIMEOUT_MS, type AgentEvent, type EventListener, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
+import { GET_STATE_TIMEOUT_MS, IDLE_DESTROY_MS, NON_TERMINAL_CONTINUATION_GRACE_MS, READY_TIMEOUT_MS, SUBAGENT_STALE_MS, type AgentEvent, type EventListener, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
 
 export type {
   AgentEvent,
@@ -31,6 +32,13 @@ export type {
 } from '@/server/lib/omp/rpc/constants';
 export { WebRpcError, resolveSpawnCwd } from '@/server/lib/omp/rpc/constants';
 
+/** Overrides for the wrapper's own timers. Production always uses the
+ *  constant; tests shrink the window so the lifecycle rules stay fast. */
+export interface AgentSessionWrapperOptions {
+  /** Idle window before an unused process is reclaimed. */
+  idleDestroyMs?: number;
+}
+
 export class AgentSessionWrapper {
   private listeners: EventListener[] = [];
   promptRunning = false;
@@ -55,14 +63,20 @@ export class AgentSessionWrapper {
   // `extension_ui_request`, so a client that reloads mid-dialog can only learn
   // the id it must answer from here.
   private readonly pendingUiDialogs = new PendingUiDialogs();
+  // Live subagents, folded from the frames omp streams after the subscription
+  // set in initialize(). No other flag on this wrapper can see them, and an
+  // idle reclaim or a spawn-mode reconcile must never kill a running subagent.
+  private readonly subagents = new SubagentLiveness();
+  readonly idleDestroyMs: number;
   proc: RpcProcess;
   readonly cwd: string;
   private readonly recordedCwd: string | null;
 
-  constructor(proc: RpcProcess, cwd: string, recordedCwd?: string | null) {
+  constructor(proc: RpcProcess, cwd: string, recordedCwd?: string | null, options: AgentSessionWrapperOptions = {}) {
     this.proc = proc;
     this.cwd = cwd;
     this.recordedCwd = recordedCwd ?? null;
+    this.idleDestroyMs = options.idleDestroyMs ?? IDLE_DESTROY_MS;
   }
 
   get sessionId(): string {
@@ -87,6 +101,13 @@ export class AgentSessionWrapper {
     return this.isAlive() && (this.promptRunning || this.streaming || this.compacting || this.bashRunning);
   }
 
+  /** Anything in flight that a process reset would destroy: the current turn,
+   *  a compaction, a shell command, or live subagents — which outlive the turn
+   *  that spawned them, so no other flag here can see them. */
+  isBusy(): boolean {
+    return this.isRunning() || this.subagents.liveCount(Date.now(), SUBAGENT_STALE_MS) > 0;
+  }
+
   start(): void {
     this.unsubscribeFrames = this.proc.onFrame((frame) => this.handleFrame(frame));
     this.resetIdleTimer();
@@ -188,6 +209,13 @@ export class AgentSessionWrapper {
       case 'extension_ui_request':
         this.pendingUiDialogs.track(event);
         break;
+      // Subagent frames carry no turn state, but they are the only proof that
+      // work is still running once the parent turn has ended.
+      case 'subagent_lifecycle':
+      case 'subagent_progress':
+      case 'subagent_event':
+        this.subagents.observe(event, Date.now());
+        break;
       case 'response': {
         if (event.success === false && event.command === 'prompt') {
           this.promptRunning = false;
@@ -226,12 +254,12 @@ export class AgentSessionWrapper {
     this.lastIdleReset = now;
     if (this.idleTimer) clearTimeout(this.idleTimer);
     this.idleTimer = setTimeout(() => {
-      if (this.isRunning()) {
+      if (this.isBusy()) {
         this.resetIdleTimer(true);
         return;
       }
       this.destroy();
-    }, IDLE_DESTROY_MS);
+    }, this.idleDestroyMs);
   }
 
   onEvent(listener: EventListener): () => void {

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

@@ -46,7 +46,7 @@ export class RpcProcess {
     const resolveBin = options.dependencies?.resolveOmpBin ?? resolveOmpBin;
     const bin = resolveBin();
     if (!bin) {
-      throw new Error('omp binary not found. Install oh-my-pi or set OMP_WEB_OMP_BIN.');
+      throw new Error('omp binary not found. Install oh-my-pi or set OMPCHAMBER_OMP_BIN.');
     }
     this.cwd = options.cwd;
     if (options.onFrame) this.frameListeners.add(options.onFrame);

package/src/server/lib/omp/rpc/session-commands.ts

@@ -10,7 +10,7 @@
  */
 
 import { RpcCommandTimeoutError, type RpcProcess } from '@/server/lib/omp/rpc/process';
-import { AWAITING_AGENT_START_TIMEOUT_MS, GET_STATE_TIMEOUT_MS, IMAGE_BEARING_COMMANDS, PASSTHROUGH_COMMANDS, PROMPT_ACK_TIMEOUT_MS, RESTARTING_MESSAGE, WebRpcError, toImageContents, type AgentEvent, type RpcSessionState, validateAgentImages } from '@/server/lib/omp/rpc/constants';
+import { AWAITING_AGENT_START_TIMEOUT_MS, GET_STATE_TIMEOUT_MS, IMAGE_BEARING_COMMANDS, PASSTHROUGH_COMMANDS, PROMPT_ACK_TIMEOUT_MS, RESTARTING_MESSAGE, SESSION_BUSY_MESSAGE, WebRpcError, toImageContents, type AgentEvent, type RpcSessionState, validateAgentImages } from '@/server/lib/omp/rpc/constants';
 import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 import { notifyRunningChange } from '@/server/lib/omp/rpc/session-registry';
 import { markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
@@ -21,6 +21,10 @@ export interface SessionCommandHost extends WebStateHost {
   restarting: boolean;
   proc: RpcProcess;
   isAlive(): boolean;
+  /** Anything a reset would destroy: the running turn, a compaction, a shell
+   *  command, or live subagents. A timed-out command against a busy session is
+   *  queued behind that work, not evidence the child is wedged. */
+  isBusy(): boolean;
   /** Real omp session id (empty before the first get_state). */
   sessionId: string;
   emit(event: AgentEvent): void;
@@ -31,6 +35,20 @@ export interface SessionCommandHost extends WebStateHost {
   destroyAndWait(): Promise<void>;
 }
 
+/** Decide a command timeout's consequence. omp runs RPC handlers one at a
+ *  time, so a late `get_state`/`prompt` ack is usually queued behind the
+ *  running turn (or behind a subagent's spawn): resetting that child would
+ *  throw away a live turn and every subagent it owns. Only a session that is
+ *  demonstrably idle AND unresponsive is reclaimed.
+ *
+ *  Never throws `session_unresponsive` for a busy session, and never suggests a
+ *  retry of a command whose acceptance is unknown. */
+async function settleCommandTimeout(host: SessionCommandHost): Promise<never> {
+  if (host.isBusy()) throw new WebRpcError(SESSION_BUSY_MESSAGE, 'session_busy');
+  await host.destroyAndWait();
+  throw new WebRpcError('The OMP session stopped responding and was reset.', 'session_unresponsive');
+}
+
 export async function dispatchSessionCommand(host: SessionCommandHost, command: Record<string, unknown>): Promise<unknown> {
   if (host.restarting) throw new WebRpcError(RESTARTING_MESSAGE, 'session_restarting');
   if (!host.isAlive()) throw new Error('Session is no longer running');
@@ -78,10 +96,10 @@ export async function dispatchSessionCommand(host: SessionCommandHost, command:
         host.awaitingAgentStart = false;
         host.awaitingAgentStartDeadline = 0;
         notifyRunningChange();
-        if (error instanceof RpcCommandTimeoutError) {
-          await host.destroyAndWait();
-          throw new WebRpcError('The OMP session stopped responding and was reset.', 'session_unresponsive');
-        }
+        // The ack may simply be queued behind a running turn: omp accepts the
+        // prompt before the turn it starts. No reset, and the client must not
+        // resend — a duplicate prompt would run twice.
+        if (error instanceof RpcCommandTimeoutError) await settleCommandTimeout(host);
         throw error;
       } finally {
         if (!streamingBehavior) {
@@ -102,15 +120,20 @@ export async function dispatchSessionCommand(host: SessionCommandHost, command:
       });
       return null;
 
+    // Escape hatch behind the Stop button: `abort` resolves only once the turn
+    // actually stops, so a session wedged on a subagent never answers it. The
+    // caller (shared/lib/chat/omp/abort.ts) escalates to this after a grace
+    // period and accepts losing the in-flight work.
+    case 'force_reset':
+      await host.destroyAndWait();
+      return null;
+
     case 'get_state': {
       try {
         const state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
         return buildWebState(host, state);
       } catch (error) {
-        if (error instanceof RpcCommandTimeoutError) {
-          await host.destroyAndWait();
-          throw new WebRpcError('The OMP session stopped responding and was reset.', 'session_unresponsive');
-        }
+        if (error instanceof RpcCommandTimeoutError) await settleCommandTimeout(host);
         throw error;
       }
     }

package/src/server/lib/omp/rpc/session-registry.ts

@@ -131,8 +131,9 @@ export function getSpawnApprovalMode(session: AgentSessionWrapper): ApprovalMode
  *  Returns true when the session was destroyed (caller MUST respawn). */
 export async function reconcileSpawnApprovalMode(session: AgentSessionWrapper, desired: ApprovalMode): Promise<boolean> {
   if (getSpawnApprovalMode(session) === desired) return false;
-  // Never kill an in-flight run — the caller would lose the active turn.
-  if (session.isRunning()) return false;
+  // Never kill in-flight work — the caller would lose the active turn, and a
+  // live subagent outlives that turn.
+  if (session.isBusy()) return false;
   // A brand-new session has no JSONL on disk yet; destroying it would 404 the
   // next request that tries to resolve its file.
   if (!session.sessionFile) return false;

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

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { SubagentLiveness } from '@/server/lib/omp/rpc/subagent-liveness';
+
+const NOW = 1_000_000;
+const STALE_MS = 60_000;
+
+describe('SubagentLiveness', () => {
+  test('counts a started subagent until its terminal lifecycle arrives', () => {
+    const live = new SubagentLiveness();
+    live.observe({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'started', index: 0 } }, NOW);
+    expect(live.liveCount(NOW, STALE_MS)).toBe(1);
+
+    live.observe({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'completed', index: 0 } }, NOW + 1);
+    expect(live.liveCount(NOW + 1, STALE_MS)).toBe(0);
+  });
+
+  test('an id-less progress frame lands on the lifecycle entry it names', () => {
+    const live = new SubagentLiveness();
+    live.observe({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'started', index: 3 } }, NOW);
+    live.observe({ type: 'subagent_progress', payload: { index: 3, status: 'running' } }, NOW + 1);
+    expect(live.liveCount(NOW + 1, STALE_MS)).toBe(1);
+
+    // A terminal progress frame for the same index must clear that one entry —
+    // not leave a second key behind holding the session open.
+    live.observe({ type: 'subagent_progress', payload: { index: 3, status: 'completed' } }, NOW + 2);
+    expect(live.liveCount(NOW + 2, STALE_MS)).toBe(0);
+  });
+
+  test('reads a progress snapshot nested under `progress`', () => {
+    const live = new SubagentLiveness();
+    live.observe({ type: 'subagent_progress', payload: { progress: { id: 's9', status: 'running' } } }, NOW);
+    expect(live.liveCount(NOW, STALE_MS)).toBe(1);
+  });
+
+  test('malformed frames never fabricate liveness', () => {
+    const live = new SubagentLiveness();
+    live.observe({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'paused' } }, NOW);
+    live.observe({ type: 'subagent_lifecycle', payload: { status: 'started' } }, NOW);
+    live.observe({ type: 'subagent_progress', payload: 'nonsense' }, NOW);
+    live.observe({ type: 'subagent_event', payload: { event: { type: 'message_end' } } }, NOW);
+    expect(live.liveCount(NOW, STALE_MS)).toBe(0);
+  });
+
+  test('a subagent silent past the stale window stops counting, so one lost terminal frame cannot pin a session', () => {
+    const live = new SubagentLiveness();
+    live.observe({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'started', index: 0 } }, NOW);
+    expect(live.liveCount(NOW + STALE_MS + 1, STALE_MS)).toBe(0);
+  });
+
+  test('an unattributed event refreshes tracked work without inventing an entry', () => {
+    const live = new SubagentLiveness();
+    live.observe({ type: 'subagent_lifecycle', payload: { id: 's1', status: 'started', index: 0 } }, NOW);
+    live.observe({ type: 'subagent_event', payload: { event: { type: 'tool_execution_start', toolName: 'bash' } } }, NOW + STALE_MS - 1);
+    expect(live.liveCount(NOW + STALE_MS + 1, STALE_MS)).toBe(1);
+  });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Liveness of a session's subagents, folded from the frames the wrapper already
+ * receives (`set_subagent_subscription` in AgentSessionWrapper.initialize).
+ *
+ * Every other "this session is working" flag on the wrapper (promptRunning /
+ * streaming / compacting / bashRunning) is blind to subagents: a parent turn
+ * can end — or a detached subagent outlive it — while subagents keep working,
+ * and a frame-silent subagent otherwise looks exactly like an idle session to
+ * the idle reaper. Used only for lifecycle decisions (idle reclaim, spawn-mode
+ * reconcile), never for the UI's running set.
+ *
+ * Identity mirrors the UI fold (`SubagentList`): frames carry an id, a
+ * lifecycle may also carry `index`, and progress frames may be id-less and are
+ * then matched by index — hence the index→key alias, so one subagent is never
+ * tracked under two keys (a leftover key would pin the session alive until it
+ * 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';
+
+/** 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
+   *  created instead of opening a second one. */
+  private readonly keyByIndex = new Map<number, string>();
+
+  /** Fold one `subagent_lifecycle|subagent_progress|subagent_event` frame. */
+  observe(frame: { type: string; payload?: unknown }, now: number): void {
+    if (frame.type === 'subagent_lifecycle') {
+      const entry = parseSubagentLifecycle(frame.payload);
+      if (!entry) return;
+      if (TERMINAL_STATUS[entry.status] === true) this.forget(entry.id);
+      else this.mark(entry.id, entry.index >= 0 ? entry.index : undefined, now);
+      return;
+    }
+
+    if (frame.type === 'subagent_progress') {
+      const progress = readProgress(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);
+      if (key === undefined) return;
+      if (progress.status !== undefined && TERMINAL_STATUS[progress.status] === true) this.forget(key);
+      else this.mark(key, index, now);
+      return;
+    }
+
+    if (frame.type === 'subagent_event') {
+      // An event proves *some* subagent is working but carries no identity of
+      // its own: refresh what is already tracked, and never invent an entry —
+      // an invented one could never be cleared by a terminal frame.
+      for (const key of this.lastSeen.keys()) this.lastSeen.set(key, now);
+    }
+  }
+
+  /** Live subagents as of `now`. Entries silent past `staleMs` are dropped
+   *  first: a terminal frame lost to a protocol hiccup must not pin a session
+   *  alive forever (the price of the window is at most one idle omp process). */
+  liveCount(now: number, staleMs: number): number {
+    for (const [key, lastSeen] of this.lastSeen) {
+      if (now - lastSeen > staleMs) this.forget(key);
+    }
+    return this.lastSeen.size;
+  }
+
+  private mark(key: string, index: number | undefined, now: number): void {
+    this.lastSeen.set(key, now);
+    if (index === undefined) return;
+    // A lifecycle naming the same index supersedes the synthetic key an earlier
+    // id-less progress frame created for it.
+    if (key !== `idx:${index}`) this.lastSeen.delete(`idx:${index}`);
+    this.keyByIndex.set(index, key);
+  }
+
+  private forget(key: string): void {
+    this.lastSeen.delete(key);
+    for (const [index, alias] of this.keyByIndex) {
+      if (alias === key) this.keyByIndex.delete(index);
+    }
+  }
+}