ompchamber 0.5.0 → 0.7.0

package/src/client/hooks/chat/omp/prompt-send.ts

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Prompt delivery for the live omp bridge: warm the session up, attach the
+ * event stream, POST the prompt, then signal the sidebars the moment it is
+ * dispatched.
+ *
+ * The signal is the point: the server writes the live `stream` row when it
+ * dispatches the prompt, so waiting for `agent_start` (spawn + ack round trip)
+ * would leave the sidebar spinner dark for seconds after the user hit send.
+ * Extracted from useOmpAgent so that hook stays under the repo's per-file size
+ * ceiling.
+ */
+
+import { useCallback } from 'preact/hooks';
+import type { Dispatch, SetStateAction } from 'preact/compat';
+import type { OmpAgentState } from '@/shared/types';
+import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
+
+export interface OmpPromptSenderDeps {
+  /** Live session id the prompt targets; the caller mirrors its prop into it. */
+  sessionIdRef: { current: string | null };
+  /** Attach the event stream to a spawned session. */
+  connect: (sessionId: string) => void;
+  setState: Dispatch<SetStateAction<OmpAgentState>>;
+}
+
+export interface OmpPromptSender {
+  sendPrompt: (message: string, images?: { data: string; mimeType: string }[], options?: { accessMode?: ApprovalMode }) => Promise<boolean>;
+  sendNewPrompt: (
+    message: string,
+    cwd: string,
+    images?: { data: string; mimeType: string }[],
+    composerOptions?: { model?: { provider: string; modelId: string } | null; thinkingLevel?: string | null; accessMode?: ApprovalMode },
+  ) => Promise<{ sessionId: string; model: { provider: string; modelId: string } | null } | null>;
+}
+
+export function useOmpPromptSender(deps: OmpPromptSenderDeps): OmpPromptSender {
+  const { sessionIdRef, connect, setState } = deps;
+
+  /** Send a prompt to the omp session via the RPC bridge. */
+  const sendPrompt = useCallback(async (
+    message: string,
+    images?: { data: string; mimeType: string }[],
+    options?: { accessMode?: ApprovalMode },
+  ) => {
+    const sid = sessionIdRef.current;
+    if (!sid) return false;
+    setState((prev) => ({ ...prev, isGenerating: true, error: null }));
+    try {
+      // Mirror omp-web handleSend: warm the session process up with get_state
+      // (spawns it on first use), then attach the event stream before sending
+      // the prompt so no agent events are missed.
+      const warmup = await fetch(`/api/agent/${encodeURIComponent(sid)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        // The mode rides the warmup too: this is the request that lazily spawns
+        // an idle session, and omp only accepts --approval-mode at spawn time.
+        body: JSON.stringify({
+          type: 'get_state',
+          ...(options?.accessMode ? { accessMode: options.accessMode } : {}),
+        }),
+      });
+      if (warmup.ok) connect(sid);
+
+      const res = await fetch(`/api/agent/${encodeURIComponent(sid)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          type: 'prompt',
+          message,
+          ...(images?.length ? { images } : {}),
+          ...(options?.accessMode ? { accessMode: options.accessMode } : {}),
+        }),
+      });
+      const body = (await res.json().catch(() => ({}))) as { success?: boolean; error?: string };
+      if (!res.ok || body.error) {
+        // `session_busy`: the ack timed out behind a still-running turn, so the
+        // prompt may already be accepted — never resend it automatically.
+        setState((prev) => ({ ...prev, isGenerating: false, error: body.error ?? `HTTP ${res.status}` }));
+        return false;
+      }
+      // Tell the sidebars to re-read the session list now — the server wrote
+      // this session's live `stream` row at dispatch. Revalidation is
+      // leading-edge throttled, so this lands immediately.
+      window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: sid } }));
+      return true;
+    } catch (e) {
+      setState((prev) => ({ ...prev, isGenerating: false, error: e instanceof Error ? e.message : String(e) }));
+      return false;
+    }
+  }, [connect, sessionIdRef, setState]);
+
+  /** Spawn a brand-new omp session and send the first prompt: ensure_session
+   *  first (returns omp's real session id), attach the event stream, then send
+   *  the prompt through the existing session route so no agent events are
+   *  missed. Model/thinking picks ride the ensure_session body so omp applies
+   *  them BEFORE the first prompt (and their JSONL change entries are written
+   *  up front, not after the run starts). Returns the new session id on
+   *  success, or null on failure — the caller adopts the id as the active
+   *  session. */
+  const sendNewPrompt = useCallback(async (
+    message: string,
+    cwd: string,
+    images?: { data: string; mimeType: string }[],
+    composerOptions?: { model?: { provider: string; modelId: string } | null; thinkingLevel?: string | null; accessMode?: ApprovalMode },
+  ): Promise<{ sessionId: string; model: { provider: string; modelId: string } | null } | null> => {
+    setState((prev) => ({ ...prev, isGenerating: true, error: null }));
+    try {
+      const created = await fetch('/api/agent/new', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          type: 'ensure_session',
+          cwd,
+          ...(composerOptions?.model ? composerOptions.model : {}),
+          ...(composerOptions?.thinkingLevel ? { thinkingLevel: composerOptions.thinkingLevel } : {}),
+          ...(composerOptions?.accessMode ? { accessMode: composerOptions.accessMode } : {}),
+        }),
+      });
+      const createdBody = (await created.json().catch(() => ({}))) as {
+        success?: boolean;
+        sessionId?: string;
+        model?: { provider: string; modelId: string } | null;
+        error?: string;
+      };
+      if (!created.ok || !createdBody.sessionId) {
+        setState((prev) => ({ ...prev, isGenerating: false, error: createdBody.error ?? `HTTP ${created.status}` }));
+        return null;
+      }
+      const sid = createdBody.sessionId;
+      connect(sid);
+      const res = await fetch(`/api/agent/${encodeURIComponent(sid)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          type: 'prompt',
+          message,
+          ...(images?.length ? { images } : {}),
+        }),
+      });
+      const body = (await res.json().catch(() => ({}))) as { success?: boolean; error?: string };
+      if (!res.ok || body.error) {
+        setState((prev) => ({ ...prev, isGenerating: false, error: body.error ?? `HTTP ${res.status}` }));
+        return null;
+      }
+      // Same dispatch-time signal as sendPrompt: the new session's live badge
+      // must not wait for agent_start + the first JSONL write.
+      window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: sid } }));
+      return { sessionId: sid, model: createdBody.model ?? null };
+    } catch (e) {
+      setState((prev) => ({ ...prev, isGenerating: false, error: e instanceof Error ? e.message : String(e) }));
+      return null;
+    }
+  }, [connect, setState]);
+
+  return { sendPrompt, sendNewPrompt };
+}

package/src/client/hooks/chat/timeline/send.ts

@@ -304,8 +304,9 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
             next.set('sessionId', spawned.sessionId);
             return next;
           }, { replace: true });
-          // The agent_start event refreshes the session metadata/sidebar once
-          // the JSONL has the user turn; no immediate refresh is needed here.
+          // The sidebar already re-read at prompt dispatch (sendNewPrompt
+          // signals it), so the new session shows its live badge without
+          // waiting for the JSONL to carry the user turn.
           return;
         }
       }

package/src/client/hooks/editor/use-file-editor.test.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `useFileEditor` revalidation contract.
+ *
+ * A landed write bumps the workspace refreshKey, which calls `reset()`. Reset
+ * used to drop every cached buffer, so the very next render painted an empty
+ * editor — and because the read effect only re-runs on a key/identity change,
+ * the file never came back without a full page reload. The same window let a
+ * read response that was already in flight land on top of keystrokes typed
+ * after it was requested.
+ *
+ * These run against a real DOM (happy-dom) because the hook is a Preact hook
+ * driving fetches and effects: the modules below are imported inside
+ * `beforeAll`, after those globals exist, because Preact and the highlighter
+ * bind their environment at evaluation time.
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { UseFileEditorResult, useFileEditor as UseFileEditorHook } from '@/client/hooks/editor/use-file-editor';
+
+const DISK = 'const a = 1;\nconst b = 2;\n';
+/** Stable identity: the read effect re-runs when its target object changes. */
+const TARGET = { id: 1, name: 'a.js', path: 'a.js' };
+
+let useFileEditor: typeof UseFileEditorHook;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+/** Latest render's result — re-read after every settle, never held across one. */
+let mounted: UseFileEditorResult | null = null;
+let container: HTMLElement;
+
+interface FsState {
+  reads: number;
+  writes: number;
+  body: string;
+}
+
+/** Serves `state.body` for reads and counts writes, without touching the network. */
+function stubFetch(state: FsState) {
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    if (String(input).startsWith('/api/fs/read')) {
+      state.reads += 1;
+      return { ok: true, json: async () => ({ content: state.body }) };
+    }
+    state.writes += 1;
+    state.body = String((init?.body as FormData).get('content'));
+    return { ok: true, json: async () => ({ success: true }) };
+  }) as unknown as typeof fetch;
+}
+
+/**
+ * Lets the stub's promise chain run and the render it queues land. The chain
+ * needs no timers (nothing I/O bound), and Preact's `act` only flushes queued
+ * renders on its boundary, so both get a pass.
+ */
+async function settleEditor() {
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+  await act(async () => {
+    for (let i = 0; i < 20; i++) await Promise.resolve();
+  });
+}
+
+async function mountEditor() {
+  const Probe = () => {
+    mounted = useFileEditor(TARGET);
+    return null;
+  };
+  await act(async () => {
+    render(h(Probe, {}), container);
+  });
+  await settleEditor();
+}
+
+/** The DOM surface this file installs for the hook and Preact to render into. */
+function domGlobals(win: Window): Record<string, unknown> {
+  return {
+    window: win,
+    document: win.document,
+    navigator: win.navigator,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+  };
+}
+
+const installed: Record<string, unknown> = {};
+const displaced: Record<string, unknown> = {};
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  for (const [key, value] of Object.entries(domGlobals(win))) {
+    displaced[key] = (globalThis as Record<string, unknown>)[key];
+    installed[key] = value;
+    (globalThis as Record<string, unknown>)[key] = value;
+  }
+  ({ useFileEditor } = await import('@/client/hooks/editor/use-file-editor'));
+  ({ h, render } = await import('preact'));
+  ({ act } = await import('preact/test-utils'));
+});
+
+// Every test file shares one process, so the globals go back the way they were:
+// code that branches on `typeof window` (the agent-event fold, for one) would
+// otherwise take its browser path for the rest of the run.
+afterAll(() => {
+  for (const key of Object.keys(installed)) {
+    if (displaced[key] === undefined) delete (globalThis as Record<string, unknown>)[key];
+    else (globalThis as Record<string, unknown>)[key] = displaced[key];
+  }
+});
+
+beforeEach(() => {
+  mounted = null;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+describe('useFileEditor revalidation', () => {
+  test('reset re-reads from disk without blanking the open file', async () => {
+    const state: FsState = { reads: 0, writes: 0, body: DISK };
+    stubFetch(state);
+    await mountEditor();
+    expect(mounted?.content).toBe(DISK);
+
+    // The refresh a landed write triggers, with newer bytes now on disk.
+    state.body = `${DISK}const c = 3;\n`;
+    await act(async () => {
+      mounted?.reset();
+    });
+    await settleEditor();
+
+    expect(state.reads).toBe(2);
+    expect(mounted?.content).toBe(state.body);
+  });
+
+  test('a read that lands mid-typing does not replace the buffer', async () => {
+    const state: FsState = { reads: 0, writes: 0, body: DISK };
+    stubFetch(state);
+    await mountEditor();
+
+    await act(async () => {
+      mounted?.onChange('edited by hand');
+      mounted?.reset();
+    });
+    await settleEditor();
+
+    expect(state.reads).toBe(2);
+    expect(mounted?.content).toBe('edited by hand');
+  });
+});

package/src/client/hooks/editor/use-file-editor.ts

@@ -40,9 +40,11 @@ export interface UseFileEditorResult {
   saveNow: () => void;
   copy: () => void;
   download: () => void;
-  /** Forget cached content for the active file and read it again. */
-  reload: () => void;
-  /** Forget all cached content (e.g. a workspace refresh). */
+  /**
+   * Re-read every cached file from disk (e.g. a workspace refresh). Content
+   * already on screen stays until the fresh bytes land, and a file with
+   * unsaved edits is left alone.
+   */
   reset: () => void;
   /** Drop cached content for files no longer open. */
   retain: (ids: Array<number | string>) => void;
@@ -77,6 +79,8 @@ export function useFileEditor(
   const [loadError, setLoadError] = useState<string | null>(null);
   const [saveStatus, setSaveStatus] = useState<FileEditorSaveStatus>('idle');
   const [copied, setCopied] = useState(false);
+  /** Bumped by `reset()` to re-run the read effect for the active file. */
+  const [revision, setRevision] = useState(0);
 
   const key = target ? targetKey(target) : '';
   const content = target ? (contents[key] ?? target.content ?? '') : '';
@@ -87,6 +91,14 @@ export function useFileEditor(
   const loadedRef = useRef<Set<string>>(new Set());
   const pendingRef = useRef<{ timer: number; file: FileEditorTarget; content: string } | null>(null);
 
+  // Live mirrors of the content maps: a read response resolves long after it
+  // was requested, and it has to know whether the buffer it read is still the
+  // one on screen.
+  const contentsRef = useRef(contents);
+  contentsRef.current = contents;
+  const baselinesRef = useRef(baselines);
+  baselinesRef.current = baselines;
+
   const remember = useCallback((fileKey: string, text: string) => {
     setContents((prev) => ({ ...prev, [fileKey]: text }));
     setBaselines((prev) => ({ ...prev, [fileKey]: text }));
@@ -145,8 +157,11 @@ export function useFileEditor(
       return;
     }
 
+    // Only a key with nothing on screen yet shows the loading state: a
+    // re-read (refreshKey / reset) must not flash a spinner over live content.
+    const firstLoad = contentsRef.current[fileKey] === undefined;
     let cancelled = false;
-    setIsLoading(true);
+    if (firstLoad) setIsLoading(true);
     setLoadError(null);
     const params = new URLSearchParams({ path: target.path });
     if (target.root) params.set('root', target.root);
@@ -164,10 +179,20 @@ export function useFileEditor(
       })
       .then((text) => {
         if (cancelled) return;
+        // These bytes were read before the response arrived, so anything typed
+        // since is newer. Applying them would replace those keystrokes (and,
+        // once a refresh is triggered by a save, wipe the editor back to an
+        // empty buffer) — instead let the queued write own the key.
+        const typed = contentsRef.current[fileKey];
+        if (typed !== undefined && typed !== baselinesRef.current[fileKey]) return;
+        const queued = pendingRef.current;
+        if (queued && targetKey(queued.file) === fileKey) return;
         remember(fileKey, text ?? (fallback ? fallback(target.name) : ''));
       })
       .catch((err: unknown) => {
         if (cancelled) return;
+        // A failed re-read keeps what is on screen; only a first load reports.
+        if (!firstLoad) return;
         if (reportLoadError) {
           remember(fileKey, '');
           setLoadError(err instanceof Error ? err.message : 'Failed to read file');
@@ -182,7 +207,7 @@ export function useFileEditor(
     return () => {
       cancelled = true;
     };
-  }, [key, target, fallback, reportLoadError, remember]);
+  }, [key, target, fallback, reportLoadError, remember, revision]);
 
   useEffect(() => {
     if (saveStatus !== 'saved') return;
@@ -239,21 +264,13 @@ export function useFileEditor(
     URL.revokeObjectURL(url);
   }, [target, contents, downloadMimeType]);
 
-  const reload = useCallback(() => {
-    if (!key) return;
-    loadedRef.current.delete(key);
-    setContents((prev) => {
-      if (prev[key] === undefined) return prev;
-      const next = { ...prev };
-      delete next[key];
-      return next;
-    });
-  }, [key]);
-
   const reset = useCallback(() => {
+    // Invalidate every key, then let the read effect refetch the active one.
+    // Content is deliberately NOT cleared: it stays on screen until the fresh
+    // bytes land, so a refresh can never blank the editor (or drop the file
+    // that is open) while the request is in flight.
     loadedRef.current.clear();
-    setContents({});
-    setBaselines({});
+    setRevision((prev) => prev + 1);
   }, []);
 
   const retain = useCallback((ids: Array<number | string>) => {
@@ -295,7 +312,6 @@ export function useFileEditor(
     saveNow,
     copy,
     download,
-    reload,
     reset,
     retain,
   };

package/src/server/index.ts

@@ -1,9 +1,13 @@
 import { Elysia } from 'elysia';
+import pkg from '@/../package.json';
 import { apiRoutes } from '@/server/routes';
 import { ssrRoutes } from '@/server/plugins/ssr';
 import { getDatabasePath } from '@/server/db.server';
 import { fetchOmpRegistrySnapshot } from '@/server/lib/models/provider-registry.server';
 import { ompStartupError, ompStartupLogLines } from '@/server/lib/omp/core/startup';
+import { readInstanceRecord, removeInstanceRecord, writeInstanceRecord } from '@/server/lib/lifecycle/instance';
+import { resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
+import { acquirePortLock, claimPort, PortInUseError } from '@/server/lib/lifecycle/port-guard';
 import { isMockMode } from '@/server/mock.server';
 
 // Refuse to run without a resolvable omp binary — before the listener opens and
@@ -24,10 +28,57 @@ console.log(`[ompchamber] db:             ${await getDatabasePath()}`);
 
 const port = Number(Bun.env.PORT) || 3000;
 const host = Bun.env.HOST || 'localhost';
+const mode = Bun.env.NODE_ENV === 'production' ? 'prod' : 'dev';
+// argv, not env: see launch-mode.ts — an inherited `OMPCHAMBER_LAUNCH_MODE`
+// would label a `bun run dev` started inside an OMPChamber shell as `daemon`.
+const launchMode = resolveLaunchMode();
+
+const lock = await acquirePortLock(port);
+if (!lock) {
+  console.error(`[ompchamber] another OMPChamber instance is starting on port ${port} right now — retry in a moment.`);
+  process.exit(1);
+}
 
 const app = new Elysia().use(apiRoutes).use(ssrRoutes);
 
-await app.listen({ port, hostname: host });
+try {
+  await claimPort({
+    port,
+    host,
+    listen: async () => {
+      // `reusePort: false` is load-bearing: Elysia's Bun adapter hardcodes
+      // `reusePort: true`, which lets a second server bind a port already in
+      // use and then sit invisible while the first-bound socket takes every
+      // connection.
+      await app.listen({ port, hostname: host, reusePort: false });
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(error instanceof PortInUseError ? `[ompchamber] ${message}` : `[ompchamber] could not listen on ${host}:${port} — ${message}`);
+  process.exit(1);
+} finally {
+  lock.release();
+}
+
+// The record is written by the process that owns the port, so `status`, `stop`
+// and the next `serve` see dev, foreground and daemon servers alike. A hot
+// reload re-runs this entry in the same process: keeping the first `startedAt`
+// for a PID that already recorded this port is what makes `status` report real
+// uptime instead of resetting it on every save.
+const previousRecord = readInstanceRecord(port);
+if (!writeInstanceRecord({
+  pid: process.pid,
+  port,
+  host,
+  mode,
+  launchMode,
+  startedAt: previousRecord?.pid === process.pid ? previousRecord.startedAt : new Date().toISOString(),
+  version: pkg.version,
+})) {
+  console.log('[ompchamber] instance record not written (data directory not writable) — `ompchamber status` will fall back to probing this port');
+}
+process.on('exit', () => removeInstanceRecord(port));
 
 // The listener is already accepting requests here, so the probe only postpones
 // this last banner line, never startup. Printing it after the probe keeps the

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Bun binary to spawn child processes with.
+ *
+ * The server is usually itself Bun, so `process.execPath` is the most
+ * trustworthy answer — it is the exact runtime this install was started with.
+ * A host that is not Bun falls back to a PATH lookup, and finally to the
+ * literal `bun`, which lets the child resolve it from its own environment.
+ */
+export function resolveBunBin(): string {
+  const execPath = process.execPath;
+  if (/(^|[\\/])bun$/.test(execPath)) return execPath;
+  return Bun.which('bun') ?? 'bun';
+}

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

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Process identity for a PID recorded for a port.
+ *
+ * Liveness alone cannot answer "is this PID still an OMPChamber server": after
+ * an ungraceful exit the PID can be recycled to an unrelated process, and a
+ * liveness-only check then reports a live instance nobody is serving — which
+ * either blocks startup on a free port or, worse, lets a stale record name a
+ * stranger. Identity therefore comes from the OS command line, so a recycled
+ * PID reads back as `mismatched`.
+ *
+ * Where `ps` is unavailable (minimal containers) the on-disk `/proc` entry
+ * still answers the identity question on Linux; on Windows, where neither is
+ * cheap, identity is reported as `unknown` and callers fall back to liveness.
+ */
+
+import fs from 'fs';
+
+export type ProcessState = 'dead' | 'matched' | 'mismatched' | 'unknown';
+
+interface ProcessRow {
+  pid: number;
+  /** `ps` state column — `Z…` means defunct (exited, awaiting reaping). */
+  state: string;
+  command: string;
+}
+
+let cachedTable: { at: number; rows: ProcessRow[] } | null = null;
+
+/**
+ * One snapshot of the process table, memoized for a startup decision.
+ *
+ * Every question in a port check happens within milliseconds, so a briefly
+ * cached view is strictly better than spawning `ps` per question.
+ */
+function readProcessTable(maxAgeMs = 250): ProcessRow[] {
+  if (cachedTable && Date.now() - cachedTable.at < maxAgeMs) return cachedTable.rows;
+  const rows: ProcessRow[] = [];
+  try {
+    const snapshot = Bun.spawnSync({
+      cmd: ['ps', '-ax', '-o', 'pid=,stat=,command='],
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    if (snapshot.success) {
+      for (const line of snapshot.stdout.toString().split('\n')) {
+        const match = /^\s*(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+        if (!match) continue;
+        rows.push({ pid: Number(match[1]), state: match[2], command: match[3].trim() });
+      }
+    }
+  } catch {
+    // No `ps` on PATH: identity falls back to /proc, liveness to signal 0.
+  }
+  cachedTable = { at: Date.now(), rows };
+  return rows;
+}
+
+/**
+ * Liveness check. Never throws.
+ *
+ * A defunct (zombie) PID still answers signal 0 — the process has exited and is
+ * only waiting for its parent to reap it — so a zombie counts as not alive: it
+ * holds no port and will never run again. Without this, a stop that worked
+ * looks like a process that "ignored SIGTERM", and stop-waits spin until their
+ * timeout.
+ */
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  const row = readProcessTable().find((entry) => entry.pid === pid);
+  return row ? !row.state.startsWith('Z') : true;
+}
+
+/** Command line for a live PID, or null when this platform cannot report one. */
+function readProcessCommandLine(pid: number): string | null {
+  const row = readProcessTable().find((entry) => entry.pid === pid);
+  if (row) return row.command.length > 0 ? row.command : null;
+  if (process.platform === 'linux') {
+    try {
+      return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ').trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * `dead` | `matched` | `mismatched` | `unknown` for a PID.
+ *
+ * `unknown` means identity could not be read; callers treat it as "alive but
+ * unverified" — never as confirmation that the PID is ours.
+ */
+export function getProcessState(pid: number): ProcessState {
+  if (!isProcessAlive(pid)) return 'dead';
+  const command = readProcessCommandLine(pid);
+  if (command === null) return 'unknown';
+  return command.toLowerCase().includes('ompchamber') ? 'matched' : 'mismatched';
+}