lazyclaw 5.4.4 → 6.0.1

package/commands/config.mjs

@@ -0,0 +1,315 @@
+// Configuration + diagnostics commands: personality, config get/set/edit/
+// validate, doctor, status, version, completion. Extracted from cli.mjs (D3).
+import path from 'node:path';
+import fs from 'node:fs';
+import { configPath, readConfig, writeConfig, readVersionFromRepo } from '../lib/config.mjs';
+import { ensureRegistry, getRegistry } from '../lib/registry_boot.mjs';
+import { bashCompletion, zshCompletion } from '../lib/args.mjs';
+import { defaultConfigDir as _persDefaultCfg } from '../memory.mjs';
+
+export async function cmdPersonality(sub, a, b) {
+  const cfgDir = process.env.LAZYCLAW_CONFIG_DIR || _persDefaultCfg();
+  const dir = path.join(cfgDir, 'personalities');
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (!sub || sub === 'list') {
+    const names = fs.existsSync(dir)
+      ? fs.readdirSync(dir).filter(f => f.endsWith('.md')).map(f => f.slice(0, -3))
+      : [];
+    if (!names.length) { console.log('No personalities installed'); return 0; }
+    for (const n of names.sort()) console.log(n);
+    return 0;
+  }
+
+  if (sub === 'show') {
+    if (!a) { console.error('Usage: lazyclaw personality show <name>'); return 2; }
+    const p = path.join(dir, `${a}.md`);
+    if (!fs.existsSync(p)) { console.error(`personality not found: ${a}`); return 1; }
+    process.stdout.write(fs.readFileSync(p, 'utf8'));
+    return 0;
+  }
+
+  if (sub === 'install') {
+    if (!a || !b) { console.error('Usage: lazyclaw personality install <name> <file>'); return 2; }
+    const dst = path.join(dir, `${a}.md`);
+    if (fs.existsSync(dst)) { console.error(`personality already installed: ${a}`); return 1; }
+    if (!fs.existsSync(b)) { console.error(`source file not found: ${b}`); return 1; }
+    fs.writeFileSync(dst, fs.readFileSync(b, 'utf8'));
+    console.log(`installed ${a}`);
+    return 0;
+  }
+
+  if (sub === 'remove') {
+    if (!a) { console.error('Usage: lazyclaw personality remove <name>'); return 2; }
+    const p = path.join(dir, `${a}.md`);
+    if (!fs.existsSync(p)) { console.error(`personality not installed: ${a}`); return 1; }
+    fs.unlinkSync(p);
+    console.log(`removed ${a}`);
+    return 0;
+  }
+
+  if (sub === 'use') {
+    if (!a) { console.error('Usage: lazyclaw personality use <name>'); return 2; }
+    const p = path.join(dir, `${a}.md`);
+    if (!fs.existsSync(p)) { console.error(`personality not installed: ${a}`); return 1; }
+    const cfgPath = path.join(cfgDir, 'config.json');
+    let cfg = {};
+    try { cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); } catch {}
+    cfg.persona = { ...(cfg.persona || {}), personality: a };
+    fs.mkdirSync(cfgDir, { recursive: true });
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+    console.log(`active personality: ${a}`);
+    return 0;
+  }
+
+  console.error(`Unknown personality subcommand: ${sub}`);
+  return 2;
+}
+
+export async function cmdConfigEdit() {
+  // Open config.json in $EDITOR (or sensible default), then validate
+  // the result before letting the user walk away believing the edit
+  // landed. A bad JSON syntax error here would silently break every
+  // future invocation, so we re-parse the file post-edit and refuse
+  // to leave it broken.
+  const p = configPath();
+  // Ensure the file exists with at least an empty object so $EDITOR
+  // doesn't open a blank scratch buffer the user accidentally saves
+  // as nothing.
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  if (!fs.existsSync(p)) fs.writeFileSync(p, '{}\n');
+  const editor = process.env.LAZYCLAW_EDITOR || process.env.VISUAL || process.env.EDITOR || 'vi';
+  const { spawn } = await import('node:child_process');
+  await new Promise((resolve, reject) => {
+    const child = spawn(editor, [p], { stdio: 'inherit' });
+    child.on('exit', code => {
+      if (code === 0) resolve();
+      else reject(new Error(`editor exited ${code}`));
+    });
+    child.on('error', reject);
+  });
+  // Validate the result. If JSON.parse throws, restore from a backup
+  // we made before the edit (the original content if the file existed,
+  // or an empty {} otherwise — the file always has SOME valid JSON).
+  try {
+    const txt = fs.readFileSync(p, 'utf8');
+    JSON.parse(txt);
+    console.log(JSON.stringify({ ok: true, path: p }));
+  } catch (e) {
+    console.error(`config: edit produced invalid JSON: ${e.message}`);
+    console.error(`Re-run \`lazyclaw config edit\` to fix; nothing else has been touched.`);
+    process.exit(1);
+  }
+}
+
+export function cmdConfigSet(key, value) {
+  const cfg = readConfig();
+  cfg[key] = value;
+  writeConfig(cfg);
+  console.log(JSON.stringify({ ok: true, key, value }));
+}
+export async function cmdDoctor() {
+  await ensureRegistry();
+  const cfg = readConfig();
+  const issues = [];
+  const warnings = [];
+  if (!cfg.provider) issues.push('config.provider is missing — run `lazyclaw onboard`');
+  // Only flag a missing api-key when the picked provider actually
+  // requires one. claude-cli / ollama / mock all run keylessly, so the
+  // previous `provider !== 'mock'` check produced false positives.
+  const _meta = (getRegistry().PROVIDER_INFO || {})[cfg.provider] || {};
+  if (cfg.provider && _meta.requiresApiKey && !cfg['api-key']) {
+    issues.push(`config['api-key'] is missing for provider "${cfg.provider}"`);
+  }
+  if (cfg.provider && !PROVIDERS_HAS(getRegistry().PROVIDERS, cfg.provider)) {
+    issues.push(`unknown provider "${cfg.provider}" — registered: ${Object.keys(getRegistry().PROVIDERS).join(', ')}`);
+  }
+  // v5.3.2 soft-migration — pre-5.3.2 wizards could write
+  // `provider: 'orchestrator'` even when the user never configured the
+  // orchestrator section (planner / workers). On those installs the
+  // first chat turn dies with an opaque "orchestrator not configured"
+  // error. Surface a warning + the fix hint, but never auto-rewrite
+  // cfg.json — the user might have legitimately picked orchestrator
+  // and just hasn't finished setup yet.
+  if (cfg.provider === 'orchestrator') {
+    const orch = cfg.orchestrator;
+    const configured = orch && typeof orch === 'object'
+      && typeof orch.planner === 'string' && orch.planner
+      && Array.isArray(orch.workers) && orch.workers.length > 0;
+    if (!configured) {
+      warnings.push(
+        'config.provider is "orchestrator" but cfg.orchestrator is missing/empty. '
+        + 'Pre-v5.3.2 setup wizards could leave you in this half-configured state. '
+        + 'Either finish orchestrator setup (`lazyclaw orchestrator set-planner …` + `lazyclaw orchestrator workers add …`) '
+        + 'or switch to a single concrete provider: `lazyclaw config set provider claude-cli`.'
+      );
+    }
+  }
+  // C12 — MinGit / Windows safety net. mas/tools/git.mjs shells out to
+  // `git`; on a stripped Windows PATH (no Git-for-Windows installed) or
+  // a minimal Docker base image, that spawnSync ENOENTs and any agent
+  // task touching the git tool fails opaquely. Probe up-front so
+  // `lazyclaw doctor` surfaces a clean diagnostic and the operator can
+  // install the binary before they trip over it.
+  let gitInfo = null;
+  try {
+    const { spawnSync } = await import('node:child_process');
+    const gitExe = process.env.GIT_EXECUTABLE || 'git';
+    const probe = spawnSync(gitExe, ['--version'], { encoding: 'utf8' });
+    if (probe.error && probe.error.code === 'ENOENT') {
+      issues.push('git binary not found on PATH — `mas/tools/git.mjs` will fail. Install Git: macOS `xcode-select --install`; Linux `apt install git` / `yum install git`; Windows Git-for-Windows (https://git-scm.com/download/win). Or set the GIT_EXECUTABLE env var to an explicit path.');
+      gitInfo = { ok: false, code: 'ENOENT' };
+    } else if (probe.status !== 0) {
+      issues.push(`git --version exited ${probe.status} (${(probe.stderr || '').trim().slice(0, 200)})`);
+      gitInfo = { ok: false, status: probe.status, stderr: (probe.stderr || '').trim().slice(0, 200) };
+    } else {
+      gitInfo = { ok: true, version: (probe.stdout || '').trim() };
+    }
+  } catch (e) {
+    gitInfo = { ok: false, error: e?.message || String(e) };
+  }
+  // m11 — stale index probe. mas/index_db.mjs write-through hooks
+  // log failures to <configDir>/index-failures.jsonl; surface a recent
+  // count so the operator notices a silently-degraded index. Best-effort:
+  // missing file → 0 failures (the common case).
+  let indexInfo = null;
+  try {
+    const cfgDir = path.dirname(configPath());
+    const auditFile = path.join(cfgDir, 'index-failures.jsonl');
+    if (fs.existsSync(auditFile)) {
+      const raw = fs.readFileSync(auditFile, 'utf8');
+      const lines = raw.split('\n').filter(Boolean);
+      const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+      let recent = 0;
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line);
+          if (entry?.ts && new Date(entry.ts).getTime() >= cutoff) recent++;
+        } catch { /* skip malformed */ }
+      }
+      indexInfo = { failuresLast24h: recent, totalFailures: lines.length };
+      if (recent > 0) {
+        issues.push(`${recent} index write failure(s) in the last 24h — run \`lazyclaw index rebuild\` to recover.`);
+      }
+    } else {
+      indexInfo = { failuresLast24h: 0, totalFailures: 0 };
+    }
+  } catch (e) {
+    indexInfo = { error: e?.message || String(e) };
+  }
+  // Workflow state health — informational counters that show whether
+  // the user has any failed or stuck workflow runs to attend to. We
+  // don't push these to `issues` (a stuck workflow doesn't break the
+  // CLI) but they surface in the output so `lazyclaw doctor | jq` can
+  // surface them in dashboards.
+  const stateDir = process.env.LAZYCLAW_WORKFLOW_STATE_DIR || '.workflow-state';
+  let workflows = null;
+  try {
+    const { listSessions } = await import('../workflow/summary.mjs');
+    if (fs.existsSync(stateDir)) {
+      const sessions = listSessions(stateDir);
+      const counts = { total: sessions.length, done: 0, resumable: 0, failed: 0, running: 0 };
+      for (const s of sessions) {
+        if (s.summary.done)         counts.done++;
+        if (s.summary.resumable)    counts.resumable++;
+        if (s.summary.failed > 0)   counts.failed++;
+        if (s.summary.running > 0)  counts.running++;
+      }
+      workflows = { dir: stateDir, ...counts };
+      // Surface a hint when there are stuck runs that the engine will
+      // demote to pending on next load — this often signals a process
+      // that crashed; the user should at least know.
+      if (counts.running > 0) {
+        issues.push(`${counts.running} workflow session(s) have 'running' nodes from a prior interrupted run — they will be demoted to pending on next resume.`);
+      }
+    } else {
+      workflows = { dir: stateDir, present: false };
+    }
+  } catch (e) {
+    workflows = { dir: stateDir, error: e?.message || String(e) };
+  }
+  const ok = issues.length === 0;
+  const out = {
+    ok,
+    configPath: configPath(),
+    provider: cfg.provider || null,
+    model: cfg.model || null,
+    hasApiKey: !!cfg['api-key'],
+    nodeVersion: process.version,
+    platform: `${process.platform}-${process.arch}`,
+    issues,
+    warnings,
+    knownProviders: Object.keys(getRegistry().PROVIDERS),
+    workflows,
+    git: gitInfo,
+    index: indexInfo,
+    timestamp: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(out, null, 2));
+  process.exit(ok ? 0 : 1);
+}
+
+export function PROVIDERS_HAS(map, name) {
+  return Object.prototype.hasOwnProperty.call(map, name);
+}
+
+export async function cmdStatus() {
+  await ensureRegistry();
+  const cfg = readConfig();
+  const out = {
+    configPath: configPath(),
+    provider: cfg.provider || null,
+    model: cfg.model || null,
+    keyMasked: getRegistry().maskApiKey(cfg['api-key']),
+  };
+  console.log(JSON.stringify(out, null, 2));
+}
+export async function cmdVersion() {
+  const out = {
+    version: readVersionFromRepo(),
+    nodeVersion: process.version,
+    platform: `${process.platform}-${process.arch}`,
+  };
+  console.log(JSON.stringify(out));
+}
+
+export async function cmdCompletion(shell) {
+  if (shell === 'bash') { process.stdout.write(bashCompletion()); return; }
+  if (shell === 'zsh')  { process.stdout.write(zshCompletion()); return; }
+  console.error('Usage: lazyclaw completion <bash|zsh>');
+  process.exit(2);
+}
+export function cmdConfigGet(key) {
+  const cfg = readConfig();
+  if (!key) { console.log(JSON.stringify(cfg)); return; }
+  let value = cfg;
+  for (const seg of String(key).split('.')) {
+    if (value && typeof value === 'object' && seg in value) value = value[seg];
+    else { value = null; break; }
+  }
+  console.log(JSON.stringify({ key, value }));
+}
+
+// Structural integrity check across the whole config. Distinct from
+// `lazyclaw doctor` (runtime checks: provider available, key present
+// for the active provider). Validate is purely about *shape* — does
+// every value have the right type, is `provider` known, are rates
+// well-formed.
+//
+// Hard issues exit 1; unknown top-level keys produce warnings (kept
+// exit 0 so a forward-compatible config from a newer CLI doesn't
+// fail validate on an older CLI).
+export async function cmdConfigValidate() {
+  const cfg = readConfig();
+  await ensureRegistry();
+  const { validateConfig } = await import('../config-validate.mjs');
+  const { ok, issues, warnings } = validateConfig(cfg, getRegistry().PROVIDERS);
+  console.log(JSON.stringify({
+    ok,
+    configPath: configPath(),
+    keys: Object.keys(cfg),
+    issues,
+    warnings,
+  }, null, 2));
+  process.exit(ok ? 0 : 1);
+}

