lazyclaw 6.0.1 → 6.2.0

package/dotenv_min.mjs

@@ -5,6 +5,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { writeTextSecure } from './secure_write.mjs';
 
 export function loadDotenvIfAny(cfgDir) {
   const p = path.join(cfgDir, '.env');
@@ -21,3 +22,30 @@ export function loadDotenvIfAny(cfgDir) {
   }
   return { path: p, loaded };
 }
+
+// Read-merge-write <cfgDir>/.env at 0600. Existing keys are preserved;
+// keys present in `vars` are overwritten. Values are written verbatim
+// (no quoting) — callers pass already-trimmed strings. Returns the path.
+// Mirror of loadDotenvIfAny so .env read + write live together.
+export function writeDotenvMerge(cfgDir, vars) {
+  const p = path.join(cfgDir, '.env');
+  const lines = [];
+  const seen = new Set();
+  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  for (const line of existing.split(/\r?\n/)) {
+    const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=/);
+    if (m && Object.prototype.hasOwnProperty.call(vars, m[1])) {
+      seen.add(m[1]);
+      lines.push(`${m[1]}=${vars[m[1]]}`);
+    } else {
+      lines.push(line);
+    }
+  }
+  for (const [k, v] of Object.entries(vars)) {
+    if (!seen.has(k)) lines.push(`${k}=${v}`);
+  }
+  let text = lines.join('\n').replace(/\n+$/, '');
+  if (text) text += '\n';
+  writeTextSecure(p, text);
+  return p;
+}

package/first_run.mjs

@@ -13,3 +13,12 @@ export function firstRunMode({ hasProvider, flagPick, isTTY }) {
   if (!hasProvider) return 'setup';
   return 'none';
 }
+
+// A blank or 'mock' provider is a placeholder, not a real configured choice:
+// the mock provider returns canned replies and v5.3.2 stopped treating it as a
+// usable default. Treat both as "not configured" so the very first run always
+// lands in setup, and only a genuine saved provider skips it afterwards.
+const PLACEHOLDER_PROVIDERS = new Set(['', 'mock']);
+export function hasConfiguredProvider(provider) {
+  return !PLACEHOLDER_PROVIDERS.has(String(provider ?? '').trim().toLowerCase());
+}

package/lib/gateway_guard.mjs

