lazyclaw 6.4.0 → 6.5.0

package/tui/repl_altbuffer.mjs

@@ -0,0 +1,63 @@
+// tui/repl_altbuffer.mjs — alt-buffer (DEC 1049) mount cluster for the REPL.
+//
+// Extracted verbatim from repl.mjs (file-size gate). Wraps the React tree
+// with mount/unmount side-effects that enable the terminal alternate screen
+// buffer. Three-layer cleanup so the user never gets stranded on the alt
+// canvas:
+//   1. React unmount → useEffect return-fn writes \x1b[?1049l
+//   2. Rude shutdown (SIGINT/SIGTERM/SIGHUP/'exit') → same escape via
+//      process-level listeners that we install + remove on unmount.
+//   3. cursor-visible safety on unmount (\x1b[?25h) in case anything
+//      below us turned it off.
+//
+// We deliberately do NOT install an uncaughtException handler — Ink
+// already installs one and re-throws; ours would swallow the stack
+// trace (violates §1 Truthfulness / no silent catch).
+//
+// `enabled` is false for non-TTY pipelines, CI, ink-testing-library, and
+// the LAZYCLAW_NO_ALT escape hatch. When false this is a pass-through —
+// no escape sequences leak into stdout.
+import { useEffect } from 'react';
+
+export const ALT_BUFFER_ENTER = '\x1b[?1049h';
+export const ALT_BUFFER_LEAVE = '\x1b[?1049l';
+export const CURSOR_VISIBLE   = '\x1b[?25h';
+
+// Rendering-mode decision. Default = Static scrollback (no flicker; splash
+// prints once + scrolls naturally). Alt-buffer fullscreen is opt-in via
+// LAZYCLAW_ALT=1; LAZYCLAW_NO_ALT=1 forces it off. TTY-only either way.
+export function computeAltEnabled(env, hasTTY) {
+  const e = env || {};
+  return !!hasTTY && !!e.LAZYCLAW_ALT && !e.LAZYCLAW_NO_ALT;
+}
+
+export function FullScreen({ enabled, children }) {
+  useEffect(() => {
+    if (!enabled) return undefined;
+    // Mount: enter alternate screen buffer.
+    try { process.stdout.write(ALT_BUFFER_ENTER); } catch { /* swallow — stdout closed */ }
+
+    // Rude-shutdown listeners. Each writes 1049l + cursor-visible so the
+    // terminal is restored even if React never gets a chance to unmount
+    // (e.g. parent process kills us with SIGTERM).
+    const restore = () => {
+      try { process.stdout.write(ALT_BUFFER_LEAVE + CURSOR_VISIBLE); } catch {}
+    };
+    const onExit = () => { restore(); };
+    const onSignal = () => { restore(); };
+    process.once('exit', onExit);
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    process.once('SIGHUP', onSignal);
+
+    return () => {
+      // React unmount: restore primary buffer.
+      restore();
+      process.removeListener('exit', onExit);
+      process.removeListener('SIGINT', onSignal);
+      process.removeListener('SIGTERM', onSignal);
+      process.removeListener('SIGHUP', onSignal);
+    };
+  }, [enabled]);
+  return children;
+}

package/tui/repl_reducers.mjs

