lazyclaw 6.3.1 → 6.5.0

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_commands.mjs

@@ -21,25 +21,27 @@ export const SLASH_COMMANDS = [
   { cmd: '/skill',       help: 'switch active skills: /skill review,style (no arg → clear)' },
   { cmd: '/tools',       help: 'list available tool registry verbs' },
   { cmd: '/provider',    help: 'pick provider from a list (or pass a name: /provider openai)' },
+  { cmd: '/login',       help: 'connect a keyless CLI provider (codex-cli / gemini-cli): browser, API key, or install' },
   { cmd: '/model',       help: 'pick a model from a list (or pass a name: /model gpt-4.1)' },
+  { cmd: '/hud',         help: 'toggle the HUD status row (usage · models · cost): /hud on|off' },
   { cmd: '/trainer',     help: 'view or set trainer provider/model: /trainer show|set <p:m>|clear' },
   { cmd: '/personality', help: 'pick a personality (or sub: list|show|install|remove|use)' },
   { cmd: '/dashboard',   help: 'open the lazyclaw web UI in your browser' },
   { cmd: '/menu',        help: 'browse the full subcommand catalog (command palette)' },
   { cmd: '/setup',       help: 'first-run / full re-setup: leave chat and run every wizard step' },
   { cmd: '/config',      help: 'change ONE setting: provider, model, context, channel creds, webhook, …' },
-  { cmd: '/channels',    help: 'view configured channels; /channels <name> on|off to toggle' },
+  { cmd: '/channels',    help: 'channels: list · <name> on|off · <name> setup (set bot token / creds)' },
   { cmd: '/orchestrator', help: 'multi-agent: status | on | off | planner <spec> | worker add|remove <spec>' },
   { cmd: '/context',      help: 'chat history window: status | turns <N> | tokens <N>' },
-  { cmd: '/loop',        help: 'repeat one prompt: /loop "fix lint" [--max N] [--until "<regex>"]' },
+  { cmd: '/loop',        help: 'repeat one prompt: /loop "fix lint" [--max N] [--until "<regex>"] [--use-memory] [--recall "<q>"]' },
   { cmd: '/goal',        help: 'register/switch goal: /goal add NAME | /goal list' },
   { cmd: '/memory',      help: 'show layered memory: /memory [core|recent|episodic [topic]]' },
   { cmd: '/recall',      help: 'FTS5 recall across sessions and memory' },
   { cmd: '/dream',       help: 'consolidate recent memory into per-topic episodic files' },
-  { cmd: '/agent',       help: 'spawn or switch agent: /agent NAME' },
-  { cmd: '/team',        help: 'list, create, or join a team' },
+  { cmd: '/agent',       help: 'agents: list · show <name> · add <name> [role] · edit <name> · remove <name>' },
+  { cmd: '/team',        help: 'teams: list · show <name> · add <name> --agents a,b [--lead a] · remove <name>' },
   { cmd: '/task',        help: 'multi-agent tasks: start/tick/list/show/transcript/abandon/done/remove' },
-  { cmd: '/handoff',     help: 'hand current task off to another agent' },
+  { cmd: '/handoff',     help: 'move the current channel thread to another channel: /handoff <target-channel> <externalId> [--note=…]' },
   { cmd: '/exit',        help: 'leave the chat' },
   { cmd: '/quit',        help: 'alias for /exit' },
 ];

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;
+  }
+}