lazyclaw 6.3.1 → 6.5.0

package/commands/sessions.mjs

@@ -7,6 +7,65 @@ import { ensureRegistry, getRegistry } from '../lib/registry_boot.mjs';
 
 const BUNDLE_VERSION = 1;
 
+// Key names that carry secrets. A bundle on a teammate's laptop must never
+// leak per-provider keys (cfg.authProfiles[<provider>][i].key, written by
+// providers/auth_store.mjs) or any other secret-bearing config value, not
+// just the legacy top-level cfg['api-key']. Match on the KEY name so we can
+// redact custom/nested entries without knowing the config schema ahead of
+// time, while leaving non-secret keys (baseUrl, model, label, …) untouched.
+const SECRET_KEY_RE = /(?:api[-_]?key|secret|token|password|authorization|access[-_]?key)/i;
+
+// Deep-clone cfg with every secret-bearing string value redacted. Pure — never
+// mutates the input. Preserves structure/labels so the bundle stays
+// inspectable (e.g. authProfiles keeps {label} but drops {key}).
+function redactSecrets(value, keyName = '') {
+  if (Array.isArray(value)) return value.map((v) => redactSecrets(v));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redactSecrets(v, k);
+    return out;
+  }
+  if (typeof value === 'string' && SECRET_KEY_RE.test(keyName)) return '***REDACTED***';
+  return value;
+}
+
+// Reciprocal of the export redaction: deep-clone cfg with every
+// '***REDACTED***' placeholder dropped, so importing a redacted bundle never
+// persists the literal placeholder string into config.json. Skipping the key
+// (rather than writing it) means an existing real value survives the default
+// "bundle wins" merge, and an authProfiles entry keeps its {label} slot minus
+// the secret. Symmetric with redactSecrets / redactAuthProfileKeys above.
+const REDACTED_PLACEHOLDER = '***REDACTED***';
+function stripRedacted(value) {
+  if (Array.isArray(value)) return value.map(stripRedacted);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (v === REDACTED_PLACEHOLDER) continue;   // drop the redacted key entirely
+      out[k] = stripRedacted(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// Redact the per-provider api keys in authProfiles. The field is literally
+// named `key` (not `apiKey`), so the generic key-name match above doesn't
+// catch it; handle it structurally instead. Keep `label` so the auth profile
+// shape stays inspectable. Operates on the already-cloned safeCfg.
+function redactAuthProfileKeys(safeCfg) {
+  const profiles = safeCfg.authProfiles;
+  if (!profiles || typeof profiles !== 'object') return safeCfg;
+  for (const provider of Object.keys(profiles)) {
+    const arr = profiles[provider];
+    if (!Array.isArray(arr)) continue;
+    profiles[provider] = arr.map((p) =>
+      p && typeof p === 'object' && 'key' in p ? { ...p, key: '***REDACTED***' } : p,
+    );
+  }
+  return safeCfg;
+}
+
 export async function cmdExport(flags) {
   // Portable bundle: config + every installed skill + (optionally) every
   // persisted session. Writes JSON to stdout so the caller pipes it
@@ -19,10 +78,9 @@ export async function cmdExport(flags) {
   const sessionsMod = await import('../sessions.mjs');
   const cfgDir = path.dirname(configPath());
   const cfg = readConfig();
-  const safeCfg = { ...cfg };
-  if (!flags['include-secrets']) {
-    if (safeCfg['api-key']) safeCfg['api-key'] = '***REDACTED***';
-  }
+  // redactSecrets deep-clones, so --include-secrets keeps the original cfg
+  // verbatim while the default path emits a fully redacted copy.
+  const safeCfg = flags['include-secrets'] ? cfg : redactAuthProfileKeys(redactSecrets(cfg));
   const skills = skillsMod.listSkills(cfgDir).map(s => ({
     name: s.name,
     content: skillsMod.loadSkill(s.name, cfgDir),
@@ -79,11 +137,13 @@ export async function cmdImport(flags) {
   // Config
   if (bundle.config && typeof bundle.config === 'object') {
     const existing = readConfig();
+    // Strip every redacted placeholder from the incoming config BEFORE the
+    // merge so the literal '***REDACTED***' is never persisted — at the
+    // top-level api-key, inside authProfiles[].key, or any nested secret.
+    const incoming = stripRedacted(bundle.config);
     const next = flags['no-overwrite-config']
-      ? { ...bundle.config, ...existing }    // existing wins
-      : { ...existing, ...bundle.config };   // bundle wins (default)
-    // Drop redacted secrets so we never write the placeholder string.
-    if (next['api-key'] === '***REDACTED***') delete next['api-key'];
+      ? { ...incoming, ...existing }    // existing wins
+      : { ...existing, ...incoming };   // bundle wins (default)
     writeConfig(next);
     stats.configKeys = Object.keys(bundle.config).length;
   }

package/commands/setup.mjs

@@ -15,7 +15,8 @@ import { SUBCOMMANDS, parseArgs, AGENT_REG_SUBS } from '../lib/args.mjs';
 import {
   _attachGhostAutocomplete, _fetchModelsForProvider, _pauseChatForSubMenu,
   _pickModelInteractive, _pickProviderInteractive, _printChatBanner,
-  _quickPrompt, _renderBanner, _renderV5Banner,
+  _quickPrompt, _quickPromptSecret, _renderBanner, _renderV5Banner,
+  _pickYesNo,
 } from '../tui/pickers.mjs';
 import { firstRunMode as _firstRunMode } from '../first_run.mjs';
 import { applyChatWindow as _applyChatWindow, CHAT_WINDOW_TURNS, CHAT_WINDOW_TOKEN_BUDGET } from '../chat_window.mjs';
@@ -24,6 +25,7 @@ import { dispatchSlash as _dispatchSlash, parseSlashLine as _parseSlashLine } fr
 import { SLASH_COMMANDS } from '../tui/slash_commands.mjs';
 import { runChannelStep, runWebhookStep, runOrchestratorStep, runContextStep } from './setup_channels.mjs';
 import { splashPropsForSetup, renderSplashToString } from '../tui/splash_props.mjs';
+import { HELP_SUMMARIES, HELP_DETAILS } from './help_text.mjs';
 
 function applyOnboardConfig(currentCfg, flags) {
   // Honors the OpenClaw-style unified provider/model string ("anthropic/claude-opus-4-7")
@@ -78,9 +80,13 @@ export async function cmdOnboard(flags) {
     const meta = (getRegistry().PROVIDER_INFO || {})[flags.provider] || {};
     if (meta.requiresApiKey && !flags['api-key']) {
       const prefix = meta.keyPrefix ? ` (starts with "${meta.keyPrefix}")` : '';
-      flags['api-key'] = (await ask(`api-key${prefix}: `)).trim();
+      // Close the line-mode reader before the masked raw-mode read so they
+      // don't both consume stdin. The key is masked (•) — never echoed.
+      rl.close();
+      flags['api-key'] = await _quickPromptSecret(`api-key${prefix}: `);
+    } else {
+      rl.close();
     }
-    rl.close();
   }
   const next = applyOnboardConfig(readConfig(), flags);
   if (!next.provider) { console.error('onboard: provider is required'); process.exit(2); }
@@ -92,79 +98,6 @@ export async function cmdOnboard(flags) {
 
 
 
-// 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.
-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.
-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]\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.',
-};
-
 export function cmdHelp(name) {
   if (!name) {
     process.stdout.write('lazyclaw — terminal AI assistant + workflow engine\n\n');
@@ -206,7 +139,16 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   const cfgDir = path.dirname(configPath());
   const colors = { accent, bold, dim, ok, warn };
 
+  // Per-step gating: `--only a,b` runs ONLY those; `--skip a,b` runs all but
+  // those. Steps: provider verify channel workspace skill webhook orchestrator.
+  // e.g. `lazyclaw setup --only channel` re-runs just the channel step.
+  const onlySet = flags.only ? new Set(String(flags.only).toLowerCase().split(',').map((s) => s.trim()).filter(Boolean)) : null;
+  const skipSet = new Set(String(flags.skip || '').toLowerCase().split(',').map((s) => s.trim()).filter(Boolean));
+  const want = (step) => (onlySet ? onlySet.has(step) : !skipSet.has(step));
+  let cfgAfterOnboard = cfg;
+
   // ── Step 1/7: Provider + model (mandatory) ──────────────────
+  if (want('provider')) {
   process.stdout.write(`  ${accent('Step 1/7 ·')} ${bold('Pick a provider + model')}\n`);
   process.stdout.write(`  ${dim('Opens the arrow-key picker. Tip: pick a model with ≥64k context — small windows can\'t hold multi-step tool-calling state.')}\n\n`);
   await _quickPrompt('  ▶ press Enter to open the picker ');
@@ -225,7 +167,7 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   // no provider set, bail out early — the rest of the wizard depends
   // on a provider being configured. `return` (not process.exit) so a
   // launcher caller can re-prompt or fall back gracefully.
-  const cfgAfterOnboard = readConfig();
+  cfgAfterOnboard = readConfig();
   if (!cfgAfterOnboard.provider) {
     process.stdout.write(`\n  ${warn('Setup not completed — provider was not configured.')}\n`);
     process.stdout.write(`  ${dim('Run `lazyclaw setup` again when ready, or pick "Onboard" from the menu for a single-step picker.')}\n\n`);
@@ -236,12 +178,14 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   // Context window — asked right after the model pick (optional; Enter keeps
   // defaults). Not a numbered step: it's part of the core model setup.
   await runContextStep({ prompt: _quickPrompt, colors });
+  }
 
   // ── Step 2/7: Verify one clean chat works ───────────────────
   // Hermes rule: get a clean reply before layering on channels/skills.
+  if (want('verify') && cfgAfterOnboard.provider) {
   process.stdout.write(`  ${accent('Step 2/7 ·')} ${bold('Verify the provider responds')}\n`);
   process.stdout.write(`  ${dim('Sends a 1-token "ping" via `lazyclaw providers test`. Confirm a clean reply before layering on channels/skills.')}\n\n`);
-  const wantPing = !flags['skip-test'] && (await _quickPrompt('  test now? [Y/n] ')).trim().toLowerCase() !== 'n';
+  const wantPing = !flags['skip-test'] && await _pickYesNo('Test the provider now?', { subtitle: 'sends a 1-token ping to confirm a clean reply', yesLabel: 'Test now', noLabel: 'Skip', defaultYes: true });
   if (wantPing) {
     try {
       // No-exit probe (providers/probe.mjs) — the CLI `providers test` calls
@@ -258,15 +202,20 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   } else {
     process.stdout.write(`  ${dim('— skipped —')}\n\n`);
   }
+  }
 
   // ── Step 3/7: Channel / gateway (optional) ──────────────────
+  if (want('channel')) {
   process.stdout.write(`  ${accent('Step 3/7 ·')} ${bold('Where will you run it?')} ${dim('(optional)')}\n`);
   await runChannelStep({ cfgDir, prompt: _quickPrompt, colors });
+  }
 
   // ── Step 4/7: Optional workspace ────────────────────────────
+  if (want('workspace')) {
   process.stdout.write(`  ${accent('Step 4/7 ·')} ${bold('Initialise a workspace?')} ${dim('(optional)')}\n`);
   process.stdout.write(`  ${dim('A workspace is a folder of AGENTS.md / SOUL.md / TOOLS.md prompt files that auto-inject into chat / agent. Skip if you don\'t need project-specific personas yet.')}\n\n`);
-  const wsName = (await _quickPrompt('  workspace name (Enter to skip): ')).trim();
+  const wantWs = await _pickYesNo('Initialise a workspace?', { yesLabel: 'Create one', noLabel: 'Skip', defaultYes: false });
+  const wsName = wantWs ? (await _quickPrompt('  workspace name: ')).trim() : '';
   if (wsName && /^[A-Za-z0-9_.-]+$/.test(wsName)) {
     try {
       const ws = await import('../workspace.mjs');
@@ -281,11 +230,14 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   } else {
     process.stdout.write(`  ${dim('— skipped —')}\n\n`);
   }
+  }
 
   // ── Step 5/7: Optional skill bundle install ─────────────────
+  if (want('skill')) {
   process.stdout.write(`  ${accent('Step 5/7 ·')} ${bold('Install a skill bundle from GitHub?')} ${dim('(optional)')}\n`);
   process.stdout.write(`  ${dim('Format: <user>/<repo>[@<ref>]. Skills are .md prompt fragments that compose into the system prompt via --skill.')}\n\n`);
-  const skillSpec = (await _quickPrompt('  github spec (Enter to skip): ')).trim();
+  const wantSkill = await _pickYesNo('Install a skill bundle from GitHub?', { yesLabel: 'Install one', noLabel: 'Skip', defaultYes: false });
+  const skillSpec = wantSkill ? (await _quickPrompt('  github spec (<user>/<repo>[@<ref>]): ')).trim() : '';
   if (skillSpec) {
     try {
       const inst = await import('../skills_install.mjs');
@@ -302,14 +254,19 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   } else {
     process.stdout.write(`  ${dim('— skipped —')}\n\n`);
   }
+  }
 
   // ── Step 6/7: Optional outbound webhook ─────────────────────
+  if (want('webhook')) {
   process.stdout.write(`  ${accent('Step 6/7 ·')} ${bold('Add an outbound webhook?')} ${dim('(optional)')}\n`);
   await runWebhookStep({ prompt: _quickPrompt, colors });
+  }
 
   // ── Step 7/7: Optional multi-agent orchestration ────────────
+  if (want('orchestrator')) {
   process.stdout.write(`  ${accent('Step 7/7 ·')} ${bold('Enable multi-agent orchestration?')} ${dim('(optional)')}\n`);
   await runOrchestratorStep({ prompt: _quickPrompt, colors });
+  }
 
   // ── Wrap up ─────────────────────────────────────────────────
   process.stdout.write('\n');
@@ -319,6 +276,13 @@ export async function cmdSetup(_sub, _positional, flags = {}) {
   process.stdout.write(`    ${dim('•')} lazyclaw agent "..."          ${dim('— one-shot prompt')}\n`);
   process.stdout.write(`    ${dim('•')} lazyclaw doctor              ${dim('— diagnostic JSON')}\n`);
   process.stdout.write(`    ${dim('•')} lazyclaw setup               ${dim('— re-run this wizard any time')}\n\n`);
+
+  // Release stdin so `lazyclaw setup` returns to the shell instead of hanging
+  // at "Setup complete". The interactive prompts (_arrowMenu / _quickPrompt)
+  // resume()+ref() stdin to read input; without an unref the ref'd handle keeps
+  // the event loop alive after the last step. When setup is invoked from the
+  // launcher, the next menu resume()+ref()s stdin again, so this is safe there.
+  try { if (process.stdin.unref) process.stdin.unref(); } catch { /* best-effort */ }
 }
 
 // First-run welcome panel + delegated onboard. Drawn once before the