lazyclaw 6.0.0 → 6.1.0

package/lib/args.mjs

@@ -0,0 +1,216 @@
+// CLI argument parsing + shell-completion generation, extracted from cli.mjs.
+// Pure leaf module: no imports, no side effects — just the subcommand inventory
+// and the parseArgs/completion functions that main() and `lazyclaw completion`
+// share.
+
+// Subcommand inventory used by `lazyclaw completion`. Single source of
+// truth so adding a subcommand updates the completion script too. The
+// dispatcher in main() is the runtime authority; this list mirrors it.
+export const SUBCOMMANDS = [
+  'run', 'resume', 'inspect', 'clear', 'validate', 'graph',
+  'config', 'chat', 'agent',
+  'doctor', 'status', 'onboard',
+  'sessions', 'skills', 'providers',
+  'daemon', 'version', 'completion', 'help',
+  'export', 'import',
+  'rates',
+  // v5.0 — sandbox 6-backend (Phase D)
+  'sandbox',
+  // OpenClaw-parity subsurfaces (v3.93–v3.98)
+  'auth', 'pairing', 'nodes', 'message', 'workspace', 'browse', 'cron',
+  // v3.99.6 — multi-step setup wizard + lazyclaw-only dashboard
+  'setup', 'dashboard',
+  // v3.99.22 — multi-agent orchestrator config
+  'orchestrator',
+  // v3.99.30 — /loop and /goal slash commands (in-session + detached)
+  'loop', 'loops', 'goal', 'memory',
+  // v4.0.0 — Slack Socket Mode listener (inbound DM / @-mention)
+  'slack',
+  // v4.3.0 — Telegram long-poll listener (zero-install mobile control)
+  'telegram',
+  // v4.3.0 — Matrix /sync long-poll listener
+  'matrix',
+  // v5.0 — channels plugin loader (Phase F)
+  'channels',
+  // v4.1.0 — multi-agent slack system (Phase 9+)
+  'agent', 'team', 'task',
+  // v5.0 Phase G — persona compose + cross-tool import (spec §9, §10)
+  'personality', 'migrate', 'hermes', 'openclaw',
+  // v5.0.6 — arrow-key launcher menu (was the no-arg default in v5.0.5-)
+  'menu',
+  // v5.0 Phase H1 — trajectory exporter (spec §2.7)
+  'trajectories',
+];
+
+export const SUBCOMMAND_SUBS = {
+  config:    ['get', 'set', 'list', 'delete', 'unset', 'path', 'edit', 'validate'],
+  sessions:  ['list', 'show', 'clear', 'export', 'search'],
+  skills:    ['list', 'show', 'install', 'remove', 'search', 'curate', 'classify'],
+  providers: ['list', 'info', 'test', 'add', 'remove', 'models'],
+  rates:     ['list', 'set', 'delete', 'shape', 'validate', 'copy'],
+  sandbox:   ['list', 'test', 'add', 'use'],
+  completion: ['bash', 'zsh'],
+  auth:      ['list', 'add', 'remove', 'use', 'rotate'],
+  pairing:   ['list', 'add', 'remove'],
+  nodes:     ['list', 'register', 'remove', 'pending', 'approve', 'revoke', 'devices'],
+  message:   ['list', 'add', 'remove', 'send'],
+  workspace: ['list', 'init', 'show', 'remove', 'path'],
+  cron:      ['list', 'add', 'remove', 'show', 'sync', 'run'],
+  orchestrator: ['status', 'set-planner', 'workers', 'set-max-subtasks', 'clear'],
+  loops:     ['list', 'show', 'kill', 'tail'],
+  goal:      ['add', 'list', 'show', 'close', 'switch', 'tick', 'channel'],
+  memory:    ['show', 'dream', 'edit'],
+  slack:     ['listen'],
+  telegram:  ['listen'],
+  matrix:    ['listen'],
+  agent:     ['add', 'list', 'show', 'edit', 'remove'],
+  team:      ['add', 'list', 'show', 'edit', 'remove'],
+  task:      ['start', 'list', 'show', 'abandon', 'done', 'remove'],
+  trajectories: ['export'],
+};
+
+// Flags whose presence is the signal — they don't consume the next arg
+// even when one is available. Without this allow-list,
+// `lazyclaw run --parallel demo wf.mjs` would set `flags.parallel='demo'`
+// and silently lose the session id; the user would only see a
+// "missing positional" error after the dispatcher rejected it.
+export const BOOLEAN_FLAGS = new Set([
+  'parallel',
+  'parallel-persistent',
+  'once',
+  'non-interactive',
+  'include-secrets',
+  'include-sessions',
+  'overwrite-skills',
+  'no-overwrite-config',
+  'import-sessions',
+  'show-thinking',
+  'usage',
+  'cost',
+  'response-cache',
+  'help',         // also handled as a subcommand alias
+  'version',
+  'summary',      // inspect: trim per-node detail
+  'regex',        // sessions search: treat query as a regex
+  'lr',           // graph: emit Mermaid `graph LR` (left-right)
+  'force',        // rates copy: overwrite existing destination
+  'aggregate',    // inspect (list mode): per-node stats across sessions
+  'all',          // providers test: run all providers in parallel
+  'with-turn-count', // sessions list: include turn count per session
+  'no-probe',     // providers add: skip the /v1/models reachability probe
+  'pick',         // onboard / chat: force the interactive picker even when provider already set
+  'detach',       // loop: fork worker and return immediately
+  'use-memory',   // loop: prepend core memory to each iteration
+  'force',        // goal tick --force: bypass schedule when invoked manually
+]);
+
+export function parseArgs(argv) {
+  const out = { positional: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    // POSIX `--`: everything after is positional verbatim. Used by
+    // `cron add <name> "<spec>" -- <cmd> [args...]` so a recurring
+    // command with --flag of its own doesn't get parsed as our flag.
+    if (a === '--') {
+      for (let j = i + 1; j < argv.length; j++) out.positional.push(argv[j]);
+      break;
+    }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq >= 0) {
+        out.flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const name = a.slice(2);
+        if (BOOLEAN_FLAGS.has(name)) {
+          // Known boolean — never consumes the next arg.
+          out.flags[name] = true;
+          continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          // Unknown flag at end-of-args or before another --flag: still boolean.
+          out.flags[name] = true;
+        } else {
+          out.flags[name] = next;
+          i += 1;
+        }
+      }
+    } else out.positional.push(a);
+  }
+  return out;
+}
+
+export function bashCompletion() {
+  // Standard bash COMPREPLY pattern. We split COMP_WORDS into:
+  //   [0] = lazyclaw, [1] = subcommand, [2+] = subcommand args.
+  // Two-level completion: word index 1 → top subcommands; index 2 → the
+  // sub-subcommand list (if defined for that subcommand). Beyond index 2
+  // we don't try to enumerate dynamic items (session ids etc.) — that
+  // would require running the CLI on every <Tab>, which is too slow.
+  const subs = SUBCOMMANDS.join(' ');
+  const subSubsCases = Object.entries(SUBCOMMAND_SUBS)
+    .map(([name, list]) => `      ${name})\n        COMPREPLY=( $(compgen -W "${list.join(' ')}" -- "$cur") )\n        ;;`)
+    .join('\n');
+  return `# lazyclaw bash completion. Source from your shell:
+#   eval "$(node /path/to/cli.mjs completion bash)"
+_lazyclaw_completion() {
+  local cur prev words cword
+  _init_completion 2>/dev/null || {
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    cword=$COMP_CWORD
+  }
+  if [ "$cword" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${subs}" -- "$cur") )
+    return 0
+  fi
+  if [ "$cword" -eq 2 ]; then
+    case "\${COMP_WORDS[1]}" in
+${subSubsCases}
+    esac
+    return 0
+  fi
+  return 0
+}
+complete -F _lazyclaw_completion lazyclaw
+`;
+}
+
+export function zshCompletion() {
+  // _arguments-style. We list subcommands then dispatch on the first
+  // positional via a single `_describe`. Sub-subcommands handled by a
+  // case inside the function. Same coverage rationale as bash.
+  const subs = SUBCOMMANDS.map(s => `    '${s}'`).join('\n');
+  const subSubsCases = Object.entries(SUBCOMMAND_SUBS)
+    .map(([name, list]) => `      (${name}) _values 'sub' ${list.map(v => `'${v}'`).join(' ')} ;;`)
+    .join('\n');
+  return `#compdef lazyclaw
+# lazyclaw zsh completion. Add to fpath, or eval inline:
+#   eval "$(node /path/to/cli.mjs completion zsh)"
+_lazyclaw() {
+  local subs=(
+${subs}
+  )
+  if (( CURRENT == 2 )); then
+    _values 'subcommand' \${subs[@]}
+    return
+  fi
+  if (( CURRENT == 3 )); then
+    case \${words[2]} in
+${subSubsCases}
+    esac
+    return
+  fi
+}
+compdef _lazyclaw lazyclaw
+_lazyclaw "$@"
+`;
+}
+
+// Subcommand-classifier sets for the multi-agent surfaces. cli.mjs uses
+// AGENT_REG_SUBS to decide whether a bare `agent <sub>` routes to the agent
+// registry vs a one-shot agent run. TEAM_SUBS/TASK_SUBS mirror their command's
+// subcommands for the same disambiguation pattern.
+export const AGENT_REG_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete', 'memory', 'reflect', 'skill-synth']);
+export const TEAM_SUBS = new Set(['add', 'list', 'show', 'edit', 'remove', 'rm', 'delete']);
+export const TASK_SUBS = new Set(['start', 'tick', 'list', 'show', 'abandon', 'done', 'transcript', 'remove', 'rm', 'delete']);

