@idl3/claude-control 0.4.1 → 1.1.0

package/lib/ws-heartbeat.js

@@ -0,0 +1,32 @@
+/**
+ * WebSocket ping/pong heartbeat helpers.
+ *
+ * Extracted from server.js so tests can import pruneDeadClients without
+ * booting the HTTP/WS server.
+ */
+
+/**
+ * Prune dead WebSocket clients using the ping/pong aliveness flag.
+ *
+ * On every heartbeat tick the server calls this with `wss.clients`.  Any
+ * client whose `isAlive` flag is still `false` from the previous sweep is
+ * terminated (firing its existing `close` handler → existing cleanup /
+ * `maybeTeardown`).  Live clients have their flag reset to `false` and
+ * receive a ping; if they respond with a pong the `pong` handler in
+ * server.js sets `isAlive = true` before the next sweep.
+ *
+ * New connections set `isAlive = true` on creation, so they are never
+ * terminated on the very first sweep.
+ *
+ * @param {Iterable<{isAlive:boolean,terminate:()=>void,ping:()=>void}>} clients
+ */
+export function pruneDeadClients(clients) {
+  for (const ws of clients) {
+    if (ws.isAlive === false) {
+      ws.terminate();
+    } else {
+      ws.isAlive = false;
+      ws.ping();
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idl3/claude-control",
-  "version": "0.4.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "Local web UI to watch and drive your Claude Code sessions running in tmux — live transcripts, reply, answer AskUserQuestion, attach files, from a browser or phone.",
   "keywords": [

package/server.js

@@ -10,7 +10,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
-import { spawn } from 'node:child_process';
+import { spawn, execFile as _execFileRaw } from 'node:child_process';
+import { promisify } from 'node:util';
+import fsp from 'node:fs/promises';
+
+const _execFile = promisify(_execFileRaw);
 import { WebSocketServer } from 'ws';
 
 import * as tmux from './lib/tmux.js';
@@ -27,6 +31,7 @@ import { sweepUploads, resolveUploadPath } from './lib/uploads.js';
 import { getVersionInfo, currentVersion } from './lib/version.js';
 import * as push from './lib/push.js';
 import { readConfig, writeConfig } from './lib/config.js';
+import { parseCodexRecord, parseCodexPrompt, buildSpawnCommand } from './lib/codex.js';
 import { optimizePrompt, rulesOptimize } from './lib/optimize.js';
 import * as mlx from './lib/mlx.js';
 import {
@@ -42,7 +47,8 @@ import { listSkills, readSkill } from './lib/skills.js';
 // library auto-selects the FIRST offered one (the non-secret WS_PROTOCOL label)
 // and echoes it, so we never reflect the raw token back and need no custom
 // handleProtocols here. checkWsToken just verifies the token is among the offers.
-import { checkToken as authCheckToken, checkWsToken } from './lib/auth.js';
+import { checkToken as authCheckToken, checkWsToken, safeTokenEqual } from './lib/auth.js';
+import { pruneDeadClients } from './lib/ws-heartbeat.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Prefer the built assistant-ui app (web/dist) when present; otherwise fall back
@@ -75,6 +81,8 @@ const CONFIG = {
   host: env('HOST') || '127.0.0.1',
   projectsRoot:
     env('PROJECTS') || path.join(os.homedir(), '.claude', 'projects'),
+  codexSessionsRoot:
+    env('CODEX_SESSIONS') || path.join(os.homedir(), '.codex', 'sessions'),
   // 768MB: a long-running Node server (WS + transcript tailing + the bundled
   // web app) baselines ~300-450MB of V8 heap + RSS, so the old 350MB budget
   // tripped "over limit" permanently. Override with CLAUDE_CONTROL_RSS_LIMIT_MB.
@@ -122,7 +130,7 @@ const IMAGE_MIME = {
 };
 
 // --- shared state -----------------------------------------------------------
-const registry = new SessionRegistry({ projectsRoot: CONFIG.projectsRoot, tmux });
+const registry = new SessionRegistry({ projectsRoot: CONFIG.projectsRoot, codexSessionsRoot: CONFIG.codexSessionsRoot, tmux });
 const resources = new ResourceMonitor({ rssLimitMB: CONFIG.rssLimitMB });
 
 // Manual transcript pins (windowId.paneIndex -> transcript path). Loaded at boot,
@@ -152,7 +160,7 @@ function checkTerminalToken(reqUrl) {
   if (!CONFIG.token) return true;
   try {
     const u = new URL(reqUrl, 'http://localhost');
-    return u.searchParams.get('token') === CONFIG.token;
+    return safeTokenEqual(u.searchParams.get('token'), CONFIG.token);
   } catch {
     return false;
   }
@@ -204,6 +212,7 @@ const _tls = loadTls();
 const _scheme = _tls ? 'https' : 'http';
 
 const _handler = (req, res) => {
+  try {
   const u = new URL(req.url, 'http://localhost');
 
   if (u.pathname === '/api/sessions') {
@@ -345,6 +354,33 @@ const _handler = (req, res) => {
     if (!checkToken(req)) return endJson(res, 401, { error: 'unauthorized' });
     return handleTranscribe(req, res, u);
   }
+  // GET /api/spawn-agents — agent-type availability (claude vs codex).
+  // Returns which agent binaries are resolvable on this machine so the UI can
+  // disable an unavailable agent picker option and show a reason.
+  // Token-gated + localhost, same as other GET endpoints.
+  if (u.pathname === '/api/spawn-agents') {
+    if (!checkToken(req)) return endJson(res, 401, { error: 'unauthorized' });
+    const cfg = readConfig();
+    return Promise.all([
+      resolveBin(cfg.claudeBin || cfg.launchCommand),
+      resolveBin(cfg.codexBin || cfg.codexLaunchCommand),
+    ]).then(([claudeResult, codexResult]) => {
+      return endJson(res, 200, {
+        agents: [
+          {
+            id: 'claude',
+            available: claudeResult.available,
+            ...(claudeResult.available ? {} : { reason: claudeResult.reason }),
+          },
+          {
+            id: 'codex',
+            available: codexResult.available,
+            ...(codexResult.available ? {} : { reason: codexResult.reason }),
+          },
+        ],
+      });
+    }).catch((err) => endJson(res, 500, { error: String(err?.message || err) }));
+  }
   if (u.pathname === '/api/session/new') {
     if (req.method !== 'POST') return endJson(res, 405, { error: 'method not allowed' });
     if (!checkToken(req)) return endJson(res, 401, { error: 'unauthorized' });
@@ -388,8 +424,16 @@ const _handler = (req, res) => {
     return proxyTerminalHttp(req, res, u);
   }
 
+  // Unknown /api/* path: return JSON 404 instead of falling through to the SPA.
+  if (u.pathname.startsWith('/api/')) return endJson(res, 404, { error: 'not found' });
+
   // static
   serveStatic(u.pathname, res);
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.error('[handler] uncaught error:', e?.stack || e);
+    endJson(res, 500, { error: 'internal' });
+  }
 };
 
 const server = _tls
@@ -420,6 +464,7 @@ function handleUpdate(res) {
 }
 
 function endJson(res, code, obj) {
+  if (res.headersSent || res.writableEnded) return;
   const body = JSON.stringify(obj);
   res.writeHead(code, { 'content-type': MIME['.json'], 'content-length': Buffer.byteLength(body) });
   res.end(body);
@@ -661,6 +706,40 @@ function handleTranscribe(req, res, u) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// resolveBin — async PATH lookup for a binary name or absolute path.
+//
+// If `bin` is an absolute path, checks it is executable directly.
+// Otherwise runs `which <bin>` on PATH.
+//
+// Returns { available: true, path } on success, { available: false, reason }
+// on failure. Never throws.
+// ---------------------------------------------------------------------------
+async function resolveBin(bin) {
+  if (!bin || typeof bin !== 'string' || !bin.trim()) {
+    return { available: false, reason: 'no binary configured' };
+  }
+  const b = bin.trim();
+  // Absolute path: check existence + execute permission directly.
+  if (b.startsWith('/')) {
+    try {
+      await fsp.access(b, fsp.constants?.X_OK ?? 1);
+      return { available: true, path: b };
+    } catch {
+      return { available: false, reason: `binary not found or not executable: ${b}` };
+    }
+  }
+  // Relative / bare name: resolve via `which`.
+  try {
+    const { stdout } = await _execFile('which', [b], { timeout: 5000 });
+    const resolved = stdout.trim();
+    if (resolved) return { available: true, path: resolved };
+    return { available: false, reason: `${b} not found on PATH` };
+  } catch {
+    return { available: false, reason: `${b} not found on PATH` };
+  }
+}
+
 // POST /api/session/new — create a new tmux window in the configured (or
 // body-overridden) cwd, then type the launch command into it via send-keys so
 // the interactive shell resolves aliases. Security: the command is operator
@@ -676,23 +755,66 @@ async function handleSessionNew(req, res) {
   const config = readConfig();
   const cwd =
     typeof body.cwd === 'string' && body.cwd.trim() ? body.cwd : config.defaultCwd;
+
+  // agent ∈ {'claude','codex'}, default 'claude'.
+  const agent = body.agent === 'codex' ? 'codex' : 'claude';
+
   // Name is required-with-default: sanitize the requested name, falling back to
   // `session-<short-ts>` so a session is ALWAYS named (the rail reads the tmux
   // window name until a transcript title exists).
   const name = tmux.sanitizeName(body.name) || tmux.defaultSessionName();
+
+  // --- Pre-validation: binary resolution + cwd check BEFORE creating any window ---
+
+  // (i) Resolve the agent binary and return 400 if unavailable.
+  const agentBin = agent === 'codex'
+    ? (config.codexBin || config.codexLaunchCommand)
+    : (config.claudeBin || config.launchCommand);
+  const binCheck = await resolveBin(agentBin);
+  if (!binCheck.available) {
+    return endJson(res, 400, { error: `agent binary unavailable: ${binCheck.reason}` });
+  }
+
+  // (ii) For codex: pre-validate cwd exists and is a directory BEFORE createWindow,
+  //      so a bad request creates NO window (400 not 500, window-leak prevention).
+  if (agent === 'codex') {
+    try {
+      const st = await fsp.stat(cwd);
+      if (!st.isDirectory()) {
+        return endJson(res, 400, { error: `cwd is not a directory: ${cwd}` });
+      }
+    } catch {
+      return endJson(res, 400, { error: `cwd does not exist: ${cwd}` });
+    }
+  }
+
   try {
     // (1) Reliable named path: the tmux window name. createWindow sets it via
-    //     `new-window -n`, so the rail shows the name immediately.
+    //     `new-window -n` and the `-c cwd` flag — cwd flows through tmux's own
+    //     working-directory flag, never a shell `cd`.
     const target = await tmux.createWindow({ cwd, name });
-    // (2) Claude's own session title: `claude --help` exposes `-n/--name`
-    //     (display name in the prompt box, /resume picker, terminal title), so
-    //     we append it to the launch command rather than relying on a delayed
-    //     `/rename`. The name is shell-quoted (sanitizeName already stripped
-    //     control chars/newlines) since the command is typed into an interactive
-    //     shell so aliases like `yolo` resolve. sendText appends Enter → runs it.
-    const launch = `${config.launchCommand} --name ${tmux.shellQuoteName(name)}`;
+
+    let launch;
+    if (agent === 'codex') {
+      // Codex path: uses -C <cwd> (its own cwd flag). No --name flag — Codex
+      // has none. The tmux window is still named (above) so the rail shows it.
+      // cwd is shell-quoted (same quoting as names) since the command is typed
+      // into an interactive shell via sendText.
+      void buildSpawnCommand({ cwd, bin: config.codexLaunchCommand }); // validate shape
+      launch = `${config.codexLaunchCommand} -C ${tmux.shellQuoteName(cwd)}`;
+    } else {
+      // Claude path: BYTE-IDENTICAL to the pre-Phase-D implementation.
+      // (2) Claude's own session title: `claude --help` exposes `-n/--name`
+      //     (display name in the prompt box, /resume picker, terminal title), so
+      //     we append it to the launch command rather than relying on a delayed
+      //     `/rename`. The name is shell-quoted (sanitizeName already stripped
+      //     control chars/newlines) since the command is typed into an interactive
+      //     shell so aliases like `yolo` resolve. sendText appends Enter → runs it.
+      launch = `${config.launchCommand} --name ${tmux.shellQuoteName(name)}`;
+    }
+
     await tmux.sendText(target, launch);
-    return endJson(res, 200, { ok: true, target, name });
+    return endJson(res, 200, { ok: true, target, name, agent });
   } catch (err) {
     return endJson(res, 500, { error: String(err?.message || err) });
   }
@@ -953,6 +1075,47 @@ function serveIndexHtml(res) {
   });
 }
 
+// --- Per-target WS op serialisation ----------------------------------------
+// Multiple browser/device clients on the same session can fire overlapping
+// send-keys ops concurrently.  Two such ops dispatched to the same tmux pane
+// interleave keystrokes mid-sequence.  We prevent this with a per-target FIFO
+// promise chain: each send-keys op appends to the tail of its target's chain
+// and runs only after its predecessor settles.  Different targets run in
+// parallel.  Read-only ops (subscribe, capture, shell-capture, …) are NOT
+// enqueued — they never touch the pane input buffer.
+const _opChains = new Map(); // target → current-tail Promise
+
+/**
+ * Enqueue `fn` behind any in-flight op on `target`.
+ *
+ * Contract:
+ *  - The returned promise settles exactly as fn() settles (value / throw).
+ *  - A rejected op does NOT poison the next op on the same target — the chain
+ *    continues regardless of whether prev settled fulfilled or rejected.
+ *  - The Map entry is deleted once the queued op is the sole tail and it has
+ *    settled, preventing unbounded growth on idle targets.
+ *
+ * @param {string} target  tmux pane target (the serialisation key)
+ * @param {() => Promise<any>} fn  async work to serialise
+ * @returns {Promise<any>}
+ */
+function runSerial(target, fn) {
+  const prev = _opChains.get(target) ?? Promise.resolve();
+  // chain: run fn after prev regardless of prev's outcome
+  const tail = prev.then(fn, fn);
+  // Store the tail so the NEXT enqueue can chain behind it.
+  // Suppress any rejection on the stored promise so Node's
+  // unhandledRejection handler never fires on the chain itself —
+  // the caller's `tail` reference will surface the error to the caller.
+  const stored = tail.then(() => {}, () => {});
+  _opChains.set(target, stored);
+  // Clean up once this op is the last in the chain and it has settled.
+  stored.finally(() => {
+    if (_opChains.get(target) === stored) _opChains.delete(target);
+  });
+  return tail;
+}
+
 // --- WebSocket --------------------------------------------------------------
 // 1 MB cap: control messages are tiny; this prevents a single huge frame from
 // forcing a multi-hundred-MB string allocation in the cockpit process.
@@ -1083,7 +1246,7 @@ function ensureSubscription(id) {
     return sub;
   }
 
-  const tailer = new TranscriptTailer(session.transcriptPath, { maxBuffer: CONFIG.maxBuffer });
+  const tailer = new TranscriptTailer(session.transcriptPath, { maxBuffer: CONFIG.maxBuffer, parser: session.kind === 'codex' ? parseCodexRecord : undefined });
   // Watch this session's sub-agent transcripts (Task/Agent). Discovery is polled
   // when the parent transcript grows (when sub-agents spawn) + once at subscribe.
   const subagents = new SubAgentsWatcher(session.transcriptPath);
@@ -1139,20 +1302,27 @@ function ensureSubscription(id) {
 function startPromptPoller(id, sub) {
   if (sub.promptTimer) return;
   sub._lastPrompt = undefined;
+  sub._promptTicking = false;
   const tick = async () => {
-    const session = sessionById(id);
-    if (!session || !tmux.isValidTarget(session.target)) return;
-    let prompt = null;
+    if (sub._promptTicking) return;
+    sub._promptTicking = true;
     try {
-      const cap = await tmux.capturePane(session.target, 40);
-      prompt = parsePanePrompt(cap);
-    } catch {
-      return;
-    }
-    const json = prompt ? JSON.stringify(prompt) : null;
-    if (json !== sub._lastPrompt) {
-      sub._lastPrompt = json;
-      broadcastTo(id, { type: 'prompt', id, prompt });
+      const session = sessionById(id);
+      if (!session || !tmux.isValidTarget(session.target)) return;
+      let prompt = null;
+      try {
+        const cap = await tmux.capturePane(session.target, 40);
+        prompt = session.kind === 'codex' ? parseCodexPrompt(cap) : parsePanePrompt(cap);
+      } catch {
+        return;
+      }
+      const json = prompt ? JSON.stringify(prompt) : null;
+      if (json !== sub._lastPrompt) {
+        sub._lastPrompt = json;
+        broadcastTo(id, { type: 'prompt', id, prompt });
+      }
+    } finally {
+      sub._promptTicking = false;
     }
   };
   sub.promptTimer = setInterval(() => tick().catch(() => {}), 2000);
@@ -1171,6 +1341,9 @@ function maybeTeardown(id) {
 }
 
 wss.on('connection', (ws) => {
+  ws.isAlive = true;
+  ws.on('pong', () => { ws.isAlive = true; });
+
   send(ws, { type: 'sessions', sessions: registry.getSessions() });
   send(ws, { type: 'resources', snapshot: resources.snapshot() });
   ws._subs = new Set();
@@ -1193,6 +1366,9 @@ wss.on('connection', (ws) => {
   });
 });
 
+const heartbeatInterval = setInterval(() => pruneDeadClients(wss.clients), 30000);
+heartbeatInterval.unref();
+
 async function handleClientMessage(ws, msg) {
   switch (msg.type) {
     case 'subscribe': {
@@ -1228,8 +1404,11 @@ async function handleClientMessage(ws, msg) {
       const session = sessionById(msg.id);
       if (!session) throw new Error('unknown session');
       if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
-      await tmux.sendText(session.target, String(msg.text ?? ''));
-      return send(ws, { type: 'ack', op: 'reply', ok: true });
+      const replyText = String(msg.text ?? '');
+      return runSerial(session.target, async () => {
+        await tmux.sendText(session.target, replyText);
+        send(ws, { type: 'ack', op: 'reply', ok: true });
+      });
     }
     case 'answer': {
       const session = sessionById(msg.id);
@@ -1244,6 +1423,7 @@ async function handleClientMessage(ws, msg) {
         throw new Error('stale question (already answered or changed)');
       }
 
+      return runSerial(session.target, async () => {
       // ── Capture-driven path ──────────────────────────────────────────────
       // Attempt to navigate by parsing the live picker render. Falls back to
       // the static buildAnswerProgram on ANY parse failure, unknown label, or
@@ -1449,7 +1629,8 @@ async function handleClientMessage(ws, msg) {
         console.log(`[answer] sent toolUseId=${msg.toolUseId} via dynamic path`);
       }
 
-      return send(ws, { type: 'ack', op: 'answer', ok: true });
+      send(ws, { type: 'ack', op: 'answer', ok: true });
+      }); // end runSerial
     }
     case 'capture': {
       const session = sessionById(msg.id);
@@ -1467,16 +1648,22 @@ async function handleClientMessage(ws, msg) {
       const session = sessionById(msg.id);
       if (!session) throw new Error('unknown session');
       if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
-      await tmux.sendLiteral(session.target, String(msg.text ?? ''));
-      return send(ws, { type: 'ack', op: 'pane-text', ok: true });
+      const paneText = String(msg.text ?? '');
+      return runSerial(session.target, async () => {
+        await tmux.sendLiteral(session.target, paneText);
+        send(ws, { type: 'ack', op: 'pane-text', ok: true });
+      });
     }
     case 'pane-key': {
       const session = sessionById(msg.id);
       if (!session) throw new Error('unknown session');
       if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
       if (!shell.SHELL_KEYS.has(String(msg.key ?? ''))) throw new Error('key not allowed');
-      await tmux.sendRawKeys(session.target, [String(msg.key)]);
-      return send(ws, { type: 'ack', op: 'pane-key', ok: true });
+      const paneKey = String(msg.key);
+      return runSerial(session.target, async () => {
+        await tmux.sendRawKeys(session.target, [paneKey]);
+        send(ws, { type: 'ack', op: 'pane-key', ok: true });
+      });
     }
     case 'promptkey': {
       // Respond to a live TUI selection prompt (permission/menu). Whitelisted
@@ -1486,11 +1673,14 @@ async function handleClientMessage(ws, msg) {
       if (!tmux.isValidTarget(session.target)) throw new Error('invalid tmux target');
       const ALLOWED = new Set(['1', '2', '3', '4', '5', '6', '7', '8', '9', 'Enter', 'Escape', 'Up', 'Down']);
       if (!ALLOWED.has(msg.key)) throw new Error('key not allowed');
-      await tmux.sendRawKeys(session.target, [msg.key]);
-      // Force the next poll tick to broadcast (the prompt should now change/clear).
-      const sub = subscriptions.get(msg.id);
-      if (sub) sub._lastPrompt = '__force__';
-      return send(ws, { type: 'ack', op: 'promptkey', ok: true });
+      const promptKey = msg.key;
+      return runSerial(session.target, async () => {
+        await tmux.sendRawKeys(session.target, [promptKey]);
+        // Force the next poll tick to broadcast (the prompt should now change/clear).
+        const sub = subscriptions.get(msg.id);
+        if (sub) sub._lastPrompt = '__force__';
+        send(ws, { type: 'ack', op: 'promptkey', ok: true });
+      });
     }
     case 'promptselect': {
       // Respond to a live TUI multi-select checkbox prompt (surfaced via pane-scrape
@@ -1503,57 +1693,61 @@ async function handleClientMessage(ws, msg) {
       const labels = Array.isArray(msg.labels) ? msg.labels.map(String) : [];
       if (labels.length === 0) throw new Error('no labels provided');
 
-      const SETTLE_MS = 300;
+      return runSerial(session.target, async () => {
+        const SETTLE_MS = 300;
 
-      // 1. Capture current picker state.
-      let capture;
-      try {
-        capture = await tmux.capturePane(session.target);
-      } catch (captureErr) {
-        throw new Error(`promptselect: capture failed: ${captureErr?.message}`);
-      }
+        // 1. Capture current picker state.
+        let capture;
+        try {
+          capture = await tmux.capturePane(session.target);
+        } catch (captureErr) {
+          throw new Error(`promptselect: capture failed: ${captureErr?.message}`);
+        }
 
-      // 2. Parse into a structured picker model.
-      const parsed = parsePicker(capture);
-      if (parsed.confidence !== 'ok') {
-        return send(ws, {
-          type: 'ack',
-          op: 'promptselect',
-          ok: false,
-          error: 'promptselect: picker not found or low confidence — please retry',
-        });
-      }
+        // 2. Parse into a structured picker model.
+        const parsed = parsePicker(capture);
+        if (parsed.confidence !== 'ok') {
+          send(ws, {
+            type: 'ack',
+            op: 'promptselect',
+            ok: false,
+            error: 'promptselect: picker not found or low confidence — please retry',
+          });
+          return;
+        }
 
-      // 3. Build a synthetic single-question descriptor (multiSelect=true) so
-      //    planStep can calculate Space-toggle + action-row Enter keys.
-      const syntheticQuestion = {
-        multiSelect: true,
-        options: parsed.rows
-          .filter((r) => r.kind === 'option')
-          .map((r) => ({ label: r.label })),
-      };
-
-      // 4. Plan keystrokes via the tested planStep function.
-      const keys = planStep(parsed, syntheticQuestion, labels);
-      if (!keys) {
-        console.log(`[promptselect] planStep returned null for labels=${JSON.stringify(labels)} — low confidence`);
-        return send(ws, {
-          type: 'ack',
-          op: 'promptselect',
-          ok: false,
-          error: 'promptselect: could not map labels to picker rows — please retry',
-        });
-      }
+        // 3. Build a synthetic single-question descriptor (multiSelect=true) so
+        //    planStep can calculate Space-toggle + action-row Enter keys.
+        const syntheticQuestion = {
+          multiSelect: true,
+          options: parsed.rows
+            .filter((r) => r.kind === 'option')
+            .map((r) => ({ label: r.label })),
+        };
 
-      console.log(`[promptselect] id=${msg.id} labels=${JSON.stringify(labels)} keys=${JSON.stringify(keys)}`);
+        // 4. Plan keystrokes via the tested planStep function.
+        const keys = planStep(parsed, syntheticQuestion, labels);
+        if (!keys) {
+          console.log(`[promptselect] planStep returned null for labels=${JSON.stringify(labels)} — low confidence`);
+          send(ws, {
+            type: 'ack',
+            op: 'promptselect',
+            ok: false,
+            error: 'promptselect: could not map labels to picker rows — please retry',
+          });
+          return;
+        }
 
-      // 5. Send keys sequenced with settle delay (same as case 'answer' dynamic path).
-      await tmux.sendRawKeysSequenced(session.target, keys, SETTLE_MS);
+        console.log(`[promptselect] id=${msg.id} labels=${JSON.stringify(labels)} keys=${JSON.stringify(keys)}`);
 
-      // Force the next poll tick to broadcast (the prompt should now change/clear).
-      const promptSub = subscriptions.get(msg.id);
-      if (promptSub) promptSub._lastPrompt = '__force__';
-      return send(ws, { type: 'ack', op: 'promptselect', ok: true });
+        // 5. Send keys sequenced with settle delay (same as case 'answer' dynamic path).
+        await tmux.sendRawKeysSequenced(session.target, keys, SETTLE_MS);
+
+        // Force the next poll tick to broadcast (the prompt should now change/clear).
+        const promptSub = subscriptions.get(msg.id);
+        if (promptSub) promptSub._lastPrompt = '__force__';
+        send(ws, { type: 'ack', op: 'promptselect', ok: true });
+      });
     }
     // Composer terminal mode (>_): each Claude session has its OWN sister shell
     // pane in its window. Resolve the session by id → its target + cwd, then act
@@ -1561,20 +1755,29 @@ async function handleClientMessage(ws, msg) {
     case 'shell-input': {
       const s = sessionById(msg.id);
       if (!s) throw new Error('unknown session');
-      await shell.shellInput(s.target, s.cwd, String(msg.line ?? ''));
-      return send(ws, { type: 'ack', op: 'shell-input', ok: true });
+      const shellInputLine = String(msg.line ?? '');
+      return runSerial(s.target + ':shell', async () => {
+        await shell.shellInput(s.target, s.cwd, shellInputLine);
+        send(ws, { type: 'ack', op: 'shell-input', ok: true });
+      });
     }
     case 'shell-text': {
       const s = sessionById(msg.id);
       if (!s) throw new Error('unknown session');
-      await shell.shellText(s.target, s.cwd, String(msg.text ?? ''));
-      return send(ws, { type: 'ack', op: 'shell-text', ok: true });
+      const shellTextVal = String(msg.text ?? '');
+      return runSerial(s.target + ':shell', async () => {
+        await shell.shellText(s.target, s.cwd, shellTextVal);
+        send(ws, { type: 'ack', op: 'shell-text', ok: true });
+      });
     }
     case 'shell-key': {
       const s = sessionById(msg.id);
       if (!s) throw new Error('unknown session');
-      await shell.shellKey(s.target, s.cwd, String(msg.key ?? ''));
-      return send(ws, { type: 'ack', op: 'shell-key', ok: true });
+      const shellKeyVal = String(msg.key ?? '');
+      return runSerial(s.target + ':shell', async () => {
+        await shell.shellKey(s.target, s.cwd, shellKeyVal);
+        send(ws, { type: 'ack', op: 'shell-key', ok: true });
+      });
     }
     case 'shell-capture': {
       const s = sessionById(msg.id);
@@ -1691,8 +1894,10 @@ async function main() {
 }
 
 function shutdown() {
+  clearInterval(heartbeatInterval);
   for (const [, sub] of subscriptions) sub.tailer?.stop();
   terminal.shutdownAll();
+  mlx.shutdown();
   registry.stop();
   resources.stop();
   if (uploadSweepTimer) clearInterval(uploadSweepTimer);
@@ -1702,4 +1907,21 @@ function shutdown() {
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 
-main();
+// Safety nets: log unhandled async rejections; exit on truly uncaught sync
+// exceptions so Node doesn't continue with a corrupted process state.
+process.on('unhandledRejection', (e) => {
+  // eslint-disable-next-line no-console
+  console.error('[unhandledRejection]', e?.stack || e);
+});
+process.on('uncaughtException', (e) => {
+  // eslint-disable-next-line no-console
+  console.error('[uncaughtException]', e?.stack || e);
+  process.exit(1);
+});
+
+// Guard: only run the server when executed directly, not when imported for testing.
+const _isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (_isMain) main();
+
+// Exported for unit testing only — not part of the public API.
+export { endJson, _handler, runSerial };