@@ -0,0 +1,114 @@
+// tui/repl_reducers.mjs — pure state reducers for the REPL host.
+//
+// Extracted verbatim from repl.mjs (file-size gate). These are pure
+// functions: no shared mutable module state, no JSX. They keep their
+// pre-v5.3 shapes — tests/phaseC-repl-interrupt.test.mjs depends on them.
+//
+// Backward-compat contracts (do not break):
+//   - makeReplState()              — still callable with zero args.
+//   - onUserInput, onEscape, onTurnComplete, consumeNextTurnFirstMessage
+//     keep their pre-v5.3 shapes.
+
+// ─── Pure state ──────────────────────────────────────────────────────────
+//
+// makeReplState stays callable with zero args (existing tests rely on it).
+// The new fields default to empty so legacy callers see no behavior change.
+export function makeReplState(opts) {
+  const splashItem = opts && opts.splashItem ? opts.splashItem : null;
+  return {
+    streaming: false,
+    controller: null,
+    pendingPrepend: null,
+    nextTurnFirstMessage: null,
+    history: [],
+    scrollback: splashItem ? [splashItem] : [],
+    liveAssistant: '',
+    turnCounter: 0,
+  };
+}
+
+export function onUserInput(state, { text, controller }) {
+  if (state.streaming && state.controller) {
+    // mid-stream interrupt — abort current turn, queue text for next turn.
+    try { state.controller.abort(); } catch {}
+    return { ...state, pendingPrepend: text };
+  }
+  // idle — start a new turn. Append a 'user' entry to scrollback so the
+  // sticky-layout caller sees the prompt history above the live stream.
+  const id = `u-${state.turnCounter}`;
+  return {
+    ...state,
+    streaming: true,
+    controller,
+    history: [...state.history, text],
+    scrollback: [...state.scrollback, { kind: 'user', id, text }],
+    turnCounter: state.turnCounter + 1,
+  };
+}
+
+export function onEscape(state) {
+  if (state.streaming && state.controller) {
+    try { state.controller.abort(); } catch {}
+  }
+  // Drop any partial live assistant text on explicit Esc — the user is
+  // telling us to discard, not to keep.
+  return {
+    ...state,
+    streaming: false,
+    controller: null,
+    pendingPrepend: null,
+    liveAssistant: '',
+  };
+}
+
+// Stream chunk arrives. Completed lines are committed to the <Static>
+// scrollback immediately (so they scroll up ABOVE the sticky editor), and only
+// the in-progress trailing partial stays in the live region. Without this, a
+// reply taller than the terminal grew the live frame past the viewport and
+// spilled BELOW the input box (long orchestrator replies). Chunks without a
+// newline still just accumulate (the prior behaviour), so short replies and the
+// existing reducer tests are unchanged.
+export function onStreamChunk(state, { chunk }) {
+  const buf = state.liveAssistant + chunk;
+  const nl = buf.lastIndexOf('\n');
+  if (nl < 0) return { ...state, liveAssistant: buf };
+  const complete = buf.slice(0, nl);          // one or more whole lines
+  const remainder = buf.slice(nl + 1);        // trailing partial (may be '')
+  const id = `as-${state.turnCounter}-${state.scrollback.length}`;
+  return {
+    ...state,
+    scrollback: [...state.scrollback, { kind: 'assistant', id, text: complete }],
+    liveAssistant: remainder,
+  };
+}
+
+export function onTurnComplete(state, { reason, error } = {}) {
+  const promoted = state.pendingPrepend;
+  const suffix = reason === 'aborted' ? ' [aborted]'
+              : reason === 'error'   ? (error ? ` [error: ${error}]` : ' [error]')
+              : '';
+  const text = (state.liveAssistant || '') + suffix;
+  // Commit any accumulated live text to scrollback. If the turn produced
+  // nothing AND wasn't an error/abort, skip the empty append.
+  const shouldCommit = text.length > 0 && (state.liveAssistant.length > 0 || suffix.length > 0);
+  const id = `a-${state.turnCounter}`;
+  const kind = reason === 'error' ? 'error' : 'assistant';
+  const nextScrollback = shouldCommit
+    ? [...state.scrollback, { kind, id, text }]
+    : state.scrollback;
+  return {
+    ...state,
+    streaming: false,
+    controller: null,
+    pendingPrepend: null,
+    nextTurnFirstMessage: promoted,
+    liveAssistant: '',
+    scrollback: nextScrollback,
+    turnCounter: state.turnCounter + 1,
+  };
+}
+
+export function consumeNextTurnFirstMessage(state) {
+  const msg = state.nextTurnFirstMessage;
+  return [{ ...state, nextTurnFirstMessage: null }, msg];
+}