package/commands/daemon.mjs

@@ -0,0 +1,260 @@
+// Daemon + dashboard lifecycle commands (cmdDashboard, cmdDaemon) plus the
+// _killPortOccupant helper, extracted from cli.mjs in Phase D3.
+import path from 'node:path';
+import { ensureRegistry } from '../lib/registry_boot.mjs';
+import { configPath, readConfig, writeConfig, readVersionFromRepo } from '../lib/config.mjs';
+
+export async function _killPortOccupant(port) {
+  if (process.platform === 'win32') return false;
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolve) => {
+    let lsof;
+    try {
+      lsof = spawn('lsof', ['-ti', `tcp:${port}`], { stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch (_) { return resolve(false); }
+    let buf = '';
+    lsof.stdout.on('data', (d) => { buf += d.toString('utf8'); });
+    lsof.on('error', () => resolve(false));
+    lsof.on('close', () => {
+      const pids = buf.trim().split(/\s+/).map((s) => parseInt(s, 10)).filter(Number.isFinite);
+      if (!pids.length) return resolve(false);
+      // SIGTERM first so node has a chance to clean up; SIGKILL the
+      // holdouts after a short grace window.
+      for (const pid of pids) {
+        try { process.kill(pid, 'SIGTERM'); } catch (_) { /* gone already */ }
+      }
+      setTimeout(() => {
+        for (const pid of pids) {
+          try { process.kill(pid, 'SIGKILL'); } catch (_) { /* gone */ }
+        }
+        resolve(true);
+      }, 200);
+    });
+  });
+}
+
+export async function cmdDashboard(flags = {}) {
+  await ensureRegistry();
+  const sessionsMod = await import('../sessions.mjs');
+  const { startDaemon } = await import('../daemon.mjs');
+  const port = flags.port !== undefined ? parseInt(flags.port, 10) : 19600;
+  const cfgDir = path.dirname(configPath());
+  const daemonOpts = {
+    port,
+    once: false,
+    readConfig,
+    writeConfig,
+    sessionsDirGetter: () => cfgDir,
+    sessionsMod,
+    version: () => readVersionFromRepo(),
+    workflowStateDir: () => process.env.LAZYCLAW_WORKFLOW_STATE_DIR || '.workflow-state',
+    // No auth token by default — same loopback-only assumption the
+    // bare daemon uses. Users who want to expose the dashboard set
+    // LAZYCLAW_AUTH_TOKEN + --allow-origin via the daemon command.
+    authToken: undefined,
+    allowedOrigins: [],
+    // The dashboard's browser tab posts back to the same loopback URL
+    // it was served from (e.g. `http://127.0.0.1:19600`). Without this
+    // opt-in every chat send / mutation tripped the daemon's CSRF gate
+    // with `403 forbidden origin`. Safe — the daemon binds 127.0.0.1
+    // only, so an attacker can't reach it with a loopback origin
+    // unless they're already on the machine.
+    allowLoopbackOrigin: true,
+    rateLimit: null,
+    responseCache: null,
+    logger: null,
+    costCap: null,
+  };
+  let d;
+  try {
+    d = await startDaemon(daemonOpts);
+  } catch (err) {
+    if (err?.code !== 'EADDRINUSE') throw err;
+    // Port is held by a leftover dashboard / daemon. Try to free it
+    // (lsof + kill on macOS/Linux); on failure, fall back to a random
+    // port so the user always gets a working dashboard rather than a
+    // crash trace.
+    const portInUse = port;
+    process.stderr.write(`  ⚠ port ${portInUse} is in use — likely a previous dashboard didn't shut down.\n`);
+    const killed = await _killPortOccupant(portInUse);
+    if (killed) {
+      process.stderr.write(`  ✓ freed port ${portInUse} (killed prior listener) — retrying…\n`);
+      // Short pause so the OS releases the port before we re-listen.
+      await new Promise(r => setTimeout(r, 250));
+      try { d = await startDaemon(daemonOpts); }
+      catch (err2) {
+        if (err2?.code !== 'EADDRINUSE') throw err2;
+        process.stderr.write(`  ⚠ still in use — falling back to a random port.\n`);
+        d = await startDaemon({ ...daemonOpts, port: 0 });
+      }
+    } else {
+      process.stderr.write(`  ⚠ couldn't free port ${portInUse} automatically — falling back to a random port.\n`);
+      d = await startDaemon({ ...daemonOpts, port: 0 });
+    }
+  }
+  const url = `http://127.0.0.1:${d.port}/dashboard`;
+  process.stdout.write(`🦞 LazyClaw dashboard listening at ${url}\n`);
+  if (!flags['no-open']) {
+    // macOS uses `open`; Linux generally `xdg-open`; Windows
+    // `cmd /c start`. Detect by platform; bail silently if the
+    // helper fails — the URL is already on stdout for fallback.
+    const { spawn } = await import('node:child_process');
+    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 (_) { /* user can click the URL above */ }
+  }
+  // Forward SIGINT/SIGTERM to a graceful shutdown so Ctrl-C doesn't
+  // strand a port-bound server. Same shape cmdDaemon uses.
+  const { gracefulShutdown } = await import('../daemon.mjs');
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return process.exit(1);
+    shuttingDown = true;
+    process.stdout.write('\n  shutting down…\n');
+    const result = await gracefulShutdown(d.server, 5_000);
+    process.exit(result.forced ? 1 : 0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+export async function cmdDaemon(flags) {
+  await ensureRegistry();
+  const sessionsMod = await import('../sessions.mjs');
+  const { startDaemon } = await import('../daemon.mjs');
+  const port = flags.port !== undefined ? parseInt(flags.port, 10) : 0;
+  const once = !!flags.once;
+  // --auth-token wins over the env var so a per-invocation override works.
+  // When neither is set, the daemon runs unauthenticated (the historical
+  // single-user-loopback default).
+  const authToken = flags['auth-token'] || process.env.LAZYCLAW_AUTH_TOKEN || null;
+  // --allow-origin accepts a comma-separated list (also reads
+  // LAZYCLAW_ALLOW_ORIGINS env). When neither is set, any request that
+  // carries an `Origin` header is rejected with 403 — the browser-CSRF
+  // / DNS-rebinding default. CLI/script callers don't send Origin so
+  // they're unaffected.
+  const originSrc = flags['allow-origin'] || process.env.LAZYCLAW_ALLOW_ORIGINS || '';
+  const allowedOrigins = String(originSrc).split(',').map(s => s.trim()).filter(Boolean);
+  // --rate-limit <capacity> sets a token-bucket cap per remote IP.
+  // refillPerSec defaults to capacity/60 so the bucket sustains the
+  // same long-run rate (a bucket of 60 / 1 per second == 60 req/min).
+  // Pass 0 (or omit) to leave the daemon unlimited.
+  const rlCap = flags['rate-limit'] ? parseInt(flags['rate-limit'], 10) : 0;
+  const rateLimit = (Number.isFinite(rlCap) && rlCap > 0)
+    ? { capacity: rlCap, refillPerSec: rlCap / 60 }
+    : null;
+  // --response-cache flips the daemon-scope cache on (no value form ⇒ true).
+  // Per-request opt-in still happens via body.cache; this just allocates
+  // the shared map so the cache state actually persists.
+  const responseCache = flags['response-cache'] ? true : null;
+  // --log <level> enables structured access logging. Also reads
+  // LAZYCLAW_LOG_LEVEL. When set, every request emits a JSON line on
+  // stderr at info level: {ts, level, msg:'access', method, path, status,
+  // durationMs, remote}. Default is silent.
+  const logLevel = flags.log || process.env.LAZYCLAW_LOG_LEVEL || null;
+  const { createLogger } = await import('../logger.mjs');
+  const logger = logLevel ? createLogger({ level: logLevel }) : null;
+  // Cost cap parsing: any --cost-cap-<currency> <amount> flag pair
+  // contributes one entry to the costCap map. Currency codes are upper-
+  // cased to match what costFromUsage's rate cards produce. Bad/zero
+  // values are silently skipped — the daemon should never reject a
+  // request because the operator typo'd the limit.
+  const costCap = {};
+  for (const [k, v] of Object.entries(flags)) {
+    if (!k.startsWith('cost-cap-')) continue;
+    const cur = k.slice('cost-cap-'.length).toUpperCase();
+    const amt = Number(v);
+    if (Number.isFinite(amt) && amt > 0) costCap[cur] = amt;
+  }
+  const costCapOrNull = Object.keys(costCap).length > 0 ? costCap : null;
+  // Workflow state dir: --workflow-state-dir flag wins, then env, then
+  // the CLI's default of `.workflow-state` (cwd-relative). Mirrors the
+  // CLI's `lazyclaw run --dir` resolution so `inspect` and the daemon
+  // see the same files.
+  const workflowStateDirValue = flags['workflow-state-dir']
+    || process.env.LAZYCLAW_WORKFLOW_STATE_DIR
+    || '.workflow-state';
+  const cfgDir = path.dirname(configPath());
+  let d;
+  try {
+    d = await startDaemon({
+      port: Number.isFinite(port) ? port : 0,
+      once,
+      readConfig,
+      // `lazyclaw daemon` exposes mutation endpoints (POST /providers,
+      // PUT /rates/<key>, etc.) only when an auth token is configured
+      // — without one the daemon is loopback-only but still untrusted
+      // (any process on the box can hit it). dashboard subcommand sets
+      // writeConfig unconditionally because it always runs as the user.
+      writeConfig: authToken ? writeConfig : undefined,
+      sessionsDirGetter: () => cfgDir,
+      sessionsMod,
+      version: () => readVersionFromRepo(),
+      workflowStateDir: () => workflowStateDirValue,
+      authToken: authToken || undefined,
+      allowedOrigins,
+      rateLimit,
+      responseCache,
+      logger,
+      costCap: costCapOrNull,
+    });
+  } catch (err) {
+    // `lazyclaw daemon` exits cleanly on EADDRINUSE with a readable
+    // message instead of the historical unhandled-error stack trace.
+    // Unlike `lazyclaw dashboard`, daemon doesn't auto-kill the prior
+    // listener — bare daemon callers are usually scripts that expect
+    // exact port semantics, so we surface the failure and let them
+    // choose (re-run with --port 0 for random, or kill the holdout).
+    if (err?.code === 'EADDRINUSE') {
+      process.stderr.write(
+        `lazyclaw daemon: port ${port} is in use.\n` +
+        `  Re-run with --port 0 for a random port, or free the port:\n` +
+        `    lsof -ti tcp:${port} | xargs kill -9\n`
+      );
+      process.exit(2);
+    }
+    throw err;
+  }
+  // Print the bound port immediately so test/script callers can pick it up
+  // even when we asked for port 0. Indicate auth presence (not the token)
+  // and the allowed-origin count (not the values, just whether browser
+  // access has been opened).
+  process.stdout.write(JSON.stringify({
+    ok: true, url: `http://127.0.0.1:${d.port}`, port: d.port, once,
+    auth: !!authToken,
+    allowedOriginCount: allowedOrigins.length,
+    rateLimit: rateLimit ? { capacity: rateLimit.capacity, refillPerSec: rateLimit.refillPerSec } : null,
+    responseCache: !!responseCache,
+    log: logLevel || null,
+    costCap: costCapOrNull,
+  }) + '\n');
+  if (!once) {
+    // Forward SIGINT/SIGTERM to a graceful shutdown with a hard timeout
+    // (default 10 s, override with --shutdown-timeout-ms). Second signal
+    // bypasses the wait and exits immediately — the orchestrator's "I
+    // mean it" signal.
+    const { gracefulShutdown } = await import('../daemon.mjs');
+    const timeoutMs = flags['shutdown-timeout-ms'] ? parseInt(flags['shutdown-timeout-ms'], 10) : 10_000;
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) {
+        if (logger) logger.warn('shutdown.force', { reason: 'second signal' });
+        return process.exit(1);
+      }
+      shuttingDown = true;
+      if (logger) logger.info('shutdown.begin', { timeoutMs });
+      const result = await gracefulShutdown(d.server, timeoutMs);
+      if (logger) logger.info('shutdown.end', result);
+      process.exit(result.forced ? 1 : 0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  } else {
+    // In once mode, exit naturally after the server closes.
+    d.server.on('close', () => process.exit(0));
+  }
+}