ompchamber 0.8.0 → 1.1.0

package/src/server/lib/queue/delivery.server.test.ts

@@ -0,0 +1,203 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The follow-up queue must never wedge.
+ *
+ * A scheduled delivery whose timer never runs (a `bun --hot` module
+ * re-evaluation discards the pending closure; a wedged event loop drops the
+ * callback) used to poison the session permanently: the in-flight guard
+ * early-returned on the leftover entry, so no later trigger — another
+ * agent_end, a tab's mount nudge — could ever schedule again. The queue simply
+ * stopped draining, with no error anywhere. Observed live: a dev server whose
+ * `setTimeout` from request handlers had stopped firing left every queued
+ * follow-up stranded, while a freshly started server delivered the identical
+ * item correctly.
+ *
+ * The store is mocked so the contract under test is delivery's own: which RPCs
+ * a claimed item produces, and that a lost timer is superseded rather than
+ * allowed to wedge the session. Time is driven by fake timers, so nothing here
+ * waits on the wall clock.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, jest, mock, test } from 'bun:test';
+import type { QueuedMessage } from '@/shared/types/chat';
+import type { QueueDeliveryHost } from '@/server/lib/queue/delivery.server';
+
+/** In-memory stand-in for the SQLite-backed queue. */
+const queue = new Map<string, QueuedMessage[]>();
+
+mock.module('@/server/lib/queue/store.server', () => ({
+  claimHeadQueueItem: (sessionId: string): QueuedMessage | null => {
+    const items = queue.get(sessionId);
+    return items?.shift() ?? null;
+  },
+  requeueHeadQueueItem: async (sessionId: string, item: QueuedMessage): Promise<void> => {
+    const items = queue.get(sessionId) ?? [];
+    items.unshift(item);
+    queue.set(sessionId, items);
+  },
+}));
+
+const { scheduleQueueDelivery } = await import('@/server/lib/queue/delivery.server');
+
+const MODEL = { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max', accessMode: 'yolo' as const };
+
+function queueItem(text: string, model: QueuedMessage['model'] = MODEL): QueuedMessage {
+  return { id: `item-${text}`, text, attachments: [], model };
+}
+
+/** Records the RPCs a delivery pushes at the session. */
+function makeHost(sessionId: string) {
+  const sent: Record<string, unknown>[] = [];
+  const host: QueueDeliveryHost = {
+    sessionId,
+    isAlive: () => true,
+    isBusy: () => false,
+    send: async (command) => {
+      sent.push(command);
+      return {};
+    },
+  };
+  return { host, sent };
+}
+
+/** Let the delivery's promise chain settle without advancing the clock. */
+async function flush(): Promise<void> {
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+}
+
+let sessionId = '';
+let counter = 0;
+
+beforeEach(() => {
+  sessionId = `queue-test-${counter++}`;
+  queue.clear();
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+describe('queue delivery', () => {
+  test('delivers the head with the model snapshot it was queued with', async () => {
+    queue.set(sessionId, [queueItem('queued hello')]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([
+      { type: 'set_model', provider: 'kenari', modelId: 'deepseek-v4-pro' },
+      { type: 'set_thinking_level', level: 'max' },
+      { type: 'prompt', message: 'queued hello', accessMode: 'yolo' },
+    ]);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
+  test("an 'auto' thinking level is left to the session", async () => {
+    queue.set(sessionId, [queueItem('no level', { ...MODEL, thinkingLevel: 'auto' })]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([
+      { type: 'set_model', provider: 'kenari', modelId: 'deepseek-v4-pro' },
+      { type: 'prompt', message: 'no level', accessMode: 'yolo' },
+    ]);
+  });
+
+  test('an item with no model snapshot is sent without touching the model', async () => {
+    queue.set(sessionId, [queueItem('session model', null)]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([{ type: 'prompt', message: 'session model' }]);
+  });
+
+  test('a busy session holds the item instead of sending it', async () => {
+    queue.set(sessionId, [queueItem('held')]);
+    const { host, sent } = makeHost(sessionId);
+    host.isBusy = () => true;
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent).toEqual([]);
+    expect(queue.get(sessionId)?.length).toBe(1);
+  });
+
+  test('a failed dispatch returns the item to the head', async () => {
+    queue.set(sessionId, [queueItem('retry me')]);
+    const { host } = makeHost(sessionId);
+    host.send = async () => {
+      throw new Error('rpc down');
+    };
+
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(queue.get(sessionId)?.map((i) => i.text)).toEqual(['retry me']);
+  });
+
+  test('repeated triggers deliver the head exactly once', async () => {
+    queue.set(sessionId, [queueItem('once')]);
+    const { host, sent } = makeHost(sessionId);
+
+    scheduleQueueDelivery(host);
+    scheduleQueueDelivery(host);
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent.filter((c) => c.type === 'prompt').length).toBe(1);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
+  test('a lost timer delays the queue instead of wedging it', async () => {
+    queue.set(sessionId, [queueItem('recovered')]);
+    const { host, sent } = makeHost(sessionId);
+
+    // A delivery was scheduled but its callback never ran — the entry is left
+    // behind, which is exactly what a hot-reloaded module or a wedged event
+    // loop leaves. `clearAllTimers` drops the pending callback WITHOUT running
+    // it, so the bookkeeping outlives the timer.
+    scheduleQueueDelivery(host);
+    jest.clearAllTimers();
+    jest.advanceTimersByTime(600);
+    await flush();
+    expect(sent).toEqual([]);
+
+    // Inside the staleness bound a new trigger still defers to the pending
+    // entry: the head must not be double-booked.
+    jest.advanceTimersByTime(1000);
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+    expect(sent).toEqual([]);
+
+    // Past it, a later trigger recovers the queue rather than giving up.
+    jest.advanceTimersByTime(5000);
+    scheduleQueueDelivery(host);
+    jest.advanceTimersByTime(600);
+    await flush();
+
+    expect(sent.filter((c) => c.type === 'prompt').length).toBe(1);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+});

package/src/server/lib/queue/delivery.server.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Server-side follow-up queue auto-delivery: the run's own `agent_end` — as
+ * observed by the session wrapper, the process that owns the omp child —
+ * triggers the next queued prompt. This replaces the client-driven
+ * auto-delivery whose state races (tab reload wiping the table, session
+ * switches sending a queue into the wrong session) made queued messages
+ * disappear or land in the wrong conversation.
+ *
+ * Semantics:
+ * - The head is CLAIMED (transactional DELETE) before dispatch, so a second
+ *   trigger — another tab's nudge, a racing run end — can never double-send.
+ * - A failed dispatch re-inserts the item at the head; nothing is lost.
+ * - A user Stop clears the pending-delivery timer instead of delivering (the
+ *   item stays claimed-but-returned... it is re-queued first), so stop-all
+ *   semantics live on the server now.
+ */
+
+import { claimHeadQueueItem, requeueHeadQueueItem } from '@/server/lib/queue/store.server';
+import type { QueuedMessage } from '@/shared/types/chat';
+
+/** Settling time between agent_end and the next prompt dispatch. Small on
+ *  purpose: omp's own turn-end bookkeeping (JSONL flush, title slot) runs on
+ *  the same child, and an instant dispatch races it. */
+const DELIVERY_DELAY_MS = 500;
+
+/**
+ * How long a scheduled-but-not-yet-run delivery may sit before the next
+ * trigger supersedes it.
+ *
+ * Without this, one lost timer wedges the session's queue FOREVER: the guard
+ * below early-returns on any existing entry, so nothing would ever schedule
+ * again. A timer can be lost without the process dying — `bun --hot`
+ * re-evaluating this module discards the pending closure, and a wedged event
+ * loop drops the callback — and the symptom is silent: the queue simply never
+ * drains and no error is reported. Past this bound the entry is presumed lost
+ * and rescheduled, so a client nudge (sent whenever a session with queued
+ * items mounts or regains focus) always recovers the queue.
+ */
+const DELIVERY_STALE_MS = 5_000;
+
+interface PendingDelivery {
+  timer: ReturnType<typeof setTimeout>;
+  /** Wall-clock after which this entry is presumed lost and superseded. */
+  expiresAt: number;
+}
+
+/** Per-session pending delivery timer, so a second agent_end while one is
+ *  already scheduled cannot double-book the head. */
+const pendingTimers = new Map<string, PendingDelivery>();
+
+function clearPendingTimer(sessionId: string): void {
+  const entry = pendingTimers.get(sessionId);
+  if (entry === undefined) return;
+  clearTimeout(entry.timer);
+  pendingTimers.delete(sessionId);
+}
+
+/** Send one queued item to the session as a normal prompt. The model snapshot
+ *  rides first (set_model / set_thinking_level) exactly like the composer's
+ *  queued delivery did. Returns false when the dispatch failed. */
+async function dispatchQueuedItem(session: QueueDeliveryHost, item: QueuedMessage): Promise<boolean> {
+  try {
+    if (item.model) {
+      await session.send({ type: 'set_model', provider: item.model.provider, modelId: item.model.modelId });
+      if (item.model.thinkingLevel !== 'auto') {
+        await session.send({ type: 'set_thinking_level', level: item.model.thinkingLevel });
+      }
+    }
+    const images = item.attachments
+      .filter((a) => typeof a?.preview === 'string' && a.preview.startsWith('data:image/') && typeof a?.dataBase64 === 'string')
+      .map((a) => ({ type: 'image' as const, data: a.dataBase64 as string, mimeType: a.preview.slice(5).split(';')[0] || 'image/png' }));
+    await session.send({
+      type: 'prompt',
+      message: item.text,
+      ...(images.length ? { images } : {}),
+      ...(item.model ? { accessMode: item.model.accessMode } : {}),
+    });
+    return true;
+  } catch (error) {
+    console.error(`[queue] delivery failed for session ${session.sessionId}:`, error);
+    return false;
+  }
+}
+
+/** Minimal surface delivery needs from a live session wrapper. */
+export interface QueueDeliveryHost {
+  sessionId: string;
+  isAlive(): boolean;
+  isBusy(): boolean;
+  send(command: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * Schedule the next queued delivery for this session. Called on terminal
+ * agent_end and on a client's mount nudge. Idempotent: an in-flight timer is
+ * reused, a claimed head can only be won by one caller.
+ *
+ * A pending entry older than {@link DELIVERY_STALE_MS} is presumed lost (see
+ * that constant) and replaced, so a dropped timer delays the queue instead of
+ * wedging it.
+ */
+export function scheduleQueueDelivery(session: QueueDeliveryHost): void {
+  const sessionId = session.sessionId;
+  if (!sessionId) return;
+  const pending = pendingTimers.get(sessionId);
+  if (pending !== undefined) {
+    if (Date.now() < pending.expiresAt) return;
+    // Lost timer: clear it so its callback cannot also fire and double-deliver.
+    clearTimeout(pending.timer);
+  }
+  const timer = setTimeout(() => {
+    pendingTimers.delete(sessionId);
+    void deliverNext(session);
+  }, DELIVERY_DELAY_MS);
+  pendingTimers.set(sessionId, { timer, expiresAt: Date.now() + DELIVERY_STALE_MS });
+}
+
+async function deliverNext(session: QueueDeliveryHost): Promise<void> {
+  const sessionId = session.sessionId;
+  if (!session.isAlive() || session.isBusy()) return;
+  const item = claimHeadQueueItem(sessionId);
+  if (!item) return;
+  const ok = await dispatchQueuedItem(session, item);
+  if (!ok) await requeueHeadQueueItem(sessionId, item);
+}
+
+/**
+ * A user Stop: return anything already claimed for this session's pending
+ * delivery to the queue and cancel the timer. The item keeps its head
+ * position; nothing is sent until the next run end or explicit send.
+ */
+export function cancelQueuedDelivery(sessionId: string): void {
+  clearPendingTimer(sessionId);
+}
+
+/** Forget a session's timer state (process teardown, session destroy). */
+export function forgetQueuedDelivery(sessionId: string): void {
+  clearPendingTimer(sessionId);
+}

package/src/server/lib/queue/schema-migration.server.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Schema migration for `queued_messages`: installs older databases created the
+ * table with an FK to `sessions`, but omp session ids have no row there —
+ * every queue insert for a real session failed with FOREIGN KEY constraint
+ * failed. Rebuilds the table without the FK, once, marker-keyed in
+ * `app_settings` (same pattern as project-settings-migration).
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+
+const QUEUE_FK_MARKER = 'queue_fk_removed';
+
+const QUEUE_TABLE_SQL = `
+  CREATE TABLE queued_messages_new (
+    id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    message TEXT NOT NULL DEFAULT '',
+    attachments TEXT NOT NULL DEFAULT '[]',
+    provider TEXT,
+    model_id TEXT,
+    thinking_level TEXT,
+    access_mode TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  );
+  INSERT INTO queued_messages_new
+    (id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode, created_at)
+  SELECT id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode, created_at
+    FROM queued_messages;
+  DROP TABLE queued_messages;
+  ALTER TABLE queued_messages_new RENAME TO queued_messages;
+`;
+
+/** Drop the invalid queue FK on pre-migration databases (idempotent). */
+export async function migrateQueueTableFk(db: DbClient): Promise<void> {
+  const marker = await db.get('SELECT value FROM app_settings WHERE key = ?', [QUEUE_FK_MARKER]);
+  if (marker?.value) return;
+
+  const table = await db.get(
+    "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'queued_messages'",
+  );
+  const hasLegacyFk = Boolean(table?.sql) && String(table.sql).includes('FOREIGN KEY');
+  if (hasLegacyFk) await db.exec(QUEUE_TABLE_SQL);
+  await db.run('INSERT OR REPLACE INTO app_settings (key, value) VALUES (?, ?)', [QUEUE_FK_MARKER, '1']);
+}

package/src/server/lib/queue/store.server.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * SQLite-backed follow-up queue store (`queued_messages` table).
+ *
+ * The server is the single source of truth: the client panel is a view that
+ * mutates through per-item operations, and every mutation returns the
+ * canonical queue so callers reconcile from the response instead of merging
+ * local state. Rows carry a model snapshot (provider, model_id,
+ * thinking_level, access_mode) so auto-delivery replays the settings the item
+ * was queued with.
+ *
+ * Delivery claims the head with a transactional DELETE (bun:sqlite is
+ * synchronous, so BEGIN…COMMIT cannot interleave with another request), which
+ * makes "exactly one consumer sends the head" hold across tabs, reloads and
+ * concurrent nudges. A failed send re-inserts the claimed row at the head.
+ */
+
+import { getDb, getDbSync } from '@/server/db.server';
+import { withTransaction } from '@/shared/lib/db/transaction.server';
+import { isApprovalMode } from '@/shared/lib/omp/config/access-mode';
+import type { QueuedMessage, QueuedMessageModel } from '@/shared/types/chat';
+
+interface QueueRow {
+  id: string;
+  session_id: string;
+  position: number;
+  message: string;
+  attachments: string;
+  provider: string | null;
+  model_id: string | null;
+  thinking_level: string | null;
+  access_mode: string | null;
+}
+
+export function rowToQueuedMessage(row: QueueRow): QueuedMessage {
+  let attachments: unknown = [];
+  try {
+    attachments = JSON.parse(row.attachments);
+  } catch {
+    attachments = [];
+  }
+  const model: QueuedMessageModel | null =
+    row.provider && row.model_id
+      ? {
+          provider: row.provider,
+          modelId: row.model_id,
+          thinkingLevel: row.thinking_level ?? 'auto',
+          accessMode: isApprovalMode(row.access_mode) ? row.access_mode : 'always-ask',
+        }
+      : null;
+  return {
+    id: row.id,
+    text: row.message,
+    attachments: Array.isArray(attachments) ? (attachments as QueuedMessage['attachments']) : [],
+    model,
+  };
+}
+
+export function normalizeModel(raw: unknown): QueuedMessageModel | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const m = raw as Record<string, unknown>;
+  if (typeof m.provider !== 'string' || typeof m.modelId !== 'string') return null;
+  return {
+    provider: m.provider,
+    modelId: m.modelId,
+    thinkingLevel: typeof m.thinkingLevel === 'string' ? m.thinkingLevel : 'auto',
+    accessMode: isApprovalMode(m.accessMode) ? m.accessMode : 'always-ask',
+  };
+}
+
+function serializeAttachments(attachments: unknown): string {
+  return JSON.stringify(Array.isArray(attachments) ? attachments : []);
+}
+
+interface QueueItemInput {
+  text: string;
+  attachments?: unknown;
+  model?: unknown;
+}
+
+/** The session's queued follow-ups in delivery order. */
+export async function listQueue(sessionId: string): Promise<QueuedMessage[]> {
+  const db = await getDb();
+  const rows = (await db.all(
+    'SELECT * FROM queued_messages WHERE session_id = ? ORDER BY position ASC',
+    [sessionId],
+  )) as QueueRow[];
+  return rows.map(rowToQueuedMessage);
+}
+
+/** Append one item; returns the canonical queue. */
+export async function appendQueueItem(sessionId: string, input: QueueItemInput): Promise<QueuedMessage[]> {
+  const db = await getDb();
+  const model = normalizeModel(input.model);
+  const id = crypto.randomUUID();
+  db.raw.run(
+    `INSERT INTO queued_messages (id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode)
+     VALUES (?, ?, COALESCE((SELECT MAX(position) FROM queued_messages WHERE session_id = ?), -1) + 1, ?, ?, ?, ?, ?, ?)`,
+    [id, sessionId, sessionId, input.text, serializeAttachments(input.attachments),
+      model?.provider ?? null, model?.modelId ?? null, model?.thinkingLevel ?? null, model?.accessMode ?? null],
+  );
+  return listQueue(sessionId);
+}
+
+/** Patch one item's text/model; null when the id is unknown. */
+export async function patchQueueItem(
+  sessionId: string,
+  id: string,
+  patch: { text?: unknown; model?: unknown },
+): Promise<QueuedMessage[] | null> {
+  const db = await getDb();
+  const sets: string[] = [];
+  const values: unknown[] = [];
+  if (typeof patch.text === 'string') {
+    sets.push('message = ?');
+    values.push(patch.text);
+  }
+  if (patch.model !== undefined) {
+    const model = normalizeModel(patch.model);
+    sets.push('provider = ?', 'model_id = ?', 'thinking_level = ?', 'access_mode = ?');
+    values.push(model?.provider ?? null, model?.modelId ?? null, model?.thinkingLevel ?? null, model?.accessMode ?? null);
+  }
+  if (sets.length === 0) return listQueue(sessionId);
+  const result = await db.run(
+    `UPDATE queued_messages SET ${sets.join(', ')} WHERE session_id = ? AND id = ?`,
+    [...values, sessionId, id],
+  );
+  if (!result.changes) return null;
+  return listQueue(sessionId);
+}
+
+/** Remove one item by id; false when it was already claimed or absent. */
+export async function deleteQueueItem(sessionId: string, id: string): Promise<boolean> {
+  const db = await getDb();
+  const result = await db.run('DELETE FROM queued_messages WHERE session_id = ? AND id = ?', [sessionId, id]);
+  return result.changes > 0;
+}
+
+/** Reorder the queue to exactly `orderedIds` (unknown ids are ignored). */
+export async function reorderQueue(sessionId: string, orderedIds: string[]): Promise<QueuedMessage[]> {
+  const db = await getDb();
+  withTransaction(db, () => {
+    const update = db.raw.query('UPDATE queued_messages SET position = ? WHERE session_id = ? AND id = ?');
+    orderedIds.forEach((id, index) => update.run(index, sessionId, id));
+  });
+  return listQueue(sessionId);
+}
+
+/**
+ * Atomically claim the head for delivery: read + delete inside one
+ * transaction, so a concurrent claimant (second tab, reload nudge racing a
+ * run end) can never observe — and send — the same item twice. Null when the
+ * queue is empty. Synchronous by construction: `bun:sqlite` is sync, so the
+ * BEGIN…COMMIT block cannot interleave with another request.
+ */
+export function claimHeadQueueItem(sessionId: string): QueuedMessage | null {
+  const db = getDbSync();
+  return withTransaction(db, () => {
+    const row = db.raw
+      .query('SELECT * FROM queued_messages WHERE session_id = ? ORDER BY position ASC LIMIT 1')
+      .get(sessionId) as QueueRow | undefined;
+    if (!row) return null;
+    db.raw.run('DELETE FROM queued_messages WHERE id = ?', [row.id]);
+    return rowToQueuedMessage(row);
+  });
+}
+
+/**
+ * Put a failed delivery back at the head (position below the current minimum)
+ * so it is retried before anything else. The next run end or mount nudge
+ * picks it up again.
+ */
+export async function requeueHeadQueueItem(sessionId: string, item: QueuedMessage): Promise<void> {
+  const db = await getDb();
+  db.raw.run(
+    `INSERT INTO queued_messages (id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode)
+     VALUES (?, ?, COALESCE((SELECT MIN(position) FROM queued_messages WHERE session_id = ?), 0) - 1, ?, ?, ?, ?, ?, ?)`,
+    [item.id, sessionId, sessionId, item.text, serializeAttachments(item.attachments),
+      item.model?.provider ?? null, item.model?.modelId ?? null, item.model?.thinkingLevel ?? null, item.model?.accessMode ?? null],
+  );
+}

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

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Is a shell busy, or sitting at its prompt?
+ *
+ * The PTY's foreground process group answers this exactly, and the kernel keeps
+ * it up to date: when a command runs in the foreground the terminal's `tpgid`
+ * becomes that command's group, and when the shell regains control `tpgid`
+ * returns to the shell's own pid. Verified on macOS against a real PTY —
+ * `sleep 30` moved `tpgid` off the shell's pid, `Ctrl+C` and a backgrounded job
+ * both left it on the shell's pid (a background job is by definition not the
+ * foreground job).
+ *
+ * Why it matters: the terminal cap counts *live* shells. "Live" has to mean
+ * "has work in flight", otherwise a panel that was opened, restarted, or
+ * switched a few times pins the budget with shells that are all idle at a
+ * prompt, and the next attach is rejected with nothing actually running.
+ *
+ * Cost is one `ps` call for the whole registry, so this is safe to run on every
+ * attach. It is advisory: any failure resolves to "not busy", because refusing
+ * a shell to save a slot is worse than letting one extra through.
+ */
+
+const PS_TIMEOUT_MS = 1500;
+
+/** `pid` is the shell's process (it is the PTY session leader, so pgid === pid). */
+export interface ShellProcess {
+  id: string;
+  pid: number;
+}
+
+export async function detectBusyShells(shells: ShellProcess[]): Promise<Set<string>> {
+  const busy = new Set<string>();
+  if (shells.length === 0 || process.platform === 'win32') return busy;
+
+  const byPid = new Map<number, string>();
+  for (const shell of shells) byPid.set(shell.pid, shell.id);
+
+  const ps = Bun.spawn(['ps', '-o', 'pid=,tpgid=', '-p', shells.map((s) => s.pid).join(',')], {
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+
+  let output = '';
+  try {
+    output = await Promise.race([
+      new Response(ps.stdout).text(),
+      Bun.sleep(PS_TIMEOUT_MS).then(() => ''),
+    ]);
+  } catch {
+    // The pipe died; fall through to the kill and the empty result.
+  }
+  try {
+    ps.kill('SIGKILL');
+  } catch {
+    // Already exited.
+  }
+  void ps.exited.catch(() => {});
+
+  for (const line of output.split('\n')) {
+    const [pidText, tpgidText] = line.trim().split(/\s+/);
+    const pid = Number(pidText);
+    const tpgid = Number(tpgidText);
+    if (!Number.isFinite(pid) || !Number.isFinite(tpgid)) continue;
+    const id = byPid.get(pid);
+    // The shell holds the terminal exactly when it is its own foreground group.
+    if (id !== undefined && tpgid !== pid) busy.add(id);
+  }
+  return busy;
+}