package/tui/slash_channels.mjs

@@ -0,0 +1,208 @@
+// tui/slash_channels.mjs — the /channels and /context slash-command handlers,
+// extracted verbatim from slash_dispatcher.mjs. Imports the shared masked-prompt
+// helper from slash_helpers.mjs and the dotenv shim from a leaf lib, never the
+// dispatcher (no cycle).
+
+import { loadDotenvIfAny } from '../dotenv_min.mjs';
+import { _promptText } from './slash_helpers.mjs';
+
+// /channels — view configured channels and toggle them. `/channels` lists;
+// `/channels <name> on|off` enables/disables. Reads/writes cfg via ctx when
+// available, else lib/config directly, so it works on both REPL paths.
+export async function _channels(args, ctx = {}) {
+  const cf = await import('../config_features.mjs');
+  const cfgMod = await import('../lib/config.mjs');
+  const read = typeof ctx.readConfig === 'function' ? ctx.readConfig : cfgMod.readConfig;
+  const write = typeof ctx.writeConfig === 'function' ? ctx.writeConfig : cfgMod.writeConfig;
+  const toks = (args || '').trim().split(/\s+/).filter(Boolean);
+  const [name, action] = toks;
+
+  // `/channels [<name>] setup` — set the channel's credentials (bot token,
+  // homeserver, …) from chat instead of redirecting to /config. Reuses the
+  // masked modal prompt (_promptText) so secrets are never echoed. No modal →
+  // fall back to the readline channel step (same as /config's channel item).
+  const wantSetup = toks.some((t) => /^setup$/i.test(t));
+  if (wantSetup) {
+    const channelMod = await import('../commands/setup_channels.mjs');
+    const picked = toks.find((t) => !/^setup$/i.test(t));
+    if (typeof ctx.openPicker !== 'function') {
+      // Readline path: hand off to the existing channel wizard step.
+      ctx.requestConfigStep = 'channel';
+      return 'EXIT';
+    }
+    let chName = picked && picked.toLowerCase();
+    if (!chName) {
+      const sel = await ctx.openPicker({
+        kind: 'menu',
+        title: 'channel — set credentials',
+        subtitle: 'pick a channel to configure',
+        items: channelMod.CHANNEL_CATALOG.map((c) => ({
+          id: c.name,
+          label: c.label,
+          desc: c.builtin ? '' : `needs: ${(c.deps && c.deps.length) ? c.deps.join(', ') : (c.binary || 'creds only')}`,
+        })),
+      });
+      chName = sel && typeof sel === 'object' ? sel.id : sel;
+      if (!chName || typeof chName !== 'string') return 'channel setup: cancelled';
+    }
+    const spec = channelMod.channelByName(chName);
+    if (!spec) return `unknown channel: ${chName} (known: ${cf.KNOWN_CHANNELS.join(', ')})`;
+    if (!spec.fields.length) {
+      // No creds (e.g. http / whatsapp) — just enable it.
+      const cfgDirX = ctx.cfgDir || (await import('node:path')).dirname(cfgMod.configPath());
+      channelMod.persistChannel(cfgDirX, chName, {});
+      if (ctx.cfg) { ctx.cfg.channels = ctx.cfg.channels || {}; ctx.cfg.channels[chName] = { ...(ctx.cfg.channels[chName] || {}), enabled: true }; }
+      return `channel ${chName} → enabled (no credentials needed)`;
+    }
+    const answers = {};
+    for (const f of spec.fields) {
+      const v = await _promptText(ctx, {
+        title: `${spec.label} — ${f.prompt}`,
+        subtitle: f.optional ? 'optional · Esc to skip' : 'Esc cancels',
+        secret: !!f.secret,
+        allowEmpty: !!f.optional,
+      });
+      if (v === null) {
+        if (f.optional) continue;       // Esc on an optional field → skip it
+        return 'channel setup: cancelled';
+      }
+      if (v) answers[f.key] = v;
+    }
+    const path = await import('node:path');
+    const cfgDirX = ctx.cfgDir || path.dirname(cfgMod.configPath());
+    const entry = channelMod.persistChannel(cfgDirX, chName, answers);
+    // Mirror the PERSISTED enabled state onto the in-session cfg so a follow-up
+    // list is fresh — an in-tree channel whose runtime dep is missing stays
+    // disabled (persistChannel gates it) rather than being force-enabled.
+    if (ctx.cfg) { ctx.cfg.channels = ctx.cfg.channels || {}; ctx.cfg.channels[chName] = { ...(ctx.cfg.channels[chName] || {}), enabled: !!entry.ready }; }
+    const setKeys = Object.keys(answers);
+    let note = '';
+    if (!entry.ready) {
+      if (entry.missingDeps && entry.missingDeps.length) note += `\n(needs ${entry.missingDeps.join(', ')} — run: lazyclaw channels install ${chName})`;
+      if (entry.missingBinary) note += `\n(needs the ${entry.missingBinary} binary on your PATH)`;
+    }
+    return `✓ ${spec.label} credentials saved (${setKeys.join(', ') || 'none'}) → ${entry.ready ? 'channel enabled' : 'saved (enable once the requirement is installed)'}${note}`;
+  }
+
+  // `/channels <name> test` — verify the stored credentials with a live call.
+  if (name && /^test$/i.test(action || '')) {
+    const channelMod = await import('../commands/setup_channels.mjs');
+    try { loadDotenvIfAny(ctx.cfgDir); } catch { /* best-effort */ }
+    const r = await channelMod.verifyChannel(name.toLowerCase());
+    if (r.ok === true) return `✓ ${name} verified — ${r.detail}`;
+    if (r.ok === null) return `· ${name}: ${r.detail}`;
+    return `✗ ${name}: ${r.detail}${r.hint ? `\n  fix: ${r.hint}` : ''}`;
+  }
+
+  if (name && /^(on|off|enable|disable)$/i.test(action || '')) {
+    const en = /^(on|enable)$/i.test(action);
+    const cfg = read();
+    const key = name.toLowerCase();
+    // Reject unknown names so a typo can't silently create a bogus
+    // cfg.channels.<name> section (which would then leak into the list).
+    // Stay permissive for pre-existing custom sections.
+    const existing = (cfg.channels && typeof cfg.channels === 'object') ? cfg.channels : {};
+    if (!cf.KNOWN_CHANNELS.includes(key) && !(key in existing)) {
+      return `unknown channel: ${key} (known: ${cf.KNOWN_CHANNELS.join(', ')})`;
+    }
+    cf.channelSetEnabled(cfg, key, en); write(cfg);
+    // Legacy fallback path: the readline ctx (_legacyCtx) has no
+    // readConfig/writeConfig, so we read/wrote disk above against a fresh
+    // cfg object. Mirror the toggle onto the in-session ctx.cfg so a
+    // follow-up `/channels` (list) or other in-session read stays
+    // consistent instead of showing the stale pre-toggle value.
+    if (ctx.cfg && ctx.cfg !== cfg && typeof ctx.cfg === 'object') {
+      cf.channelSetEnabled(ctx.cfg, key, en);
+    }
+    return en
+      ? `channel ${key} → enabled`
+      : `channel ${key} → disabled (re-enable with /channels ${key} on)`;
+  }
+  // No-arg + modal → an action menu: each row toggles in place, plus a
+  // "set credentials" row. Falls through to the text list when no modal.
+  if (!toks.length && typeof ctx.openPicker === 'function') {
+    const statusRows = cf.channelStatusList(read());
+    const items = statusRows.map((c) => ({
+      id: `toggle:${c.name}`,
+      label: `${c.name} — ${c.enabled ? 'enabled' : 'disabled'}`,
+      desc: c.enabled ? 'Enter to disable' : 'Enter to enable',
+    }));
+    items.push({ id: 'setup', label: '+ Set credentials…', desc: 'pick a channel and enter bot token / homeserver / …' });
+    const picked = await ctx.openPicker({ kind: 'menu', title: 'Channels', subtitle: `${statusRows.length} configured`, items });
+    const pid = picked && typeof picked === 'object' ? picked.id : picked;
+    if (!pid || typeof pid !== 'string') return 'cancelled';
+    if (pid === 'setup') return _channels('setup', ctx);
+    if (pid.startsWith('toggle:')) {
+      const nm = pid.slice(7);
+      const cur = statusRows.find((r) => r.name === nm);
+      return _channels(`${nm} ${cur && cur.enabled ? 'off' : 'on'}`, ctx);
+    }
+  }
+  const rows = cf.channelStatusList(read());
+  if (!rows.length) return 'no channels configured. set credentials with /channels setup (or `lazyclaw setup` for the full wizard).';
+  // Cross-reference each channel's required env creds against the loaded env so
+  // the list flags a channel that's "enabled" but missing its token.
+  let channelMod = null;
+  try {
+    loadDotenvIfAny(ctx.cfgDir);
+    channelMod = await import('../commands/setup_channels.mjs');
+  } catch { /* hint is best-effort */ }
+  const missingFor = (name) => {
+    const spec = channelMod && channelMod.channelByName(name);
+    if (!spec) return [];
+    return spec.fields.filter((f) => !f.optional && !process.env[f.env]).map((f) => f.env);
+  };
+  const lines = ['configured channels:'];
+  for (const c of rows) {
+    const miss = missingFor(c.name);
+    const credNote = miss.length ? ` · creds: missing ${miss.join(', ')}` : '';
+    lines.push(`  ${c.name}  ${c.enabled ? 'enabled' : 'disabled'}${c.boundAgent ? ' · agent: ' + c.boundAgent : ''}${credNote}`);
+  }
+  lines.push('toggle: /channels <name> on|off   ·   set creds: /channels <name> setup');
+  return lines.join('\n');
+}
+
+// /context — view/set the chat history window (turns + token budget). This is
+// the sliding history budget sent each turn, NOT the model's hard context
+// limit. ctx-or-lib/config fallback so it works on both REPL paths.
+export async function _context(args, ctx = {}) {
+  const cf = await import('../config_features.mjs');
+  const cfgMod = await import('../lib/config.mjs');
+  const read = typeof ctx.readConfig === 'function' ? ctx.readConfig : cfgMod.readConfig;
+  const write = typeof ctx.writeConfig === 'function' ? ctx.writeConfig : cfgMod.writeConfig;
+  const persist = (cfg) => { write(cfg); if (ctx.cfg) ctx.cfg = cfg; };
+  const parts = (args || '').trim().split(/\s+/).filter(Boolean);
+  const sub = (parts[0] || 'status').toLowerCase();
+  const fmt = () => { const w = cf.chatWindowGet(read()); return `context window: ${w.turns} turns · ${w.tokens} tokens  (history budget — not the model's hard limit)`; };
+  // No-arg + modal → action menu → numeric picker (mirrors orchestrator maxsubtasks).
+  if (!parts.length && typeof ctx.openPicker === 'function') {
+    const w = cf.chatWindowGet(read());
+    const action = await ctx.openPicker({
+      kind: 'menu', title: 'Context window (history budget)', subtitle: `now ${w.turns} turns · ${w.tokens} tokens`,
+      items: [
+        { id: 'turns', label: 'Set turns…', desc: 'past turns to send' },
+        { id: 'tokens', label: 'Set tokens…', desc: 'token budget (min 256)' },
+        { id: 'status', label: 'Status', desc: 'show current' },
+      ],
+    });
+    const aid = action && typeof action === 'object' ? action.id : action;
+    if (!aid || typeof aid !== 'string' || aid === 'status') return fmt();
+    if (aid === 'turns') {
+      const np = await ctx.openPicker({ kind: 'menu', title: 'Turns to keep', subtitle: `currently ${w.turns}`, items: [5, 10, 15, 20, 30, 40, 50].map((x) => ({ id: String(x), label: String(x) })) });
+      const v = parseInt(np && typeof np === 'object' ? np.id : np, 10);
+      if (!Number.isFinite(v)) return 'context turns: cancelled';
+      const cfg = read(); cf.chatWindowSet(cfg, { turns: v }); persist(cfg); return fmt();
+    }
+    if (aid === 'tokens') {
+      const np = await ctx.openPicker({ kind: 'menu', title: 'Token budget', subtitle: `currently ${w.tokens}`, items: [2000, 4000, 8000, 12000, 16000, 32000].map((x) => ({ id: String(x), label: String(x) })) });
+      const v = parseInt(np && typeof np === 'object' ? np.id : np, 10);
+      if (!Number.isFinite(v) || v < 256) return 'context tokens: cancelled';
+      const cfg = read(); cf.chatWindowSet(cfg, { tokens: v }); persist(cfg); return fmt();
+    }
+  }
+  if (sub === 'status') return fmt();
+  const n = parseInt(parts[1], 10);
+  if (sub === 'turns') { if (!Number.isFinite(n) || n < 1) return 'usage: /context turns <N>'; const cfg = read(); cf.chatWindowSet(cfg, { turns: n }); persist(cfg); return fmt(); }
+  if (sub === 'tokens') { if (!Number.isFinite(n) || n < 256) return 'usage: /context tokens <N>  (min 256)'; const cfg = read(); cf.chatWindowSet(cfg, { tokens: n }); persist(cfg); return fmt(); }
+  return 'usage: /context [status | turns <N> | tokens <N>]';
+}