@@ -0,0 +1,100 @@
+// lib/gateway_guard.mjs — boot-time safety guards + crash handlers for the
+// always-on gateway (the daemon and the channel listeners).
+//
+// These are deliberately small, pure, and dependency-free so every entry
+// point that opens a remote inbound surface can call them the same way and
+// fail CLOSED before a single message is accepted.
+
+export class GatewayGuardError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'GatewayGuardError';
+    this.code = code || 'GATEWAY_GUARD';
+  }
+}
+
+// `security.allowUnattendedSensitive` is a GLOBAL opt-in read by
+// mas/tool_runner.mjs for EVERY sensitive tool call (bash/write/net). It
+// bypasses the fail-closed approval gate process-wide. Combined with an
+// always-on channel or daemon surface, an inbound chat message could drive
+// bash/write with no human in the loop — remote-prompt-injection-to-RCE.
+// Refuse to start such a surface while the flag is set.
+export function assertUnattendedSafe(cfg, { surface = 'channel' } = {}) {
+  if (cfg && cfg.security && cfg.security.allowUnattendedSensitive === true) {
+    throw new GatewayGuardError(
+      `refusing to start a ${surface} surface while security.allowUnattendedSensitive=true: ` +
+        `that flag bypasses the fail-closed tool-approval gate for EVERY inbound message, so an ` +
+        `always-on ${surface} could run bash/write on remote command (RCE). Remove ` +
+        `security.allowUnattendedSensitive from your config (the ${surface} path does not need it), ` +
+        `or run sensitive tools only in an interactive session.`,
+      'UNATTENDED_SENSITIVE_WITH_CHANNEL',
+    );
+  }
+}
+
+// An unattended service (started under launchd/systemd, no operator at a
+// terminal) with an empty pairing allowlist answers anyone who can reach
+// it. Require at least one paired sender before booting in service mode.
+export function assertServicePairing(cfg, { service = false, surface = 'channel' } = {}) {
+  if (!service) return;
+  const allow = Array.isArray(cfg && cfg.pairing)
+    ? cfg.pairing.filter((p) => p && p.id != null)
+    : [];
+  if (allow.length === 0) {
+    throw new GatewayGuardError(
+      `refusing to start ${surface} in unattended --service mode with an empty pairing allowlist: ` +
+        `the agent would answer anyone who can reach it, 24/7. Pair at least one sender first: ` +
+        `lazyclaw pairing add <id>.`,
+      'SERVICE_REQUIRES_PAIRING',
+    );
+  }
+}
+
+// Process-level crash handlers for long-running processes. There are none in
+// the codebase, so a single unhandledRejection / uncaughtException kills the
+// always-on process with no log and no clean socket shutdown. This makes the
+// crash OBSERVABLE (structured log) and CLEAN (best-effort stop), then exits
+// non-zero so a service manager (launchd KeepAlive / systemd Restart) restarts
+// it. Deliberately NOT installed on the interactive TUI path — Ink manages the
+// terminal and needs its own handling (see tui/repl.mjs).
+//
+// Idempotent: a second call is a no-op and returns the same cleanup fn.
+const INSTALLED = Symbol.for('lazyclaw.gateway.crashHandlers');
+
+export function installCrashHandlers({ label = 'lazyclaw', logger = null, stop = null, exit = null } = {}) {
+  if (process[INSTALLED]) return process[INSTALLED];
+  const doExit = typeof exit === 'function' ? exit : (code) => process.exit(code);
+
+  const report = (kind, err) => {
+    const detail = {
+      level: 'fatal',
+      msg: 'crash',
+      label,
+      kind,
+      error: (err && (err.stack || err.message)) || String(err),
+    };
+    if (logger && typeof logger.error === 'function') logger.error('crash', detail);
+    else process.stderr.write(JSON.stringify(detail) + '\n');
+  };
+
+  const handle = (kind) => async (err) => {
+    report(kind, err);
+    if (typeof stop === 'function') {
+      try { await stop(); } catch { /* best-effort: we're already crashing */ }
+    }
+    doExit(1);
+  };
+
+  const onRej = handle('unhandledRejection');
+  const onExc = handle('uncaughtException');
+  process.on('unhandledRejection', onRej);
+  process.on('uncaughtException', onExc);
+
+  const cleanup = () => {
+    process.removeListener('unhandledRejection', onRej);
+    process.removeListener('uncaughtException', onExc);
+    delete process[INSTALLED];
+  };
+  process[INSTALLED] = cleanup;
+  return cleanup;
+}

package/lib/inbound_client.mjs