package/lib/config.mjs

@@ -0,0 +1,113 @@
+// Shared config + key/url resolution helpers, extracted from cli.mjs so the
+// per-domain command modules (commands/*.mjs) can import them without pulling
+// in the whole entrypoint. Leaf module: depends only on node builtins and the
+// owner-only secure writer — never on the provider registry (the registry
+// dependency is injected via setRegistryEnvResolver to keep this a leaf and
+// avoid a config<->registry_boot import cycle).
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+// Owner-only (0600/0700) atomic writer for config.json — it holds plaintext
+// API keys / auth profiles and must not be group/other readable.
+import { writeJsonSecure, tightenIfLoose } from '../secure_write.mjs';
+
+export function configPath() {
+  const override = process.env.LAZYCLAW_CONFIG_DIR;
+  const dir = override ? override : path.join(os.homedir(), '.lazyclaw');
+  return path.join(dir, 'config.json');
+}
+
+export function readConfig() {
+  const p = configPath();
+  if (!fs.existsSync(p)) return {};
+  // Migrate already-deployed world/group-readable config.json (plaintext keys)
+  // to 0600 the first time we touch it. Best-effort, idempotent.
+  tightenIfLoose(p);
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return {}; }
+}
+
+export function writeConfig(cfg) {
+  // 0600 file in a 0700 dir, atomically — config.json stores plaintext API
+  // keys / auth profiles, so it must be owner-only on disk.
+  writeJsonSecure(configPath(), cfg);
+}
+
+// Injected built-in OpenAI-compat env-var resolver. registry_boot wires this
+// to registry.resolveBuiltinEnvKey on ensureRegistry() so _resolveAuthKey can
+// fall back to provider env vars without importing the registry (no cycle).
+let _envResolver = null;
+export function setRegistryEnvResolver(fn) { _envResolver = fn; }
+
+// Synchronous, dependency-free resolver for the api-key the
+// chat / agent flow sends. Mirrors config_features.resolveApiKey
+// without forcing the dynamic import on every hot-path call.
+//   1. cfg.authProfiles[provider] active label, if set
+//   2. first profile in the array
+//   3. customProviders[<provider>].apiKey (custom OpenAI-compat entries)
+//   4. PROVIDER_INFO[<provider>].envKey / altEnvKeys env var (built-in
+//      OpenAI-compat: nim → NVIDIA_API_KEY, openrouter → OPENROUTER_API_KEY, …)
+//   5. legacy single `cfg["api-key"]` (pre-v3.93 configs)
+export function _resolveAuthKey(cfg, provider) {
+  const arr = (cfg.authProfiles || {})[provider] || [];
+  const active = (cfg.authActiveProfile || {})[provider];
+  const hit = arr.find((p) => p && p.label === active) || arr[0];
+  if (hit?.key) return hit.key;
+  const custom = Array.isArray(cfg.customProviders)
+    ? cfg.customProviders.find((p) => p && p.name === provider)
+    : null;
+  if (custom?.apiKey) return custom.apiKey;
+  // Built-in OpenAI-compat env var fallback. Skipped silently when the
+  // registry module isn't loaded yet (every chat / agent path calls
+  // ensureRegistry() before _resolveAuthKey, so this is just defence-in-depth).
+  if (typeof _envResolver === 'function') {
+    const envHit = _envResolver(provider);
+    if (envHit) return envHit;
+  }
+  return cfg['api-key'] || '';
+}
+
+// Per-provider base-URL override (used by tests + private gateways).
+// Single source of truth — the reflect / skill-synth / task-tick paths
+// all resolve through here so a new provider's env var lands in one spot.
+export function _resolveBaseUrl(provider) {
+  return {
+    anthropic: process.env.LAZYCLAW_ANTHROPIC_BASE_URL,
+    openai:    process.env.LAZYCLAW_OPENAI_BASE_URL,
+    gemini:    process.env.LAZYCLAW_GEMINI_BASE_URL,
+  }[provider] || undefined;
+}
+
+export function readVersionFromRepo() {
+  // Two source-of-truth lookups, in order:
+  //   1. The npm-published package's own package.json (sits next to the
+  //      entrypoint once installed via `npm i -g lazyclaw`).
+  //   2. The monorepo's VERSION file at the repo root (one or two
+  //      levels up depending on how the file is symlinked / copied).
+  // Either one wins on first hit. Falls back to '0.0.0' so the CLI
+  // never crashes on a stripped-down install. The candidate list is a
+  // superset spanning both the repo-root entrypoint and this lib/ module
+  // location so resolution is identical regardless of where it runs from.
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  const candidates = [
+    { kind: 'pkg',     path: path.resolve(here, './package.json') },
+    { kind: 'pkg',     path: path.resolve(here, '../package.json') },
+    { kind: 'pkg',     path: path.resolve(here, '../../package.json') },
+    { kind: 'version', path: path.resolve(here, '../../VERSION') },
+    { kind: 'version', path: path.resolve(here, '../../../VERSION') },
+    { kind: 'version', path: path.resolve(here, '../../../../VERSION') },
+  ];
+  for (const c of candidates) {
+    try {
+      const raw = fs.readFileSync(c.path, 'utf8').trim();
+      if (!raw) continue;
+      if (c.kind === 'pkg') {
+        const v = JSON.parse(raw).version;
+        if (v) return v;
+      } else {
+        return raw;
+      }
+    } catch { /* keep trying */ }
+  }
+  return '0.0.0';
+}

