lazyclaw 6.3.1 → 6.5.0

package/commands/config.mjs

@@ -102,11 +102,45 @@ export async function cmdConfigEdit() {
   }
 }
 
+// Coerce a CLI string value into the type it most likely represents so a
+// boolean/number setting isn't stored as a string the rest of the code then
+// mis-compares (`if (cfg.chat.recall)` is truthy for the string "false").
+//   'true' / 'false'        → boolean
+//   integer / float strings → number
+//   everything else         → the original string (provider/model/api-key/…)
+function coerceConfigValue(value) {
+  if (typeof value !== 'string') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  // Only treat as a number when the WHOLE string is a clean numeric literal —
+  // Number('') is 0 and Number('1.2.3') is NaN, both of which we reject so
+  // ids like "gpt-4.1" or empty values stay strings.
+  if (value.trim() !== '' && /^-?(?:\d+|\d*\.\d+|\d+\.\d*)$/.test(value.trim()) && Number.isFinite(Number(value))) {
+    return Number(value);
+  }
+  return value;
+}
+
 export function cmdConfigSet(key, value) {
   const cfg = readConfig();
-  cfg[key] = value;
+  const coerced = coerceConfigValue(value);
+  if (typeof key === 'string' && key.includes('.')) {
+    // Dotted key → nested path. Walk/create each intermediate object so
+    // `chat.recall` lands as cfg.chat.recall (not a flat "chat.recall" key).
+    // A non-object value blocking the path is replaced rather than crashing.
+    const segs = key.split('.');
+    let node = cfg;
+    for (let i = 0; i < segs.length - 1; i++) {
+      const seg = segs[i];
+      if (!node[seg] || typeof node[seg] !== 'object' || Array.isArray(node[seg])) node[seg] = {};
+      node = node[seg];
+    }
+    node[segs[segs.length - 1]] = coerced;
+  } else {
+    cfg[key] = coerced;
+  }
   writeConfig(cfg);
-  console.log(JSON.stringify({ ok: true, key, value }));
+  console.log(JSON.stringify({ ok: true, key, value: coerced }));
 }
 export async function cmdDoctor() {
   await ensureRegistry();

package/commands/daemon.mjs

@@ -1,9 +1,70 @@
 // Daemon + dashboard lifecycle commands (cmdDashboard, cmdDaemon) plus the
 // _killPortOccupant helper, extracted from cli.mjs in Phase D3.
 import path from 'node:path';
+import fs from 'node:fs';
 import { ensureRegistry } from '../lib/registry_boot.mjs';
 import { configPath, readConfig, writeConfig, readVersionFromRepo } from '../lib/config.mjs';
 import { assertUnattendedSafe, installCrashHandlers } from '../lib/gateway_guard.mjs';
+import { isProcessAlive } from '../loops.mjs';
+
+// The bare `lazyclaw daemon` runs in the foreground, so a started daemon
+// records its pid + the actually-bound port here. status/stop read it back;
+// the start path writes it after bind and removes it on graceful shutdown.
+export function _daemonPidfilePath(configDir) {
+  return path.join(configDir, 'daemon.pid');
+}
+
+// Parse the pidfile into { pid, port } or null if missing/garbage. Never
+// throws — a corrupt pidfile is treated the same as "no daemon".
+export function readDaemonPidfile(pidfilePath) {
+  try {
+    const raw = fs.readFileSync(pidfilePath, 'utf8');
+    const obj = JSON.parse(raw);
+    const pid = parseInt(obj?.pid, 10);
+    if (!Number.isFinite(pid)) return null;
+    const port = Number.isFinite(parseInt(obj?.port, 10)) ? parseInt(obj.port, 10) : null;
+    return { pid, port };
+  } catch { return null; }
+}
+
+// Inspect the daemon pidfile and report liveness. A pidfile pointing at a
+// dead pid is stale (the daemon crashed without removing it), so we clean it
+// up here to keep `status` self-healing.
+export function daemonStatus({ configDir }, deps = {}) {
+  const isAlive = deps.isAlive || isProcessAlive;
+  const pf = _daemonPidfilePath(configDir);
+  const rec = readDaemonPidfile(pf);
+  if (!rec) return { running: false, pid: null, port: null };
+  if (isAlive(rec.pid)) return { running: true, pid: rec.pid, port: rec.port };
+  // Stale pidfile — remove it so the next start/status starts clean.
+  try { fs.rmSync(pf); } catch { /* already gone */ }
+  return { running: false, pid: null, port: null };
+}
+
+// SIGTERM the recorded daemon, falling back to SIGKILL only if it ignores the
+// graceful signal. Returns { running, pid, port, killed, exitCode }; a missing
+// or dead pidfile is "not running" (exit 0), never an error.
+export function daemonStop({ configDir }, deps = {}) {
+  const isAlive = deps.isAlive || isProcessAlive;
+  const kill = deps.kill || ((pid, sig) => process.kill(pid, sig));
+  const pf = _daemonPidfilePath(configDir);
+  const rec = readDaemonPidfile(pf);
+  if (!rec || !isAlive(rec.pid)) {
+    try { fs.rmSync(pf); } catch { /* nothing to clean */ }
+    return { running: false, pid: rec ? rec.pid : null, port: rec ? rec.port : null, killed: false, exitCode: 0 };
+  }
+  try { kill(rec.pid, 'SIGTERM'); } catch { /* raced with exit */ }
+  // Short grace window, then SIGKILL the holdout. This is best-effort and
+  // synchronous so the CLI exits deterministically; the daemon's own
+  // graceful-shutdown hook usually wins well inside the window.
+  if (isAlive(rec.pid)) {
+    const until = Date.now() + 1500;
+    while (isAlive(rec.pid) && Date.now() < until) { /* spin briefly */ }
+    if (isAlive(rec.pid)) { try { kill(rec.pid, 'SIGKILL'); } catch { /* gone */ } }
+  }
+  try { fs.rmSync(pf); } catch { /* removed by the daemon already */ }
+  return { running: true, pid: rec.pid, port: rec.port, killed: true, exitCode: 0 };
+}
 
 // Fail closed before binding the HTTP surface: the daemon/dashboard serve
 // POST /inbound + /agent, so the global unattended-sensitive override must
@@ -134,6 +195,35 @@ export async function cmdDashboard(flags = {}) {
 }
 
 export async function cmdDaemon(flags) {
+  // cli.mjs dispatches `daemon` with only the parsed flags, so the lifecycle
+  // subcommand (status|stop|logs) is recovered from argv here. The first
+  // non-flag positional after `daemon` is the subcommand; absent it, we start
+  // the server as before.
+  const { parseArgs } = await import('../lib/args.mjs');
+  const sub = parseArgs(process.argv.slice(3)).positional[0];
+  const cfgDirEarly = path.dirname(configPath());
+  if (sub === 'status') {
+    const st = daemonStatus({ configDir: cfgDirEarly });
+    process.stdout.write(JSON.stringify(st) + '\n');
+    process.exit(0);
+  }
+  if (sub === 'stop') {
+    const r = daemonStop({ configDir: cfgDirEarly });
+    if (!r.running) process.stdout.write('lazyclaw daemon: not running\n');
+    else process.stdout.write(`lazyclaw daemon: stopped pid ${r.pid}${r.killed ? '' : ''}\n`);
+    process.exit(r.exitCode);
+  }
+  if (sub === 'logs') {
+    // The foreground daemon writes its boot line + access logs to stdout; a
+    // logfile only exists when it was installed as an OS service (see
+    // lib/service_install.mjs servicePaths). Point the user at whichever is
+    // applicable. No tail-follower — keep it simple.
+    const { servicePaths } = await import('../lib/service_install.mjs');
+    const logfile = servicePaths('daemon', { configDir: cfgDirEarly }).logfile;
+    if (fs.existsSync(logfile)) process.stdout.write(logfile + '\n');
+    else process.stdout.write(`No service logfile at ${logfile}.\nThe foreground daemon logs to stdout (run \`lazyclaw daemon --log info\`).\n`);
+    process.exit(0);
+  }
   await ensureRegistry();
   _bootGuard('daemon');
   const sessionsMod = await import('../sessions.mjs');
@@ -245,6 +335,13 @@ export async function cmdDaemon(flags) {
     costCap: costCapOrNull,
   }) + '\n');
   if (!once) {
+    // Record pid + the ACTUAL bound port (d.port, not the requested port,
+    // which may be 0) so `daemon status`/`daemon stop` can find us without
+    // an lsof on the port. Removed on graceful shutdown below.
+    const pidfile = _daemonPidfilePath(cfgDir);
+    try { fs.writeFileSync(pidfile, JSON.stringify({ pid: process.pid, port: d.port })); }
+    catch { /* non-fatal: the daemon still runs, just isn't stoppable by pidfile */ }
+    const removePidfile = () => { try { fs.rmSync(pidfile); } catch { /* already gone */ } };
     // 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
@@ -253,7 +350,7 @@ export async function cmdDaemon(flags) {
     const timeoutMs = flags['shutdown-timeout-ms'] ? parseInt(flags['shutdown-timeout-ms'], 10) : 10_000;
     // Always-on: make an unhandled crash observable + drain sockets, then
     // exit non-zero so a service manager restarts us (vs. silent death).
-    installCrashHandlers({ label: 'daemon', logger, stop: () => gracefulShutdown(d.server, timeoutMs) });
+    installCrashHandlers({ label: 'daemon', logger, stop: () => { removePidfile(); return gracefulShutdown(d.server, timeoutMs); } });
     let shuttingDown = false;
     const shutdown = async () => {
       if (shuttingDown) {
@@ -263,6 +360,7 @@ export async function cmdDaemon(flags) {
       shuttingDown = true;
       if (logger) logger.info('shutdown.begin', { timeoutMs });
       const result = await gracefulShutdown(d.server, timeoutMs);
+      removePidfile();
       if (logger) logger.info('shutdown.end', result);
       process.exit(result.forced ? 1 : 0);
     };

package/commands/gateway.mjs

@@ -14,6 +14,8 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { configPath, readConfig, writeConfig, readVersionFromRepo } from '../lib/config.mjs';
 import { ensureRegistry } from '../lib/registry_boot.mjs';
 import { loadDotenvIfAny } from '../dotenv_min.mjs';
@@ -22,6 +24,13 @@ import { makeInboundHandler } from '../lib/inbound_client.mjs';
 
 export const GATEWAY_CHANNELS = ['slack', 'telegram', 'matrix'];
 
+// In-tree plugin channels (channels-<name>/index.mjs). These are NOT builtins:
+// each ships as a @lazyclaw/channel-* package that exports
+// register({ addChannel }) and wires a factory returning a channels/base.mjs
+// Channel (start/send/stop). The gateway loads the ENABLED ones at runtime so
+// `channels enable discord` is actually reachable instead of a no-op.
+export const PLUGIN_CHANNELS = ['discord', 'email', 'signal', 'voice', 'whatsapp'];
+
 // Default per-channel constructors. Each receives { handler, logger,
 // allowlist }, must return a started channel exposing send()/stop().
 // Injectable so tests can run the full gateway with stub transports.
@@ -47,15 +56,113 @@ const DEFAULT_FACTORIES = {
   },
 };
 
+// Resolve an enabled plugin channel into the same gateway transport factory
+// shape the builtins use: ({ handler, logger, allowlist }) -> a STARTED
+// channel exposing send()/stop(). Dynamically imports channels-<name>/index.mjs
+// and runs its register({ addChannel }) hook to capture the channel factory.
+//
+// A plugin that does not conform — import fails, no register export, never
+// registers the requested name — is SKIPPED (returns null) so the gateway can
+// log a warning and keep the other channels running. A factory that hands back
+// the wrong shape is caught lazily, when the returned transport factory is
+// invoked, so runGateway's per-channel try/catch turns it into a skip+warn.
+// Resolve an in-tree adapter's runtime dependency from <cfgDir>/node_modules
+// (where `lazyclaw channels install <name>` puts it), falling back to a bare
+// import (dep installed alongside lazyclaw). The adapters do a bare
+// `import('discord.js')` which Node resolves from the adapter's own location —
+// NOT the config dir — so without this an installed dep is never found.
+export function _makeDepLoader(cfgDir) {
+  return async (specifier) => {
+    if (cfgDir) {
+      try {
+        // Anchor resolution inside <cfgDir>/node_modules. The anchor file need
+        // not exist; createRequire only uses its directory as the base.
+        const req = createRequire(path.join(cfgDir, 'node_modules', '_anchor_.js'));
+        const resolved = req.resolve(specifier);
+        return await import(pathToFileURL(resolved).href);
+      } catch { /* fall through to a bare import */ }
+    }
+    return import(specifier);
+  };
+}
+
+// Map the .env-derived credentials into each in-tree adapter's constructor opts
+// (the gateway loads .env into process.env at boot). discord/whatsapp also fall
+// back to env internally, but email has NO env fallback and threw
+// IMAP_CONFIG_MISSING when the gateway passed only { allowlist }.
+export function _pluginChannelOpts(name, env = process.env, cfgDir = '') {
+  switch (name) {
+    case 'discord':
+      return { token: env.DISCORD_BOT_TOKEN || null };
+    case 'email':
+      return {
+        imap: {
+          host: env.EMAIL_IMAP_HOST, user: env.EMAIL_IMAP_USER, password: env.EMAIL_IMAP_PASS,
+          port: env.EMAIL_IMAP_PORT ? Number(env.EMAIL_IMAP_PORT) : undefined,
+          tls: env.EMAIL_IMAP_TLS ? env.EMAIL_IMAP_TLS !== 'false' : undefined,
+        },
+        smtp: {
+          host: env.EMAIL_SMTP_HOST || env.EMAIL_IMAP_HOST, port: env.EMAIL_SMTP_PORT ? Number(env.EMAIL_SMTP_PORT) : undefined,
+          user: env.EMAIL_SMTP_USER || env.EMAIL_IMAP_USER, pass: env.EMAIL_SMTP_PASS || env.EMAIL_IMAP_PASS,
+        },
+      };
+    case 'whatsapp':
+      return { dataPath: path.join(cfgDir || '.', 'whatsapp') };
+    case 'signal':
+      return { account: env.SIGNAL_ACCOUNT || null };
+    case 'voice':
+      return { apiKey: env.OPENAI_API_KEY || null };
+    default:
+      return {};
+  }
+}
+
+// `importer` is injectable for tests. cfgDir + env let the factory resolve the
+// adapter's runtime dep from the config dir and thread credentials in.
+export async function _loadPluginChannel(name, { importer, cfgDir = '', env = process.env } = {}) {
+  const load = importer || ((n) => import(`../channels-${n}/index.mjs`));
+  let mod;
+  try {
+    mod = await load(name);
+  } catch {
+    return null; // missing optional dep / module: skip, do not crash the gateway.
+  }
+  if (!mod || typeof mod.register !== 'function') return null;
+  let channelFactory = null;
+  try {
+    mod.register({ addChannel: (n, factory) => { if (n === name) channelFactory = factory; } });
+  } catch {
+    return null;
+  }
+  if (typeof channelFactory !== 'function') return null;
+  const loadDep = _makeDepLoader(cfgDir);
+  return async ({ handler, logger, allowlist }) => {
+    const ch = channelFactory({ allowlist, loadDep, ..._pluginChannelOpts(name, env, cfgDir) });
+    if (!ch || typeof ch.start !== 'function' || typeof ch.send !== 'function' || typeof ch.stop !== 'function') {
+      throw new Error(`plugin channel "${name}" does not conform to the channel interface (start/send/stop)`);
+    }
+    await ch.start(handler, { poll: true, logger });
+    return ch;
+  };
+}
+
 // Which channels should the gateway run? --channels a,b wins; otherwise the
-// enabled cfg.channels sections that we have a built-in transport for.
+// enabled cfg.channels sections we can actually run — a built-in transport OR
+// an in-tree plugin channel.
 export function _selectChannels(cfg, flags = {}) {
+  const runnable = (n) => GATEWAY_CHANNELS.includes(n) || PLUGIN_CHANNELS.includes(n);
   if (flags.channels) {
     return String(flags.channels).split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)
-      .filter((n) => GATEWAY_CHANNELS.includes(n));
+      .filter(runnable);
   }
   const configured = (cfg.channels && typeof cfg.channels === 'object') ? cfg.channels : {};
-  return GATEWAY_CHANNELS.filter((n) => configured[n] && configured[n].enabled !== false);
+  const isEnabled = (n) => configured[n] && configured[n].enabled !== false;
+  // Builtins first (in their canonical order, preserving existing behavior),
+  // then enabled plugin channels.
+  return [
+    ...GATEWAY_CHANNELS.filter(isEnabled),
+    ...PLUGIN_CHANNELS.filter(isEnabled),
+  ];
 }
 
 // The whole gateway, with injectable deps so tests can drive it end-to-end
@@ -129,7 +236,19 @@ export async function runGateway(flags = {}, deps = {}) {
       provider: flags.provider, model: flags.model,
     });
     try {
-      const ch = await factories[name]({
+      // Builtin transport, else resolve an enabled in-tree plugin channel and
+      // adapt it to the same factory shape. A plugin that won't load is skipped
+      // (factory === null) rather than crashing the gateway.
+      let factory = factories[name];
+      if (!factory) {
+        factory = await _loadPluginChannel(name, { importer: deps.pluginImporter, cfgDir, env: process.env });
+        if (!factory) {
+          skipped.push({ name, error: 'plugin channel did not conform (no usable register/factory)' });
+          log(`[gateway] ${name}: skipped (plugin channel did not load or does not conform)\n`);
+          continue;
+        }
+      }
+      const ch = await factory({
         handler,
         logger: (line) => log(line),
         allowlist: allowlistArr.length ? allowlistArr : null,

package/commands/help_text.mjs

@@ -0,0 +1,78 @@
+// commands/help_text.mjs — pure-data help tables for `lazyclaw help`,
+// extracted verbatim from commands/setup.mjs (file-size gate, no behavior
+// change). HELP_SUMMARIES (one-liners for `help`) and HELP_DETAILS (per-
+// subcommand usage for `help <name>`) are read only by cmdHelp. They import
+// nothing and reference nothing else — pure data, lowest-risk extraction.
+
+// One-line summaries used by `lazyclaw help`. Format keeps it scan-friendly
+// in a 80-column terminal: subcommand padded to 12 chars, then the summary.
+export const HELP_SUMMARIES = {
+  run:        'Execute a workflow file (run <session-id> <workflow.mjs>)',
+  resume:     'Resume a workflow from its last persisted checkpoint',
+  config:     'Manage local config (get|set|list|delete <key>)',
+  chat:       'Interactive REPL with the configured provider',
+  agent:      'One-shot prompt: streams a single response, exits',
+  doctor:     'Print diagnostic JSON; exits non-zero on issues',
+  status:     'Print current provider/model/masked key as JSON',
+  onboard:    'Guided setup (use --non-interactive for scripts)',
+  sessions:   'Persistent chat sessions (list|show|clear|export)',
+  skills:     'Markdown skill bundles (list|show|install|remove)',
+  providers:  'Inspect / register providers (list|info|test|add|remove|models)',
+  daemon:     'Run the local HTTP gateway (--port, --auth-token, --allow-origin)',
+  version:    'Print VERSION + node + platform as JSON',
+  completion: 'Emit shell completion script (completion <bash|zsh>)',
+  export:     'Dump config + skills (+ optional sessions) as a JSON bundle',
+  import:     'Apply a JSON bundle from stdin or --from <path>',
+  rates:      'Manage cost rate-cards in config (rates list|set <provider/model>|delete|shape)',
+  auth:       'Multiple keys per provider (auth list|add|remove|use|rotate <provider>)',
+  pairing:    'Sender allowlist for the messaging surface (pairing list|add|remove <id>)',
+  nodes:      'Companion device registration (nodes list|register|remove <id>)',
+  message:    'Outbound webhook messaging (message list|add|remove|send <name>)',
+  workspace:  'AGENTS.md / SOUL.md / TOOLS.md system-prompt convention (workspace list|init|show|remove|path)',
+  browse:     'Fetch a URL and emit Markdown on stdout (browse <url> [--max-bytes <N>])',
+  cron:       'Schedule recurring agent runs via launchd / crontab (cron list|add|remove|show|sync|run)',
+  setup:      'Hermes-style phased first-run wizard (provider + verify chat + channel + workspace + skill + webhook)',
+  dashboard:  'Launch the lazyclaw-only web UI (lighter than the full lazyclaude dashboard)',
+  inspect:    'Print persisted workflow state without executing',
+  clear:      'Delete a persisted workflow state file (idempotent)',
+  validate:   'Static-check a workflow file: shape, deps, cycles, parallelism',
+  graph:      'Emit workflow DAG as Mermaid syntax (paste-ready for docs)',
+  orchestrator: 'Multi-agent dispatch — planner decomposes, workers run, planner synthesises',
+};
+
+// Detailed usage per subcommand for `lazyclaw help <name>`. Kept as flat
+// strings so the help output is identical in every terminal.
+export const HELP_DETAILS = {
+  run: 'Usage: lazyclaw run <session-id> <workflow.mjs> [--parallel | --parallel-persistent] [--concurrency <N>]\n  Default: runPersistent — sequential, persists state, resumable via `lazyclaw resume`.\n  --parallel: runParallel — topological-level DAG, in-memory only, NOT resumable.\n  --parallel-persistent: runPersistentDag — DAG + checkpoint + resume.\n  --concurrency <N>: cap in-flight nodes within a level (DAG modes only). 0/missing → unbounded.\n  Workflow file exports `nodes`; deps: string[] declares dependencies for both DAG modes.',
+  resume: 'Usage: lazyclaw resume <session-id> <workflow.mjs> [--parallel-persistent] [--concurrency <N>]\n  Re-enters a previously persisted run; succeeds nodes are skipped.\n  Pass --parallel-persistent to resume a DAG run (must match the original run\'s mode).\n  --concurrency <N>: cap in-flight nodes per level (DAG mode only).',
+  inspect: 'Usage: lazyclaw inspect [<session-id>] [--dir <state-dir>] [--status done|resumable|failed|running] [--summary] [--filter <substr>] [--limit <N>] [--node <node-id>] [--slowest <N>] [--critical-path <workflow.mjs>] [--aggregate]\n  With no session-id: list every persisted session in the state dir, sorted by recency.\n  --aggregate (list mode): per-node stats across all sessions (count, success/failed/pending/running, min/max/avg/total duration).\n  --status filters the listing to a single lifecycle bucket.\n  --filter / --limit refine list-mode further (case-insensitive sessionId substring + post-filter cap).\n  --summary trims per-node detail in single-session mode (matches list-mode shape).\n  --node <id>: print just that node\'s state. Exit 0 success/pending/running, 1 failed, 2 no such node.\n  --slowest <N>: top N nodes by durationMs (descending, ties broken by id).\n  --critical-path <workflow.mjs>: longest-weighted-path analysis using each node\'s recorded durationMs (bottleneck finder).\n  With a session-id (no per-node flag): print full state. Exit code: 0=resumable, 1=fully done, 2=no state, 3=terminal failure.',
+  clear: 'Usage: lazyclaw clear <session-id> [--dir <state-dir>]\n  Delete the state file for <session-id>. Idempotent — exits 0 whether the file existed or not.\n  Refuses sessionIds that resolve outside <state-dir>. Mirrors DELETE /workflows/<id> on the daemon.',
+  validate: 'Usage: lazyclaw validate <workflow.mjs>\n  Static check: load + shape + dep + cycle + parallelism estimate.\n  Exit 0 valid · 1 hard failure (issues populated) · 2 file/import error.',
+  graph: 'Usage: lazyclaw graph <workflow.mjs> [--lr] [--state <session-id>] [--dir <state-dir>]\n  Emit the workflow DAG as Mermaid syntax (graph TD by default; --lr for left-right).\n  --state overlays a persisted run\'s status (success ✓ / running ⏳ / failed ✗ / pending) with classDef styling.\n  Output is paste-ready for GitHub markdown / Notion / Obsidian.',
+  config: 'Usage: lazyclaw config <get|set|list|delete|path|edit|validate> [key] [value]\n  Local key-value config at $LAZYCLAW_CONFIG_DIR/config.json (default ~/.lazyclaw).\n  `path` prints the file location; `edit` opens it in $EDITOR (or $LAZYCLAW_EDITOR / $VISUAL / vi) and validates JSON on save.\n  `validate` checks the structural integrity of the whole config file (typed values, known providers, rate-card shape).',
+  chat: 'Usage: lazyclaw chat [--session <id>] [--skill name1,name2] [--workspace <name>] [--pick] [--sandbox docker:<image>] [--sandbox-network <net>] [--sandbox-mount <m>] [--sandbox-env <e>]\n  --session persists turns to <configDir>/sessions/<id>.jsonl across invocations.\n  --skill composes named skills into a system message at the head of the conversation.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md from <configDir>/workspaces/<name>/ into the system prompt.\n  --pick opens an interactive provider/model picker before the prompt (also auto-fires on first run).\n  --sandbox routes the underlying claude CLI through `docker run --rm -i --network <net> -v cwd:cwd ...` (default --network=none).',
+  agent: 'Usage: lazyclaw agent <prompt|-> [--provider X] [--model Y] [--skill list] [--workspace <name>] [--thinking N] [--show-thinking] [--usage] [--cost] [--sandbox docker:<image>]\n  One-shot non-interactive call. Pass "-" as the prompt to read from stdin.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md into the system prompt (combines with --skill).\n  --usage prints normalized {inputTokens, outputTokens, ...} to stderr after the response.\n  --cost adds a cost line on stderr when config.rates has a card for the active provider/model.\n  --sandbox docker:<image> wraps the subprocess provider (claude-cli) in a Docker container; --sandbox-network defaults to none.',
+  doctor: 'Usage: lazyclaw doctor\n  Validates configuration and registered providers. Exits 0 only when no issues.',
+  status: 'Usage: lazyclaw status\n  Provider, model, and masked API key. Never prints the raw key.',
+  onboard: 'Usage: lazyclaw onboard [--non-interactive] [--provider X] [--model Y] [--api-key Z]\n  --model accepts the unified "provider/model" string (e.g. anthropic/claude-opus-4-7).',
+  sessions: 'Usage: lazyclaw sessions <list [--filter <substr>] [--limit <N>]|show <id>|clear <id>|export <id> [--format md|json|text]|search <query> [--regex]>\n  list — recent sessions by mtime; --filter caps to ids containing substring (case-insensitive); --limit caps result count.\n  export — render in chosen format (md default for human sharing, json for tooling, text for paste).\n  search — case-insensitive substring (or --regex pattern) match across all session content; returns first excerpt + match count per matching session.',
+  skills: 'Usage: lazyclaw skills <list [--filter <substr>] [--limit <N>]|show <name>|install <user/repo[@ref][:path]> [--prefix <p>] [--force] | install <name> [--from <path> | --from-url <https://...>]|remove <name>|search <query> [--regex]>\n  list — installed skills; --filter caps to names containing substring (case-insensitive); --limit caps result count.\n  install <user>/<repo>[@<ref>][:<subpath>] — fetch a GitHub tarball, install every .md under skills/ (or the explicit subpath, or repo root). Default ref is `main`.\n    --prefix prepends a name prefix so a multi-skill repo doesn\'t collide with locally-managed skills. --force overwrites existing names.\n  install <name> --from <path> | --from-url <https://...> — single-file install. --from-url is HTTPS-only with a 1 MiB cap.\n  search — case-insensitive substring (or --regex) match across all skill markdown bodies; returns first excerpt + match count per skill.',
+  providers: 'Usage: lazyclaw providers <list [--filter <substr>] [--limit <N>] | info <name> | test <name> [--model X] [--prompt T] | test [--all] [--prompt T] | add <name> --base-url <url> [--api-key <k>] [--default-model <id>] [--no-probe] | remove <name> | models <name> [--filter <substr>]>\n  list   — registered providers (--filter case-insensitive name substring; --limit caps post-filter count).\n  info   — static metadata: requiresApiKey, defaultModel, suggestedModels, endpoint.\n  test   — send a 1-token "ping" through the provider and report ok/error + duration.\n           Useful after configuring an API key to verify it works before relying on it.\n           No name OR --all: tests every registered provider in parallel; exits 0 only when ALL pass.\n  add    — register a custom OpenAI-compatible endpoint (NIM / OpenRouter / Together / Groq / vLLM / LM Studio / …).\n           Probes /v1/models on success unless --no-probe is set; persists to cfg.customProviders[].\n  remove — drop a custom provider entry from cfg.customProviders[].\n  models — fetch + print the live model catalogue from <provider>/v1/models (works for openai / ollama / custom).',
+  daemon: 'Usage: lazyclaw daemon [--port <N>] [--once] [--auth-token <token>] [--allow-origin <origin>] [--rate-limit <N>] [--response-cache] [--log <level>] [--shutdown-timeout-ms <N>] [--cost-cap-<currency> <N> ...] [--workflow-state-dir <dir>]\n  Always binds 127.0.0.1. --port 0 picks a random port and prints the URL.\n  --auth-token also reads $LAZYCLAW_AUTH_TOKEN; --allow-origin also reads $LAZYCLAW_ALLOW_ORIGINS.\n  --rate-limit <N> caps each remote IP at N requests / 60 s.\n  --response-cache enables process-scoped memoization; per-request opt-in via body.cache.\n  --log <debug|info|warn|error> emits JSON-line access logs on stderr (also reads $LAZYCLAW_LOG_LEVEL).\n  --shutdown-timeout-ms <N> caps graceful drain on SIGINT/SIGTERM (default 10000). Second signal forces immediate exit.\n  --cost-cap-usd 100 (or any currency code in lowercase) rejects POST /agent + /chat with 402 once cumulative cost reaches the cap.\n  --workflow-state-dir <dir> backs GET /workflows + GET /workflows/<id> (default .workflow-state, also reads $LAZYCLAW_WORKFLOW_STATE_DIR).',
+  version: 'Usage: lazyclaw version\n  Aliases: --version, -v.',
+  completion: 'Usage: lazyclaw completion <bash|zsh>\n  bash:   eval "$(lazyclaw completion bash)"\n  zsh:    lazyclaw completion zsh > "${fpath[1]}/_lazyclaw"',
+  export: 'Usage: lazyclaw export [--include-secrets] [--include-sessions] > bundle.json\n  --include-secrets keeps the raw api-key in the bundle (default redacts it).\n  --include-sessions adds full turn content (default keeps metadata only).',
+  import: 'Usage: lazyclaw import [--from <path>] [--overwrite-skills] [--no-overwrite-config] [--import-sessions]\n  Reads JSON from stdin (or --from <path>). Sessions are NEVER overwritten.\n  Redacted api-keys (***REDACTED***) are dropped, never written.',
+  rates: 'Usage: lazyclaw rates <list [--filter <substr>] [--limit <N>] | set <provider/model> --input <N> --output <N> [--cache-read <N>] [--cache-create <N>] [--currency USD] | delete <key> | shape | validate | copy <src> <dst> [--force]>\n  Rates are per million tokens. costFromUsage uses cfg.rates to compute the cost block in /usage and body.cost.\n  `list` accepts --filter (case-insensitive key substring) and --limit (post-filter cap), same shape sessions/skills/workflows lists use.\n  `shape` prints the reference template (zero-filled) you can copy into config.\n  `validate` checks the cfg.rates shape: required fields, non-negative numbers, known providers (warn-only).\n  `copy` clones an existing card to a new key (use when a new model launches at the same price as an old one).',
+  sandbox: 'Usage: lazyclaw sandbox <list|test|add|use> [args]\n  list             show 6 backends (local, docker, ssh, singularity, modal, daytona)\n  test <kind>      run echo through the backend (or argv-shape check for remote)\n  add <name> --kind <kind> [--image|--host|--user|--workspace|--app|--confiner ...]\n  use <profile>    set the profile as cfg.sandbox.default',
+  auth: 'Usage: lazyclaw auth <list <provider> | add <provider> <key> [--label <name>] | remove <provider> <label> | use <provider> <label> | rotate <provider>>\n  Multiple keys per provider for rate-limit rotation. The active label is sent on every chat / agent call.\n  `rotate` advances the cursor to the next label; pair with a 429 hook for auto-failover.',
+  pairing: 'Usage: lazyclaw pairing <list | add <id> [--label <name>] | remove <id>>\n  Sender allowlist for the messaging surface. Inbound senders not on this list are rejected.\n  Sender ids are opaque per-channel: Slack member id, Discord user id, phone number for SMS, etc.',
+  nodes: 'Usage: lazyclaw nodes <list | register <id> [--platform macos|ios|android|web|cli] [--label <name>] | remove <id>>\n  Companion device registration table. CLI only — the actual mobile / menu-bar apps are out of scope here.\n  Platform is free-form lower-case; future surfaces (iOS / Android nodes) authenticate against the daemon using these ids.',
+  message: 'Usage: lazyclaw message <list | add <name> <webhook-url> [--kind slack|discord|generic] | remove <name> | send <name> <text>>\n  Outbound webhook messaging — Slack / Discord Incoming Webhooks. Auto-detects kind from the URL pattern.\n  send accepts a literal string, or `-` to read the body from stdin.',
+  workspace: 'Usage: lazyclaw workspace <list | init <name> | show <name> [<file>] | remove <name> | path <name>>\n  Workspace = a directory under <configDir>/workspaces/<name>/ containing AGENTS.md, SOUL.md, TOOLS.md.\n  When `chat` or `agent` is invoked with --workspace <name>, the three files are stitched into a single system prompt at the head of the conversation. Missing files are skipped silently.\n  init scaffolds the three files with short stubs you replace.\n  show prints the composed prompt; show <name> AGENTS.md (etc) prints just one file.',
+  browse: 'Usage: lazyclaw browse <url> [--max-bytes <N>] [--timeout-ms <N>] [--user-agent <ua>] [--meta]\n  Fetches the URL and emits Markdown on stdout. Pipes cleanly into `agent`:\n      lazyclaw browse https://example.com/docs | lazyclaw agent -\n  Strips <script>/<style>/<svg>/comments, prefers <main>/<article>, falls back to <body>.\n  --max-bytes caps the body read (default 2 MB) so a misconfigured upstream can\'t OOM the process.\n  --meta prints { url, title, bytes, truncated } as JSON to stderr alongside the markdown on stdout.',
+  cron: 'Usage: lazyclaw cron <list | add <name> "<cron-spec>" -- <cmd> ... | remove <name> | show <name> | sync | run <name>>\n  Schedule recurring agent runs. macOS uses launchd (~/Library/LaunchAgents/com.lazyclaw.<name>.plist); Linux / WSL uses the user crontab.\n  Cron spec is the standard 5-field form (minute hour dom month dow). Supports *, range a-b, list a,b,c, step */N.\n  add: pass the command after `--`. Typical use:\n      lazyclaw cron add daily-summary "0 9 * * 1-5" -- lazyclaw agent "Summarise today\'s TODOs"\n  list / show: read from cfg.cron[name] (config is the source of truth).\n  sync: re-installs every job in cfg.cron into the system scheduler — handy after a reinstall.\n  run: one-shot in-process execution of the named job; the OS scheduler does the same thing on its trigger.\n  Logs: ~/.lazyclaw/logs/cron-<name>.{out,err}.log (macOS launchd path).',
+  setup: 'Usage: lazyclaw setup [--skip-test] [--only <steps>] [--skip <steps>]\n  --only/--skip take a comma list of: provider verify channel workspace skill webhook orchestrator (e.g. --only channel re-runs just that step).\n  Hermes-style phased first-run wizard — get one clean chat working first,\n  then optionally add the rest. Walks through:\n    1. Provider + model + api-key (delegates to onboard --pick; ≥64k-context tip)\n    2. Verify the provider responds (1-token ping; --skip-test bypasses)\n    3. Optional channel / gateway (Slack / Telegram / Matrix / HTTP built in;\n       Discord / Email / Signal / Voice / WhatsApp via plugin packages)\n    4. Optional workspace init  (AGENTS.md / SOUL.md / TOOLS.md)\n    5. Optional skill bundle install from GitHub\n    6. Optional outbound webhook (Slack / Discord)\n    7. Optional multi-agent orchestration (planner + workers)\n  Each optional step takes Enter or "skip" to bypass. Re-runnable safely.\n  Also fires automatically on first run when `lazyclaw` is invoked with no config.',
+  dashboard: 'Usage: lazyclaw dashboard [--port <N>] [--no-open]\n  Launches the lazyclaw-only web UI on http://127.0.0.1:<port> (default 19600) and opens it in the default browser.\n  Wraps `lazyclaw daemon` + a static HTML; no Python / lazyclaude dashboard required.\n  See web/dashboard.html for the current tab set (v5: Chat / Sessions / Workflows / Skills / Providers / Rates / Metrics / Doctor / Config / Status / Agents / Teams / Tasks / Trainer / Recall / Sandbox / Channels).\n  --no-open keeps the browser closed (handy for SSH / headless / dev). The bound URL is always printed to stdout.',
+  orchestrator: 'Usage: lazyclaw orchestrator <status | set-planner <provider[:model]> | workers add <spec> | workers remove <spec> | workers set <spec,spec,...> | workers clear | set-max-subtasks <N> | clear>\n  Read/write cfg.orchestrator without editing config.json by hand.\n  status               — print {planner, workers, maxSubtasks} as JSON; lists registered providers for reference.\n  set-planner          — replace the planner spec ("provider" or "provider:model"). "orchestrator" itself is rejected (self-recursion).\n  workers add          — append a worker (idempotent — duplicates skipped).\n  workers remove       — drop a worker by exact match. Idempotent.\n  workers set          — replace the whole list (comma-separated specs).\n  workers clear        — empty the workers list.\n  set-max-subtasks <N> — cap subtasks per request, clamped 1..10 (default 5).\n  clear                — delete the cfg.orchestrator block entirely.\n  Pair with: `lazyclaw config set provider orchestrator` to route chats through it.',
+};

package/commands/mcp.mjs

@@ -0,0 +1,150 @@
+// commands/mcp.mjs — `lazyclaw mcp <list|add|remove|call>`.
+//
+// MCP servers are stored in cfg.mcp.servers[] (stdio transport only; an entry
+// is { name, command, args[], env{}, allowGlob }). They are spawned at daemon
+// boot by mcp/server_spawn.startConfigured. This command manages that list and
+// lets you invoke a single tool from the CLI for a quick check.
+//
+// Verb dispatch + output convention mirror commands/agents.mjs cmdTeam:
+// success → JSON on stdout, usage/validation errors → console.error + exit 2,
+// operational failures → exit 1.
+
+import { readConfig, writeConfig } from '../lib/config.mjs';
+
+// The name becomes the tool namespace `mcp:<name>:<tool>`, so it must not carry
+// a colon or whitespace — reuse the cron/job name grammar.
+const NAME_RE = /^[A-Za-z0-9_.-]+$/;
+
+const emitJson = (o) => process.stdout.write(JSON.stringify(o, null, 2) + '\n');
+
+// `--args "-y pkg /tmp"` and `--env "K=V K2=V2"` arrive as one whitespace-
+// joined string (parseArgs consumes a single argv token), so split on spaces.
+function splitWords(raw) {
+  if (raw === undefined || raw === null || raw === true) return [];
+  return String(raw).split(/\s+/).filter(Boolean);
+}
+function parseEnv(raw) {
+  const env = {};
+  for (const pair of splitWords(raw)) {
+    const i = pair.indexOf('=');
+    if (i > 0) env[pair.slice(0, i)] = pair.slice(i + 1);
+  }
+  return env;
+}
+
+export async function cmdMcp(sub, positional = [], flags = {}) {
+  const cfg = readConfig();
+  const servers = (cfg.mcp && Array.isArray(cfg.mcp.servers)) ? cfg.mcp.servers : [];
+
+  switch (sub) {
+    case undefined:
+    case 'list': {
+      const configured = servers.map((s) => ({
+        name: s.name, command: s.command, args: s.args || [], allowGlob: s.allowGlob || '*',
+      }));
+      // listServers() reports servers connected in THIS process; the short-lived
+      // CLI never boots them, so this is normally empty — surfaced anyway so the
+      // same shape works when the command runs inside the daemon.
+      let connected = [];
+      try { connected = (await import('../mcp/client.mjs')).listServers(); }
+      catch { /* mcp client unavailable — report configured only */ }
+      emitJson({ ok: true, configured, connected });
+      return;
+    }
+
+    case 'add': {
+      const name = positional[0];
+      const command = flags.command;
+      if (!name || !command || command === true) {
+        console.error('Usage: lazyclaw mcp add <name> --command <cmd> [--args "<a b c>"] [--allow-glob <glob>] [--env "K=V ..."]');
+        process.exit(2);
+      }
+      if (!NAME_RE.test(name)) {
+        console.error(`mcp add: invalid name "${name}" — letters/digits/.-_ only (it becomes the tool namespace mcp:${name}:<tool>)`);
+        process.exit(2);
+      }
+      if (servers.find((s) => s.name === name)) {
+        console.error(`mcp add: server "${name}" already exists — remove it first or pick another name`);
+        process.exit(2);
+      }
+      const record = {
+        name,
+        command: String(command),
+        args: splitWords(flags.args),
+        allowGlob: (flags['allow-glob'] && flags['allow-glob'] !== true) ? String(flags['allow-glob']) : '*',
+      };
+      const env = parseEnv(flags.env);
+      if (Object.keys(env).length) record.env = env;
+      cfg.mcp = cfg.mcp || {};
+      cfg.mcp.servers = servers.concat([record]);
+      writeConfig(cfg);
+      emitJson({ ok: true, added: record });
+      return;
+    }
+
+    case 'remove':
+    case 'rm':
+    case 'delete': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw mcp remove <name>'); process.exit(2); }
+      if (!servers.find((s) => s.name === name)) {
+        console.error(`mcp remove: no configured server "${name}"`);
+        process.exit(2);
+      }
+      cfg.mcp = cfg.mcp || {};
+      cfg.mcp.servers = servers.filter((s) => s.name !== name);
+      writeConfig(cfg);
+      emitJson({ ok: true, removed: name });
+      return;
+    }
+
+    case 'call': {
+      const server = positional[0];
+      const toolName = positional[1];
+      if (!server || !toolName) {
+        console.error('Usage: lazyclaw mcp call <server> <tool> [--args-json \'{"k":"v"}\']');
+        process.exit(2);
+      }
+      const sconf = servers.find((s) => s.name === server);
+      if (!sconf) {
+        console.error(`mcp call: no configured server "${server}" — add it with 'lazyclaw mcp add ${server} --command <cmd>'`);
+        process.exit(2);
+      }
+      let args = {};
+      if (flags['args-json'] !== undefined && flags['args-json'] !== true) {
+        try { args = JSON.parse(String(flags['args-json'])); }
+        catch (e) { console.error(`mcp call: --args-json is not valid JSON: ${e.message}`); process.exit(2); }
+      }
+      const mcpClient = await import('../mcp/client.mjs');
+      const registry = await import('../mas/tools/registry.mjs');
+      let started = false;
+      try {
+        // sensitive:true — the same approval-gate invariant the daemon boot
+        // enforces (server_spawn). A CLI call can never downgrade an MCP tool.
+        await mcpClient.startServer({
+          name: sconf.name, command: sconf.command, args: sconf.args || [],
+          env: sconf.env || {}, allowGlob: sconf.allowGlob || '*', sensitive: true,
+        });
+        started = true;
+        const full = `mcp:${server}:${toolName}`;
+        const tool = registry.lookup(full);
+        if (!tool) {
+          const available = registry.listNames().filter((n) => n.startsWith(`mcp:${server}:`));
+          console.error(`mcp call: tool "${full}" not found. Available: ${available.join(', ') || '(none)'}`);
+          process.exit(1);
+        }
+        emitJson(await tool.exec(args));
+      } catch (e) {
+        console.error(`mcp call: ${e?.message || e}`);
+        process.exit(1);
+      } finally {
+        if (started) { try { await mcpClient.stopServer(server); } catch { /* best-effort */ } }
+      }
+      return;
+    }
+
+    default:
+      console.error('Usage: lazyclaw mcp <list|add|remove|call> ...');
+      process.exit(2);
+  }
+}

package/commands/misc.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { configPath } from '../lib/config.mjs';
 import { resolveSandbox, listBackends } from '../sandbox/index.mjs';
+import { pickAvailableConfiner } from '../sandbox/spawn.mjs';
 
 export async function cmdBrowse(url, flags = {}) {
   if (!url) { console.error('Usage: lazyclaw browse <url> [--max-bytes <N>] [--timeout-ms <N>] [--meta]'); process.exit(2); }
@@ -33,6 +34,25 @@ export async function cmdSandbox(args, flags = {}) {
     return 0;
   }
 
+  if (sub === 'status') {
+    // Show the EFFECTIVE default-on confinement posture for this host so the
+    // operator can audit what sensitive tools run under.
+    const cfg = _sandboxLoadConfigOrEmpty();
+    const sb = cfg.sandbox || {};
+    const off = sb.confine === false || sb.default === 'off' || sb.default === 'none';
+    const confiner = (sb.local && sb.local.confiner && sb.local.confiner !== 'auto')
+      ? sb.local.confiner
+      : pickAvailableConfiner();
+    const allowNet = sb.allowNet !== false;
+    process.stdout.write(`confinement: ${off ? 'OFF' : 'ON'} (default-on; opt out with cfg.sandbox.confine=false)\n`);
+    process.stdout.write(`host confiner: ${confiner}\n`);
+    process.stdout.write(`policy: writes → workspace + temp only · secret dirs unreadable · network ${allowNet ? 'allowed' : 'denied'}\n`);
+    if (!off && confiner === 'none') {
+      process.stdout.write('note: no OS confiner available on this host — sensitive tools run UNCONFINED. Install bubblewrap or firejail on Linux.\n');
+    }
+    return 0;
+  }
+
   if (sub === 'test') {
     const name = args[1];
     if (!name) { process.stderr.write('usage: lazyclaw sandbox test <kind|profile>\n'); return 2; }