@@ -0,0 +1,108 @@
+// lib/inbound_client.mjs — the channel-listener -> daemon bridge.
+//
+// Phase 2 of the unified gateway: a channel listener no longer calls the
+// provider inline (its own per-process history Map). Instead it POSTs each
+// inbound message to the always-on daemon's session-bearing POST /inbound,
+// which binds {channel, externalId} -> a persistent session, hydrates prior
+// turns, runs the provider, and persists the turn. The result is one shared
+// agent (session + memory + skills) across chat, the dashboard, and every
+// channel — plus cross-channel /handoff lights up for free.
+
+export class InboundClientError extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.name = 'InboundClientError';
+    this.code = code || 'INBOUND_ERR';
+    this.status = status || 0;
+  }
+}
+
+// A connection refusal means the daemon isn't up yet (e.g. still starting, or
+// momentarily restarting under a service manager) — worth a short backoff.
+// Definitive HTTP answers (403/4xx/5xx) are NOT retried.
+function isConnRefused(err) {
+  if (!err) return false;
+  if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET') return true;
+  if (err.cause && (err.cause.code === 'ECONNREFUSED' || err.cause.code === 'ECONNRESET')) return true;
+  return /ECONNREFUSED|ECONNRESET|fetch failed|socket hang up/i.test(err.message || '');
+}
+
+export async function postInbound(opts, deps = {}) {
+  const { url, authToken, channel, externalId, senderId, messageId, text, provider, model } = opts;
+  const f = deps.fetchImpl || globalThis.fetch;
+  if (typeof f !== 'function') throw new InboundClientError('no fetch implementation available', 'NO_FETCH');
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const retries = Number.isFinite(deps.retries) ? deps.retries : 5;
+  const backoffMs = Number.isFinite(deps.backoffMs) ? deps.backoffMs : 250;
+  const endpoint = String(url).replace(/\/+$/, '') + '/inbound';
+
+  const payload = { text };
+  if (channel) payload.channel = channel;
+  if (externalId != null && externalId !== '') payload.externalId = String(externalId);
+  if (senderId != null && senderId !== '') payload.senderId = String(senderId);
+  // Native per-message id (Slack channel:ts, Telegram update_id, Matrix
+  // event_id) — lets /inbound dedup retries/redeliveries idempotently.
+  if (messageId != null && messageId !== '') payload.messageId = String(messageId);
+  if (provider) payload.provider = provider;
+  if (model) payload.model = model;
+  const headers = { 'content-type': 'application/json' };
+  if (authToken) headers['authorization'] = `Bearer ${authToken}`;
+
+  let lastErr = null;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    let resp;
+    try {
+      resp = await f(endpoint, { method: 'POST', headers, body: JSON.stringify(payload) });
+    } catch (err) {
+      lastErr = err;
+      if (isConnRefused(err) && attempt < retries) { await sleep(backoffMs * (attempt + 1)); continue; }
+      throw new InboundClientError(`daemon unreachable at ${endpoint}: ${err?.message || err}`, 'DAEMON_UNREACHABLE');
+    }
+    if (resp.status === 403) throw new InboundClientError('sender not paired', 'NOT_PAIRED', 403);
+    if (!resp.ok) {
+      let detail = '';
+      try { detail = await resp.text(); } catch { /* body is best-effort */ }
+      throw new InboundClientError(`daemon /inbound returned ${resp.status}${detail ? ': ' + detail.slice(0, 200) : ''}`, 'HTTP_ERROR', resp.status);
+    }
+    try { return await resp.json(); }
+    catch (err) { throw new InboundClientError(`bad JSON from /inbound: ${err?.message || err}`, 'BAD_JSON', resp.status); }
+  }
+  throw new InboundClientError(`daemon unreachable at ${endpoint} after ${retries + 1} attempts: ${lastErr?.message || lastErr}`, 'DAEMON_UNREACHABLE');
+}
+
+// Build the per-message handler a Channel calls. Shared by slack/telegram/
+// matrix listeners (they differ only in channel name + slack's @mention
+// strip). The handler returns the reply string to post back, or null to stay
+// silent (empty input, unpaired sender, empty daemon reply).
+export function makeInboundHandler(opts, deps = {}) {
+  const { channel, daemonUrl, daemonToken, provider, model } = opts;
+  const post = deps.postInbound || postInbound;
+  const log = deps.log || ((s) => process.stderr.write(s));
+  const stripMention = channel === 'slack';
+
+  return async ({ threadId, text, senderId, messageId } = {}) => {
+    let cleaned = String(text || '');
+    if (stripMention) cleaned = cleaned.replace(/<@[A-Z0-9]+>/g, '');
+    cleaned = cleaned.trim();
+    if (!cleaned) { log(`[${channel}] dropping empty inbound (after mention strip)\n`); return null; }
+    try {
+      const out = await post({ url: daemonUrl, authToken: daemonToken, channel, externalId: threadId, senderId, messageId, text: cleaned, provider, model });
+      // A duplicate means THIS message was already answered (redelivery, a
+      // restart replaying the backlog, the Slack double-fire landing twice):
+      // the channel already has the reply, so posting the replayed body
+      // would double-post. Stay silent. (Raw /inbound API callers still get
+      // the replayed body — this gate is listener-side only.)
+      if (out && out.duplicate) { log(`[${channel}] duplicate message — already answered, staying silent\n`); return null; }
+      const reply = out && typeof out.reply === 'string' ? out.reply : '';
+      if (!reply.trim()) { log(`[${channel}] daemon returned empty reply — not posting\n`); return null; }
+      return reply;
+    } catch (err) {
+      // Unpaired senders are dropped silently — that is what pairing is for.
+      if (err && err.code === 'NOT_PAIRED') { log(`[${channel}] sender not paired — ignoring\n`); return null; }
+      // Anything else: log the detail to stderr (operator), but post only a
+      // generic line to the channel so we never leak internals to users.
+      log(`[${channel}] inbound bridge error: ${err?.message || err}\n`);
+      return '(agent unavailable — backend not reachable)';
+    }
+  };
+}