package/tui/slash_dashboard.mjs

@@ -0,0 +1,220 @@
+// tui/slash_dashboard.mjs — the /dashboard slash-command cluster, extracted
+// verbatim from slash_dispatcher.mjs. Self-contained leaf with its own
+// encapsulated module state (_dashboardSpawning / _dashboardChildPid). Imports
+// only the shared leaf helpers, never the dispatcher (no cycle).
+
+import { splitWhitespace } from './slash_helpers.mjs';
+
+// /dashboard — open the lazyclaw web UI.
+//
+// v5.4.4 ROOT-CAUSE FIX (was: rapid repeated /dashboard within one chat
+// session spawned 20+ daemon children).
+//
+// Original implementation:
+//   probe /healthz → if !200, spawn detached `lazyclaw dashboard
+//   --no-open` and poll for up to 3s.
+//
+// Failure mode that produced the 20+ spawn pile-up:
+//   1. User types /dashboard. probe fails (no daemon). Spawn child A.
+//   2. Child A begins binding port 19600. Takes ~500ms-2s to be ready.
+//   3. User types /dashboard again BEFORE A is ready. probe still fails.
+//      Spawn child B. Child B sees EADDRINUSE and calls _killPortOccupant
+//      (cli.mjs:3611) which SIGTERMs child A. B takes over.
+//   4. Repeat. Each /dashboard kills the previous daemon and starts a
+//      new one. With autorepeat / many slash calls this stacks fast.
+//
+// Two-layer guard:
+//   - A module-level _dashboardSpawning latch refuses concurrent spawn
+//     attempts. While a spawn is in flight, /dashboard says so + returns
+//     without firing another child.
+//   - A _dashboardChildPid cache remembers the PID we already spawned;
+//     subsequent calls check kill(pid, 0) to confirm the child is alive
+//     and just open the browser without spawning.
+//
+// We probe both /healthz (HTTP) AND a raw net.connect port check so a
+// slow-starting daemon (binding the listener but not yet answering HTTP)
+// still counts as "running".
+let _dashboardSpawning = false;
+let _dashboardChildPid = null;
+
+function _portIsListening(port, timeoutMs = 200) {
+  return new Promise((resolve) => {
+    import('node:net').then(({ createConnection }) => {
+      let settled = false;
+      const sock = createConnection({ host: '127.0.0.1', port });
+      const done = (ok) => {
+        if (settled) return;
+        settled = true;
+        try { sock.destroy(); } catch {}
+        resolve(ok);
+      };
+      sock.once('connect', () => done(true));
+      sock.once('error', () => done(false));
+      setTimeout(() => done(false), timeoutMs);
+    }).catch(() => resolve(false));
+  });
+}
+
+async function _dashboardProbe(port) {
+  // Fast path — port-level probe. Catches a daemon that has bound the
+  // socket but hasn't finished initializing its HTTP routes.
+  if (await _portIsListening(port, 200)) return true;
+  // Slow path — full /healthz fetch, for defense in depth.
+  if (typeof fetch !== 'function') return false;
+  try {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), 250);
+    const r = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: ac.signal });
+    clearTimeout(t);
+    return !!(r && r.ok);
+  } catch { return false; }
+}
+
+function _openBrowser(url) {
+  return import('node:child_process').then(({ spawn }) => {
+    let cmd, args;
+    if (process.platform === 'darwin')      { cmd = 'open';     args = [url]; }
+    else if (process.platform === 'win32')  { cmd = 'cmd';      args = ['/c', 'start', '""', url]; }
+    else                                    { cmd = 'xdg-open'; args = [url]; }
+    try { spawn(cmd, args, { stdio: 'ignore', detached: true }).unref(); } catch { /* swallow */ }
+  });
+}
+
+async function _dashboardStop(port) {
+  // Best-effort kill of every lazyclaw dashboard daemon on the box.
+  // Used to clean up after the v5.4.3 spawn pile-up bug.
+  if (process.platform === 'win32') {
+    return 'dashboard stop: not implemented on Windows yet — kill via Task Manager';
+  }
+  const { spawn } = await import('node:child_process');
+  // Step 1: lsof the port and SIGTERM each PID.
+  const portPids = await new Promise((resolve) => {
+    try {
+      const lsof = spawn('lsof', ['-ti', `tcp:${port}`], { stdio: ['ignore', 'pipe', 'ignore'] });
+      let buf = '';
+      lsof.stdout.on('data', (d) => { buf += d.toString('utf8'); });
+      lsof.on('error', () => resolve([]));
+      lsof.on('close', () => resolve(
+        buf.trim().split(/\s+/).map((s) => parseInt(s, 10)).filter(Number.isFinite)
+      ));
+    } catch { resolve([]); }
+  });
+  for (const pid of portPids) {
+    try { process.kill(pid, 'SIGTERM'); } catch { /* gone */ }
+  }
+  // Step 2: pkill any process whose command line includes "lazyclaw dashboard"
+  // — catches detached children that bound a different (random) port via
+  // cmdDashboard's EADDRINUSE fallback.
+  let pkilled = 0;
+  try {
+    const pkill = spawn('pkill', ['-f', 'lazyclaw dashboard'], { stdio: ['ignore', 'ignore', 'ignore'] });
+    pkilled = await new Promise((r) => pkill.on('close', (code) => r(code === 0 ? 1 : 0)));
+  } catch { /* fine */ }
+  _dashboardChildPid = null;
+  return `✓ stopped ${portPids.length} listener(s) on :${port}${pkilled ? ' + remaining `lazyclaw dashboard` processes via pkill' : ''}`;
+}
+
+// Parse the daemon's "listening at <url>" stdout line so /dashboard opens the
+// actually-bound port (the child may fall back to a random port on EADDRINUSE).
+export function parseDashboardUrl(text) {
+  const m = String(text || '').match(/listening at\s+(https?:\/\/\S+)/i);
+  return m ? m[1] : null;
+}
+
+// Resolve the daemon's real URL from its stdout within `timeoutMs`, or null.
+function _waitForDashboardUrl(child, timeoutMs) {
+  return new Promise((resolve) => {
+    if (!child || !child.stdout) { resolve(null); return; }
+    let buf = '';
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      try { child.stdout.off('data', onData); } catch { /* ignore */ }
+      resolve(v);
+    };
+    const onData = (d) => {
+      buf += d.toString('utf8');
+      const u = parseDashboardUrl(buf);
+      if (u) finish(u);
+    };
+    child.stdout.on('data', onData);
+    setTimeout(() => finish(null), timeoutMs);
+  });
+}
+
+export async function _dashboard(args) {
+  const port = 19600;
+  const url = `http://127.0.0.1:${port}/dashboard`;
+  // Under the node:test runner, never launch a real daemon or open a browser
+  // (it leaked a background daemon + opened a tab on every test run).
+  if (process.env.NODE_TEST_CONTEXT) return `dashboard: ${url} (spawn skipped under test)`;
+  const sub = splitWhitespace(args)[0];
+  if (sub === 'stop' || sub === 'kill') return _dashboardStop(port);
+
+  // 1. Already running anywhere on the machine? → reuse.
+  if (await _dashboardProbe(port)) {
+    await _openBrowser(url);
+    return `✓ dashboard already running — opened ${url}`;
+  }
+
+  // 2. We spawned in this chat — is that child still alive?
+  if (_dashboardChildPid != null) {
+    try {
+      process.kill(_dashboardChildPid, 0); // signal 0 = liveness probe
+      // Child alive but not answering yet. Don't re-spawn; just nudge.
+      await _openBrowser(url);
+      return `✓ dashboard starting (pid ${_dashboardChildPid}) — opened ${url}`;
+    } catch {
+      _dashboardChildPid = null; // child died; fall through and respawn.
+    }
+  }
+
+  // 3. Spawn already in flight from a concurrent /dashboard? Don't pile on.
+  if (_dashboardSpawning) {
+    await _openBrowser(url);
+    return `dashboard is still booting — opened ${url}; try again in a moment if it didn't load`;
+  }
+
+  // 4. Cold start. Spawn ONE detached child, poll up to 3s, latch the
+  //    spawn flag in a finally so it always clears.
+  _dashboardSpawning = true;
+  try {
+    const { spawn } = await import('node:child_process');
+    let child;
+    try {
+      // Pass --port so the child tries 19600 first; pipe stdout so we can read
+      // the real bound URL (it may fall back to a random port on EADDRINUSE).
+      child = spawn(process.execPath, [process.argv[1], 'dashboard', '--port', String(port), '--no-open'], {
+        detached: true, stdio: ['ignore', 'pipe', 'ignore'], cwd: process.cwd(), env: process.env,
+      });
+      _dashboardChildPid = child.pid;
+    } catch (e) {
+      return `dashboard error: failed to spawn — ${e?.message || e}`;
+    }
+    // Prefer the daemon's own "listening at <url>" line — it carries the
+    // actual port even after a random-port fallback.
+    const boundUrl = await _waitForDashboardUrl(child, 3000);
+    // Release the captured stdout pipe so the detached daemon doesn't keep
+    // OUR event loop alive (unref, not destroy — destroying would EPIPE the
+    // daemon on its next stdout write). Then unref the child itself.
+    try { if (child.stdout) { child.stdout.removeAllListeners('data'); child.stdout.unref(); } } catch { /* ignore */ }
+    child.unref();
+    if (boundUrl) {
+      await _openBrowser(boundUrl);
+      return `✓ started dashboard (pid ${child.pid}) — opened ${boundUrl}`;
+    }
+    // Fallback: the line never arrived — poll the default port best-effort.
+    const start = Date.now();
+    while (Date.now() - start < 1500) {
+      if (await _dashboardProbe(port)) {
+        await _openBrowser(url);
+        return `✓ started dashboard (pid ${child.pid}) — opened ${url}`;
+      }
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    return `⚠ dashboard didn't come up within 3s (pid ${child.pid}). URL: ${url}`;
+  } finally {
+    _dashboardSpawning = false;
+  }
+}