package/lib/gateway_guard.mjs

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

package/lib/inbound_client.mjs

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

package/lib/registry_boot.mjs

@@ -0,0 +1,55 @@
+// Provider-registry bootstrap, extracted from cli.mjs so every command module
+// (commands/*.mjs) shares one lazily-loaded registry instance instead of each
+// re-importing and re-registering. One-directional dependency: registry_boot
+// -> config (never the reverse), so this stays cycle-free.
+import { readConfig, _resolveAuthKey, setRegistryEnvResolver } from './config.mjs';
+
+let _registryMod = null;
+
+// Throwing accessor — use when the caller has already awaited ensureRegistry()
+// and a null registry would be a programmer error.
+export function requireRegistry() {
+  if (!_registryMod) {
+    throw new Error('registry module not pre-loaded — call ensureRegistry() first');
+  }
+  return _registryMod;
+}
+
+// Nullable accessor — returns the loaded registry module or null. Mirrors the
+// old bare `_registryMod` read semantics for sites that tolerate "not loaded".
+export function getRegistry() {
+  return _registryMod;
+}
+
+export async function ensureRegistry() {
+  if (!_registryMod) {
+    _registryMod = await import('../providers/registry.mjs');
+    // Wire config._resolveAuthKey's built-in env-var fallback to the registry
+    // without config importing the registry (keeps config a leaf module).
+    if (typeof _registryMod.resolveBuiltinEnvKey === 'function') {
+      setRegistryEnvResolver((p) => _registryMod.resolveBuiltinEnvKey(p));
+    }
+  }
+  // Re-run registration on every call so config changes within the same
+  // process (e.g. setup wizard adding a custom endpoint mid-session) take
+  // effect for the next chat / agent / picker invocation. registerCustom-
+  // Providers is idempotent — re-registering the same name is a no-op.
+  try {
+    if (typeof _registryMod.registerCustomProviders === 'function') {
+      _registryMod.registerCustomProviders(readConfig());
+    }
+  } catch { /* never let a malformed cfg.customProviders block startup */ }
+  // Wire the orchestrator's live cfg + auth-key resolver. We do this on
+  // every ensureRegistry() call (cheap — just replaces the closure) so a
+  // mid-session config edit (custom provider added, env var exported)
+  // takes effect on the next orchestrator turn without a restart.
+  try {
+    if (typeof _registryMod.registerOrchestrator === 'function') {
+      _registryMod.registerOrchestrator({
+        cfgGetter: readConfig,
+        keyResolver: _resolveAuthKey,
+      });
+    }
+  } catch { /* defensive */ }
+  return _registryMod;
+}