package/lib/service_install.mjs

@@ -0,0 +1,207 @@
+// lib/service_install.mjs — install a lazyclaw long-running command as an
+// always-on OS service across three backends:
+//   - launchd  (macOS): plist with RunAtLoad + KeepAlive
+//   - systemd  (Linux user unit): Restart=always
+//   - fallback (no service manager): detached child + pidfile
+//
+// The unit-file builders + backend detection are PURE. The apply layer
+// (install/uninstall/status) takes injectable deps (fs/spawn/spawnSync/isAlive)
+// so it is fully testable without touching the real OS.
+//
+// NOTE: this is distinct from cron.mjs's plist machinery, which emits a
+// StartCalendarInterval (scheduled) plist with RunAtLoad=false — the opposite
+// of an always-on service.
+
+import os from 'node:os';
+import path from 'node:path';
+import fsReal from 'node:fs';
+import { spawn as spawnReal, spawnSync as spawnSyncReal } from 'node:child_process';
+import { isProcessAlive } from '../loops.mjs';
+
+export class ServiceError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'ServiceError';
+    this.code = code || 'SERVICE_ERR';
+  }
+}
+
+function xmlEscape(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// ---- pure helpers ----
+
+export function servicePaths(name, { home = os.homedir(), configDir } = {}) {
+  const cfg = configDir || path.join(home, '.lazyclaw');
+  return {
+    launchd: path.join(home, 'Library', 'LaunchAgents', `com.lazyclaw.${name}.plist`),
+    systemd: path.join(home, '.config', 'systemd', 'user', `lazyclaw-${name}.service`),
+    pidfile: path.join(cfg, `${name}.pid`),
+    logfile: path.join(cfg, `${name}.log`),
+  };
+}
+
+export function detectBackend({ platform = process.platform, hasSystemctl = false, override = null } = {}) {
+  if (override) return override;
+  if (platform === 'darwin') return 'launchd';
+  if (platform === 'linux' && hasSystemctl) return 'systemd';
+  return 'fallback';
+}
+
+export function buildLaunchdPlist({ name, execPath, args, workingDir, logfile, env = {} }) {
+  const progArgs = [execPath, ...args]
+    .map((a) => `    <string>${xmlEscape(a)}</string>`)
+    .join('\n');
+  const envBlock = Object.keys(env).length
+    ? `  <key>EnvironmentVariables</key>\n  <dict>\n` +
+      Object.entries(env).map(([k, v]) => `    <key>${xmlEscape(k)}</key><string>${xmlEscape(v)}</string>`).join('\n') +
+      `\n  </dict>\n`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.lazyclaw.${xmlEscape(name)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${progArgs}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>WorkingDirectory</key><string>${xmlEscape(workingDir)}</string>
+  <key>StandardOutPath</key><string>${xmlEscape(logfile)}</string>
+  <key>StandardErrorPath</key><string>${xmlEscape(logfile)}</string>
+${envBlock}</dict>
+</plist>
+`;
+}
+
+export function buildSystemdUnit({ description, execPath, args, workingDir, env = {} }) {
+  // systemd ExecStart wants an absolute path + a single command line. We keep
+  // the argv simple (paths/flags lazyclaw produces have no shell metachars),
+  // so a plain space-join is correct and readable.
+  const exec = [execPath, ...args].join(' ');
+  const envLines = Object.entries(env).map(([k, v]) => `Environment=${k}=${v}`).join('\n');
+  return `[Unit]
+Description=${description}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+WorkingDirectory=${workingDir}
+Restart=always
+RestartSec=3
+${envLines ? envLines + '\n' : ''}
+[Install]
+WantedBy=default.target
+`;
+}
+
+// ---- apply layer (side-effectful, injectable deps) ----
+
+function resolveDeps(deps = {}) {
+  return {
+    fs: deps.fs || fsReal,
+    spawnSync: deps.spawnSync || spawnSyncReal,
+    spawn: deps.spawn || spawnReal,
+    isAlive: deps.isAlive || isProcessAlive,
+  };
+}
+
+export function installService(spec, depsIn = {}) {
+  const { name, execPath, args, workingDir, env = {}, backend, description, home, configDir, logfile } = spec;
+  const deps = resolveDeps(depsIn);
+  const p = servicePaths(name, { home, configDir });
+  const log = logfile || p.logfile;
+
+  if (backend === 'launchd') {
+    deps.fs.mkdirSync(path.dirname(p.launchd), { recursive: true });
+    deps.fs.writeFileSync(p.launchd, buildLaunchdPlist({ name, execPath, args, workingDir, logfile: log, env }));
+    deps.spawnSync('launchctl', ['unload', p.launchd], { stdio: 'ignore' });
+    const r = deps.spawnSync('launchctl', ['load', p.launchd], { encoding: 'utf8' });
+    if (r && r.status !== 0) throw new ServiceError(`launchctl load failed: ${r.stderr || r.status}`, 'SERVICE_LAUNCHD_FAIL');
+    return { backend, target: p.launchd };
+  }
+
+  if (backend === 'systemd') {
+    deps.fs.mkdirSync(path.dirname(p.systemd), { recursive: true });
+    deps.fs.writeFileSync(p.systemd, buildSystemdUnit({ description, execPath, args, workingDir, env }));
+    deps.spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    const r = deps.spawnSync('systemctl', ['--user', 'enable', '--now', `lazyclaw-${name}.service`], { encoding: 'utf8' });
+    if (r && r.status !== 0) throw new ServiceError(`systemctl enable failed: ${r.stderr || r.status}`, 'SERVICE_SYSTEMD_FAIL');
+    return { backend, target: p.systemd };
+  }
+
+  if (backend === 'fallback') {
+    // No service manager: detach a child and record its pid. This survives
+    // the launching terminal but NOT a reboot — the caller is told so.
+    deps.fs.mkdirSync(path.dirname(p.pidfile), { recursive: true });
+    const child = deps.spawn(execPath, args, {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, ...env },
+    });
+    if (child && typeof child.unref === 'function') child.unref();
+    deps.fs.writeFileSync(p.pidfile, String(child.pid));
+    return { backend, pid: child.pid, pidfile: p.pidfile };
+  }
+
+  throw new ServiceError(`unknown service backend: ${backend}`, 'SERVICE_BAD_BACKEND');
+}
+
+export function uninstallService(spec, depsIn = {}) {
+  const { name, backend, home, configDir } = spec;
+  const deps = resolveDeps(depsIn);
+  const p = servicePaths(name, { home, configDir });
+
+  if (backend === 'launchd') {
+    if (deps.fs.existsSync(p.launchd)) {
+      deps.spawnSync('launchctl', ['unload', p.launchd], { stdio: 'ignore' });
+      deps.fs.rmSync(p.launchd);
+    }
+    return { backend, removed: p.launchd };
+  }
+  if (backend === 'systemd') {
+    deps.spawnSync('systemctl', ['--user', 'disable', '--now', `lazyclaw-${name}.service`], { stdio: 'ignore' });
+    if (deps.fs.existsSync(p.systemd)) deps.fs.rmSync(p.systemd);
+    deps.spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    return { backend, removed: p.systemd };
+  }
+  if (backend === 'fallback') {
+    let pid = null;
+    if (deps.fs.existsSync(p.pidfile)) {
+      pid = parseInt(deps.fs.readFileSync(p.pidfile, 'utf8'), 10);
+      if (Number.isFinite(pid)) { try { process.kill(pid); } catch { /* already gone */ } }
+      deps.fs.rmSync(p.pidfile);
+    }
+    return { backend, killed: pid };
+  }
+  throw new ServiceError(`unknown service backend: ${backend}`, 'SERVICE_BAD_BACKEND');
+}
+
+export function serviceStatus(spec, depsIn = {}) {
+  const { name, backend, home, configDir } = spec;
+  const deps = resolveDeps(depsIn);
+  const p = servicePaths(name, { home, configDir });
+
+  if (backend === 'launchd') {
+    return { backend, installed: deps.fs.existsSync(p.launchd), target: p.launchd };
+  }
+  if (backend === 'systemd') {
+    const installed = deps.fs.existsSync(p.systemd);
+    const r = deps.spawnSync('systemctl', ['--user', 'is-active', `lazyclaw-${name}.service`], { encoding: 'utf8' });
+    const running = !!r && typeof r.stdout === 'string' && r.stdout.trim() === 'active';
+    return { backend, installed, running, target: p.systemd };
+  }
+  if (backend === 'fallback') {
+    if (!deps.fs.existsSync(p.pidfile)) return { backend, installed: false, running: false };
+    const pid = parseInt(deps.fs.readFileSync(p.pidfile, 'utf8'), 10);
+    return { backend, installed: true, running: Number.isFinite(pid) && deps.isAlive(pid), pid: Number.isFinite(pid) ? pid : null };
+  }
+  throw new ServiceError(`unknown service backend: ${backend}`, 'SERVICE_BAD_BACKEND');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "6.0.1",
+  "version": "6.2.0",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama, orchestrating multi-step LLM workflows, and running multi-agent Slack teams with cross-task memory. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",
@@ -37,8 +37,7 @@
     "test:bench": "node scripts/bench-providers.mjs",
     "test:bench:index": "node --test tests/index_store.bench.mjs",
     "test:perf": "node --test tests/phaseH-perf.test.mjs tests/index_store.bench.mjs",
-    "migrate:v5": "node scripts/migrate-v5.mjs",
-    "build:splash": "node scripts/build-splash.mjs"
+    "migrate:v5": "node scripts/migrate-v5.mjs"
   },
   "files": [
     "cli.mjs",

package/providers/codex_cli.mjs

@@ -144,6 +144,16 @@ export const codexCliProvider = {
     const onAbort = () => { try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ } };
     if (opts.signal) opts.signal.addEventListener('abort', onAbort);
 
+    // A missing binary surfaces as an ASYNC ChildProcess 'error' event on
+    // some platforms (the sync try/catch above doesn't see it). Without a
+    // listener that's an uncaughtException that kills the WHOLE process mid
+    // `providers test` — capture it and surface a per-provider CliMissingError
+    // instead (same fix claude_cli.mjs received in F8).
+    let spawnError = null;
+    const spawnErrorPromise = new Promise((resolve) => {
+      proc.once('error', (err) => { spawnError = err; resolve(); });
+    });
+
     let stderr = '';
     proc.stderr.setEncoding('utf8');
     proc.stderr.on('data', (chunk) => { stderr += chunk; });
@@ -184,7 +194,13 @@ export const codexCliProvider = {
           if (text) yield text;
         } catch (_) { /* incomplete tail — drop */ }
       }
-      await exitPromise;
+      // Wait for either a clean exit or an async spawn error. On ENOENT the
+      // process never starts, so 'close' never fires — racing against
+      // spawnErrorPromise keeps this from hanging forever.
+      await Promise.race([exitPromise, spawnErrorPromise]);
+      if (spawnError) {
+        throw spawnError.code === 'ENOENT' ? new CliMissingError() : spawnError;
+      }
       if (exitInfo && exitInfo.code !== 0 && !opts.signal?.aborted) {
         throw new CliExitError(exitInfo.code, exitInfo.signal, stderr);
       }