lazyclaw 6.3.1 → 6.4.0

package/commands/setup_channels.mjs

@@ -9,12 +9,20 @@
 // and the dashboard read. Plugin channels are recorded the same way with an
 // honest "needs a plugin package" notice — we never pretend a channel works
 // when it requires an uninstalled package or an external binary.
+import fs from 'node:fs';
+import path from 'node:path';
 import { readConfig, writeConfig } from '../lib/config.mjs';
 import { writeDotenvMerge } from '../dotenv_min.mjs';
 import { messageAdd } from '../config_features.mjs';
 
 // fields[].key is the answer key; .env is the env var it maps to; .secret
 // masks it on echo; .optional lets the user skip it.
+//
+// The five non-builtin channels are NOT separate npm packages — they ship
+// IN-TREE under channels-<name>/ and the gateway runs them directly. What they
+// need is a RUNTIME dependency: an npm package (`deps`) installed into the
+// config dir, or an external `binary` on PATH. (The old catalog pointed at
+// unpublished `@lazyclaw/channel-*` packages, so `channels install` 404'd.)
 export const CHANNEL_CATALOG = [
   { name: 'slack',    builtin: true,  label: 'Slack',
     fields: [
@@ -30,29 +38,62 @@ export const CHANNEL_CATALOG = [
       { key: 'userId',     env: 'MATRIX_USER_ID', prompt: 'User id (@you:matrix.org)' },
     ] },
   { name: 'http',     builtin: true,  label: 'HTTP (generic inbound endpoint)', fields: [] },
-  { name: 'discord',  builtin: false, plugin: '@lazyclaw/channel-discord', label: 'Discord',
+  { name: 'discord',  builtin: false, deps: ['discord.js'], label: 'Discord',
     fields: [{ key: 'token', env: 'DISCORD_BOT_TOKEN', prompt: 'Bot token', secret: true }] },
-  { name: 'email',    builtin: false, plugin: '@lazyclaw/channel-email', label: 'Email (IMAP/SMTP)',
+  { name: 'email',    builtin: false, deps: ['node-imap', 'nodemailer', 'mailparser'], label: 'Email (IMAP/SMTP)',
     fields: [
       { key: 'host', env: 'EMAIL_IMAP_HOST', prompt: 'IMAP host' },
       { key: 'user', env: 'EMAIL_IMAP_USER', prompt: 'IMAP user' },
       { key: 'pass', env: 'EMAIL_IMAP_PASS', prompt: 'IMAP password', secret: true },
     ] },
-  { name: 'signal',   builtin: false, plugin: '@lazyclaw/channel-signal', label: 'Signal (needs signal-cli)',
+  { name: 'signal',   builtin: false, binary: 'signal-cli', label: 'Signal (needs signal-cli)',
     fields: [{ key: 'account', env: 'SIGNAL_ACCOUNT', prompt: 'Signal account (+15551234567)' }] },
-  { name: 'voice',    builtin: false, plugin: '@lazyclaw/channel-voice', label: 'Voice (Whisper transcription)',
+  { name: 'voice',    builtin: false, deps: [], label: 'Voice (Whisper transcription)',
     fields: [{ key: 'apiKey', env: 'OPENAI_API_KEY', prompt: 'OpenAI API key (whisper)', secret: true }] },
-  { name: 'whatsapp', builtin: false, plugin: '@lazyclaw/channel-whatsapp', label: 'WhatsApp (web session)',
+  { name: 'whatsapp', builtin: false, deps: ['whatsapp-web.js', 'qrcode-terminal'], label: 'WhatsApp (web session)',
     fields: [] },
 ];
 
+// Is a runtime npm dep installed into <cfgDir>/node_modules? (the in-tree
+// adapter resolves it from there; see commands/gateway.mjs _loadPluginChannel).
+export function depInstalled(dep, cfgDir) {
+  if (!cfgDir) return false;
+  return fs.existsSync(path.join(cfgDir, 'node_modules', dep, 'package.json'));
+}
+
+// Is an external binary on PATH? (signal needs signal-cli.)
+export function binaryOnPath(bin) {
+  const PATH = process.env.PATH || '';
+  const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  for (const dir of PATH.split(path.delimiter).filter(Boolean)) {
+    for (const ext of exts) {
+      try { if (fs.existsSync(path.join(dir, bin + ext))) return true; } catch { /* skip */ }
+    }
+  }
+  return false;
+}
+
+// Can this channel actually run right now? Builtins always; in-tree channels
+// only once their runtime dep (npm package) / external binary is present.
+// Returns { ready, missingDeps:[], missingBinary:null }.
+export function channelReadiness(name, cfgDir) {
+  const spec = channelByName(name);
+  if (!spec) return { ready: false, missingDeps: [], missingBinary: null };
+  if (spec.builtin) return { ready: true, missingDeps: [], missingBinary: null };
+  const missingDeps = (spec.deps || []).filter((d) => !depInstalled(d, cfgDir));
+  const missingBinary = spec.binary && !binaryOnPath(spec.binary) ? spec.binary : null;
+  return { ready: missingDeps.length === 0 && !missingBinary, missingDeps, missingBinary };
+}
+
 export function channelByName(name) {
   return CHANNEL_CATALOG.find((c) => c.name === name) || null;
 }
 
-// Pure: turn collected answers into { envVars, channelConfig, needsPlugin }.
-// Empty/whitespace answers are dropped so a skipped optional field doesn't
-// write an empty env var.
+// Pure: turn collected answers into { envVars, deps, binary, builtin }. Empty/
+// whitespace answers are dropped so a skipped optional field doesn't write an
+// empty env var. `deps`/`binary` describe the runtime requirement the in-tree
+// channel needs to actually run (replaces the old, unpublished `@lazyclaw/
+// channel-*` plugin pointer).
 export function buildChannelEntry(name, answers = {}) {
   const spec = channelByName(name);
   if (!spec) throw new Error(`unknown channel: ${name}`);
@@ -63,8 +104,9 @@ export function buildChannelEntry(name, answers = {}) {
   }
   return {
     envVars,
-    channelConfig: { enabled: true },
-    needsPlugin: spec.builtin ? null : spec.plugin,
+    builtin: !!spec.builtin,
+    deps: spec.deps || [],
+    binary: spec.binary || null,
   };
 }
 
@@ -78,9 +120,17 @@ export function persistChannel(cfgDir, name, answers) {
   if (Object.keys(entry.envVars).length) writeDotenvMerge(cfgDir, entry.envVars);
   const cfg = readConfig();
   cfg.channels = cfg.channels && typeof cfg.channels === 'object' ? cfg.channels : {};
-  cfg.channels[name] = { ...(cfg.channels[name] || {}), ...entry.channelConfig };
+  // Don't mark a channel enabled until it can actually run — a plugin channel
+  // whose runtime dep / binary is still missing is recorded but left disabled
+  // (with the missing requirement) so the gateway never tries (and fails) to
+  // start it. `channels enable <name>` flips it once the dep is installed.
+  const r = channelReadiness(name, cfgDir);
+  const section = { ...(cfg.channels[name] || {}), enabled: r.ready };
+  if (!r.ready) section.pending = { deps: r.missingDeps, binary: r.missingBinary };
+  else delete section.pending;
+  cfg.channels[name] = section;
   writeConfig(cfg);
-  return entry;
+  return { ...entry, ready: r.ready, missingDeps: r.missingDeps, missingBinary: r.missingBinary };
 }
 
 const mask = (v) => {
@@ -88,48 +138,153 @@ const mask = (v) => {
   return s.length <= 4 ? '••••' : `${s.slice(0, 3)}…${s.slice(-2)}`;
 };
 
-// Interactive channel step. `prompt(label)` resolves to a trimmed string;
-// `write(text)` sinks UI output (defaults to process.stdout). Returns
-// { skipped, channel?, needsPlugin? }. Never echoes a secret field value.
-export async function runChannelStep({ cfgDir, prompt, colors, write = (s) => process.stdout.write(s) }) {
-  const { dim, ok, warn } = colors;
-  const list = CHANNEL_CATALOG.map((c) => `${c.name}${c.builtin ? '' : ' *'}`).join(' · ');
-  write(`  ${dim('Where will you talk to the agent? Built-in: slack/telegram/matrix/http. (* = needs a plugin package.)')}\n`);
-  write(`  ${dim(list)}\n\n`);
-  const pick = (await prompt('  channel (Enter to skip): ')).trim().toLowerCase();
-  if (!pick) { write(`  ${dim('— skipped —')}\n\n`); return { skipped: true }; }
-  const spec = channelByName(pick);
-  if (!spec) { write(`  ${warn('skipped:')} unknown channel "${pick}"\n\n`); return { skipped: true }; }
+// Verify a channel's stored credentials with a cheap live call (Slack
+// auth.test, Telegram getMe, Matrix whoami). Reads creds from `env` (defaults
+// to process.env — load the .env first). Returns { ok, detail, hint }:
+// ok=true verified, ok=false rejected/unreachable (hint = how to fix),
+// ok=null when the channel has no verifiable endpoint (http/plugins). Pure
+// w.r.t. config; fetch is injectable for tests.
+export async function verifyChannel(name, { env = process.env, fetchImpl } = {}) {
+  const f = fetchImpl || globalThis.fetch;
+  const spec = channelByName(name);
+  if (!spec) return { ok: false, detail: `unknown channel "${name}"`, hint: '' };
+  const need = (envVar) => env[envVar] || '';
+  try {
+    if (name === 'slack') {
+      const token = need('SLACK_BOT_TOKEN');
+      if (!token) return { ok: false, detail: 'no SLACK_BOT_TOKEN set', hint: 'set it with /channels slack setup' };
+      const base = env.SLACK_API_BASE || 'https://slack.com/api';
+      const res = await f(`${base}/auth.test`, { method: 'POST', headers: { authorization: `Bearer ${token}` } });
+      const j = await res.json().catch(() => ({}));
+      return j && j.ok
+        ? { ok: true, detail: `team=${j.team || '?'} user=${j.user || '?'}`, hint: '' }
+        : { ok: false, detail: `Slack rejected the token (${j && j.error ? j.error : 'auth.test failed'})`, hint: 'check SLACK_BOT_TOKEN via /channels slack setup' };
+    }
+    if (name === 'telegram') {
+      const token = need('TELEGRAM_BOT_TOKEN');
+      if (!token) return { ok: false, detail: 'no TELEGRAM_BOT_TOKEN set', hint: 'set it with /channels telegram setup' };
+      const res = await f(`https://api.telegram.org/bot${token}/getMe`);
+      const j = await res.json().catch(() => ({}));
+      return j && j.ok
+        ? { ok: true, detail: `@${(j.result && j.result.username) || '?'}`, hint: '' }
+        : { ok: false, detail: `Telegram rejected the token (${j && j.description ? j.description : 'getMe failed'})`, hint: 'check TELEGRAM_BOT_TOKEN via /channels telegram setup' };
+    }
+    if (name === 'matrix') {
+      const hs = need('MATRIX_HOMESERVER');
+      const token = need('MATRIX_ACCESS_TOKEN');
+      if (!hs || !token) return { ok: false, detail: 'no MATRIX_HOMESERVER / MATRIX_ACCESS_TOKEN set', hint: 'set them with /channels matrix setup' };
+      const res = await f(`${hs.replace(/\/$/, '')}/_matrix/client/v3/account/whoami`, { headers: { authorization: `Bearer ${token}` } });
+      const j = await res.json().catch(() => ({}));
+      return res.ok && j && j.user_id
+        ? { ok: true, detail: j.user_id, hint: '' }
+        : { ok: false, detail: 'Matrix rejected the token', hint: 'check MATRIX_ACCESS_TOKEN via /channels matrix setup' };
+    }
+    return { ok: null, detail: `no live verification for "${name}"`, hint: '' };
+  } catch (e) {
+    return { ok: false, detail: `could not reach ${name}: ${e && e.message ? e.message : e}`, hint: 'check your network / credentials' };
+  }
+}
 
+// Configure ONE channel: prompt each credential field (secrets masked),
+// persist to .env + cfg.channels, echo a summary. Returns the persist entry.
+async function configureChannel({ cfgDir, spec, prompt, colors, write, fetchImpl }) {
+  const { dim, ok, warn } = colors;
   const answers = {};
   for (const f of spec.fields) {
-    const v = (await prompt(`  ${spec.label} — ${f.prompt}${f.optional ? ' (optional)' : ''}: `)).trim();
+    // Mask secret fields so tokens aren't echoed in plaintext to the terminal.
+    const v = (await prompt(`  ${spec.label} — ${f.prompt}${f.optional ? ' (optional)' : ''}: `, { secret: !!f.secret })).trim();
     if (v) answers[f.key] = v;
   }
-  try {
-    const entry = persistChannel(cfgDir, pick, answers);
-    const credKeys = Object.keys(entry.envVars);
-    write(`  ${ok('✓ channel enabled:')} ${pick}  ${credKeys.length ? dim(`creds: ${credKeys.join(', ')}`) : ''}\n`);
-    for (const f of spec.fields) {
-      if (f.secret && answers[f.key]) write(`    ${dim(`${f.env} = ${mask(answers[f.key])}  (stored in ${cfgDir}/.env, 0600)`)}\n`);
+  const entry = persistChannel(cfgDir, spec.name, answers);
+  const credKeys = Object.keys(entry.envVars);
+  const status = entry.ready ? ok('✓ channel enabled:') : warn('• channel saved (not yet enabled):');
+  write(`  ${status} ${spec.name}  ${credKeys.length ? dim(`creds: ${credKeys.join(', ')}`) : ''}\n`);
+  for (const f of spec.fields) {
+    if (f.secret && answers[f.key]) write(`    ${dim(`${f.env} = ${mask(answers[f.key])}  (stored in ${cfgDir}/.env, 0600)`)}\n`);
+  }
+  // Verify the credentials with a cheap live call (same probe as `channels
+  // test`) so a typo'd token is caught here, not later in chat. The creds were
+  // just written to .env; verifyChannel reads from env, so merge them in.
+  // ok=null (http / plugins) prints nothing.
+  if (credKeys.length) {
+    try {
+      const ver = await verifyChannel(spec.name, { env: { ...process.env, ...entry.envVars }, fetchImpl });
+      if (ver.ok === true) write(`  ${ok('✓ verified:')} ${dim(ver.detail || '')}\n`);
+      else if (ver.ok === false) write(`  ${warn('✗ not verified:')} ${ver.detail || ''}${ver.hint ? dim(`  (${ver.hint})`) : ''}\n`);
+    } catch { /* verification is best-effort — never block setup on it */ }
+  }
+  // Honest requirement notice: these channels ship in-tree but need a runtime
+  // dependency before the gateway can start them. We never point at a package
+  // that doesn't exist.
+  if (!entry.ready) {
+    if (entry.missingDeps && entry.missingDeps.length) {
+      write(`  ${warn('needs a runtime package:')} ${entry.missingDeps.join(', ')}\n`);
+      write(`    ${dim(`install with: lazyclaw channels install ${spec.name}  (runs: npm install --prefix ${cfgDir} ${entry.missingDeps.join(' ')})`)}\n`);
     }
-    if (entry.needsPlugin) {
-      write(`  ${warn('plugin required:')} ${entry.needsPlugin}\n`);
-      write(`    ${dim(`install with: lazyclaw channels install ${entry.needsPlugin}  (or npm install --prefix ${cfgDir} ${entry.needsPlugin})`)}\n`);
+    if (entry.missingBinary) {
+      write(`  ${warn('needs an external binary:')} ${entry.missingBinary} (must be on your PATH)\n`);
     }
-    write('\n');
-    return { skipped: false, channel: pick, needsPlugin: entry.needsPlugin };
-  } catch (e) {
-    write(`  ${warn('skipped:')} ${e?.message || e}\n\n`);
-    return { skipped: true };
+    write(`    ${dim(`then enable it with: lazyclaw channels enable ${spec.name}`)}\n`);
   }
+  write('\n');
+  return entry;
+}
+
+// Interactive channel step. Picks the channel from an arrow-key list (no
+// typing the name), then prompts that channel's credential fields, and loops
+// so several channels can be set up in one pass. `prompt(label, {secret})`
+// resolves to a trimmed string; `write(text)` sinks UI output. Returns
+// { skipped, channels: [names], needsPlugin? }. Never echoes a secret value.
+export async function runChannelStep({ cfgDir, prompt, colors, write = (s) => process.stdout.write(s), pick, fetchImpl }) {
+  const { dim, ok, warn } = colors;
+  // `pick` is the arrow-key list selector — injectable so tests can script it
+  // (the real _arrowMenu reads raw stdin, which a unit test can't drive).
+  const picker = pick || (await import('../tui/pickers.mjs'))._arrowMenu;
+  write(`  ${dim('Where will you talk to the agent? Pick one (arrow keys); set its credentials inline. (* = ships in-tree but needs a runtime package/binary.) You can add more than one.')}\n\n`);
+
+  const configured = [];
+  let needsPlugin = null;
+  while (true) {
+    const done = configured.length
+      ? { id: '__done__', label: `✓ Done (${configured.length} channel${configured.length === 1 ? '' : 's'} set)`, desc: 'finish the channel step' }
+      : { id: '__done__', label: 'Skip — no channel', desc: 'set one later with /channels <name> setup' };
+    const items = [done, ...CHANNEL_CATALOG.map((c) => ({
+      id: c.name,
+      label: `${c.label}${c.builtin ? '' : ' *'}`,
+      desc: configured.includes(c.name) ? '(already set — reconfigure)' : (c.builtin ? '' : `needs: ${(c.deps && c.deps.length) ? c.deps.join(', ') : (c.binary || 'creds only')}`),
+    }))];
+    const picked = await picker({
+      title: 'Step 3 · pick a channel to set up',
+      subtitle: 'Enter to configure · Esc / Done to finish',
+      items,
+      searchable: true,
+    });
+    // Esc / q / Ctrl-C / Done → leave the step.
+    const id = picked && typeof picked === 'object' ? picked.id : picked;
+    if (!id || id === '__done__' || id === 'BACK' || id === 'CANCEL') break;
+    const spec = channelByName(id);
+    if (!spec) { write(`  ${warn('skipped:')} unknown channel "${id}"\n\n`); continue; }
+    try {
+      const entry = await configureChannel({ cfgDir, spec, prompt, colors, write, fetchImpl });
+      if (!configured.includes(id)) configured.push(id);
+      if (!entry.ready && entry.missingDeps && entry.missingDeps.length) needsPlugin = entry.missingDeps.join(', ');
+    } catch (e) {
+      write(`  ${warn('skipped:')} ${e?.message || e}\n\n`);
+    }
+  }
+
+  if (!configured.length) { write(`  ${dim('— skipped —')}\n\n`); return { skipped: true }; }
+  write(`  ${ok('channels:')} ${configured.join(', ')}\n\n`);
+  return { skipped: false, channels: configured, needsPlugin };
 }
 
 // Outbound webhook step (moved verbatim-in-spirit from setup.mjs).
 export async function runWebhookStep({ prompt, colors, write = (s) => process.stdout.write(s) }) {
   const { dim, ok, warn } = colors;
+  const { _pickYesNo } = await import('../tui/pickers.mjs');
   write(`  ${dim('Outbound webhook for `lazyclaw message send <name> <text>`. Slack / Discord Incoming Webhook URLs work as-is.')}\n\n`);
-  const hookName = (await prompt('  webhook name (Enter to skip): ')).trim();
+  const wantHook = await _pickYesNo('Add an outbound webhook?', { yesLabel: 'Add one', noLabel: 'Skip', defaultYes: false });
+  const hookName = wantHook ? (await prompt('  webhook name: ')).trim() : '';
   if (!hookName) { write(`  ${dim('— skipped —')}\n\n`); return { skipped: true }; }
   const hookUrl = (await prompt('  webhook URL: ')).trim();
   if (!hookUrl) { write(`  ${warn('skipped:')} URL required\n\n`); return { skipped: true }; }
@@ -151,13 +306,29 @@ export async function runWebhookStep({ prompt, colors, write = (s) => process.st
 export async function runContextStep({ prompt, colors, write = (s) => process.stdout.write(s) }) {
   const { dim, ok } = colors;
   const cf = await import('../config_features.mjs');
+  const { _pickChoice } = await import('../tui/pickers.mjs');
   const cur = cf.chatWindowGet(readConfig());
   write(`  ${dim(`Context window — how much past conversation to send each turn (sliding budget, not the model's hard limit). Now: ${cur.turns} turns · ${cur.tokens} tokens.`)}\n\n`);
-  const turnsRaw = (await prompt(`  turns to keep (Enter = ${cur.turns}): `)).trim();
-  const tokensRaw = (await prompt(`  token budget (Enter = ${cur.tokens}): `)).trim();
-  if (!turnsRaw && !tokensRaw) { write(`  ${dim('— kept defaults —')}\n\n`); return { skipped: true }; }
-  const turns = parseInt(turnsRaw, 10);
-  const tokens = parseInt(tokensRaw, 10);
+  // Pick a preset (or "custom" → type the two numbers). Presets cover the
+  // common small/default/large tradeoffs so the user rarely has to type.
+  const PRESETS = [
+    { id: 'keep', label: `Keep current (${cur.turns} turns · ${cur.tokens} tokens)`, turns: cur.turns, tokens: cur.tokens },
+    { id: 'small', label: 'Small — 20 turns · 8k tokens', desc: 'cheaper, shorter memory', turns: 20, tokens: 8000 },
+    { id: 'default', label: 'Default — 40 turns · 16k tokens', turns: 40, tokens: 16000 },
+    { id: 'large', label: 'Large — 80 turns · 32k tokens', desc: 'more context, costs more', turns: 80, tokens: 32000 },
+    { id: 'custom', label: 'Custom…', desc: 'type your own turns + token budget' },
+  ];
+  const choice = await _pickChoice('Context window', PRESETS, { subtitle: 'how much past conversation to send each turn', fallback: 'keep' });
+  if (choice === 'keep') { write(`  ${dim('— kept defaults —')}\n\n`); return { skipped: true }; }
+  let turns, tokens;
+  if (choice === 'custom') {
+    turns = parseInt((await prompt(`  turns to keep (Enter = ${cur.turns}): `)).trim(), 10);
+    tokens = parseInt((await prompt(`  token budget (Enter = ${cur.tokens}): `)).trim(), 10);
+  } else {
+    const p = PRESETS.find((x) => x.id === choice);
+    turns = p ? p.turns : NaN;
+    tokens = p ? p.tokens : NaN;
+  }
   const cfg = readConfig();
   cf.chatWindowSet(cfg, {
     ...(Number.isFinite(turns) && turns > 0 ? { turns } : {}),
@@ -180,9 +351,10 @@ export async function runOrchestratorStep({ prompt, colors, write = (s) => proce
   // planner + workers are chosen from a list (arrow keys / filter), not typed.
   const { _pickProviderInteractive } = await import('../tui/pickers.mjs');
   const toSpec = (p) => (p && p.provider) ? (p.model ? `${p.provider}:${p.model}` : p.provider) : null;
+  const { _pickYesNo } = await import('../tui/pickers.mjs');
   write(`  ${dim('Multi-agent: a planner splits your task into subtasks, workers run them in parallel, then a synthesis step merges the results. Skip for a single agent.')}\n\n`);
-  const yn = (await prompt('  enable orchestration? [y/N] ')).trim().toLowerCase();
-  if (yn !== 'y' && yn !== 'yes') { write(`  ${dim('— skipped —')}\n\n`); return { skipped: true }; }
+  const enable = await _pickYesNo('Enable multi-agent orchestration?', { yesLabel: 'Enable', noLabel: 'Skip', defaultYes: false });
+  if (!enable) { write(`  ${dim('— skipped —')}\n\n`); return { skipped: true }; }
   const cfg = readConfig();
   const base = cfg.provider && cfg.provider !== 'orchestrator' ? cfg.provider : 'claude-cli';
   // Planner — pick from the provider/model list (Esc keeps the default).

package/commands/skills.mjs

@@ -2,6 +2,7 @@
 // extracted from cli.mjs in Phase D3. Self-contained over skills*.mjs modules.
 import path from 'node:path';
 import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { configPath } from '../lib/config.mjs';
 
 export async function cmdSkills(sub, positional, flags = {}) {
@@ -118,6 +119,23 @@ export async function cmdSkills(sub, positional, flags = {}) {
       console.log(JSON.stringify({ ok: true, name, path: written, bytes: content.length }));
       return;
     }
+    case 'starter': {
+      // Bundled starter pack — the .md skills shipped under the package's
+      // skills/ directory. pickSkillFiles() already prefers a skills/ dir
+      // at a repo root, so the same heuristic that resolves a GitHub
+      // bundle resolves the local package. Existing names are skipped
+      // unless --force, so user edits survive re-runs.
+      const inst = await import('../skills_install.mjs');
+      const pkgRoot = fileURLToPath(new URL('..', import.meta.url));
+      const picked = inst.pickSkillFiles(pkgRoot);
+      if (!picked.length) {
+        console.error('no bundled starter skills found (package incomplete?)');
+        process.exit(1);
+      }
+      const r = inst.installPickedSkills(picked, cfgDir, { force: !!flags.force });
+      console.log(JSON.stringify({ ok: true, installed: r.installed, skipped: r.skipped }, null, 2));
+      return;
+    }
     case 'remove': {
       const name = positional[0];
       if (!name) { console.error('Usage: lazyclaw skills remove <name>'); process.exit(2); }
@@ -212,7 +230,7 @@ export async function cmdSkills(sub, positional, flags = {}) {
       return;
     }
     default:
-      console.error('Usage: lazyclaw skills <list|show <name>|install <name> [--from path]|remove <name>|search <query> [--regex]|curate|classify <name>>');
+      console.error('Usage: lazyclaw skills <list|show <name>|install <name> [--from path]|starter [--force]|remove <name>|search <query> [--regex]|curate|classify <name>>');
       process.exit(2);
   }
 }

package/commands/workflow_named.mjs

@@ -0,0 +1,137 @@
+// commands/workflow_named.mjs — `lazyclaw workflow <add|list|show|remove|run>`.
+//
+// Stored, named declarative workflows (cfg.workflows[<name>]) — the Hermes-style
+// automation surface. `add` persists a def from a JSON file (+ optional Slack
+// channel / cron schedule); `run` executes it by name and posts the reply to
+// the bound channel. Distinct from the top-level `run <session-id> <file.mjs>`
+// (the hand-written .mjs engine) — these are DATA workflows.
+
+import fs from 'node:fs';
+import { readConfig, writeConfig, configPath } from '../lib/config.mjs';
+import { PROVIDERS } from '../providers/registry.mjs';
+import { parseWorkflow } from '../workflow/declarative.mjs';
+import { runNamedWorkflow, getNamedWorkflow, listNamedWorkflows, namedReplyText, validWorkflowName } from '../workflow/named.mjs';
+
+const emitJson = (o) => process.stdout.write(JSON.stringify(o, null, 2) + '\n');
+const providerLookup = (name) => PROVIDERS[name] || null;
+
+// Post a workflow's reply text to a channel target ("slack:#chan" or a bare
+// channel id). makeSender is injected in tests; in production it builds a
+// short-lived SlackChannel (requireInbound:false → only SLACK_BOT_TOKEN needed),
+// mirroring the goal-tick fan-out. Best-effort: a Slack failure is reported, not
+// fatal to the run.
+async function postReply(channelTarget, text, { makeSender } = {}) {
+  if (!channelTarget || !text) return { posted: false };
+  const channel = String(channelTarget).startsWith('slack:') ? String(channelTarget).slice('slack:'.length) : String(channelTarget);
+  let sender;
+  try {
+    if (makeSender) {
+      sender = await makeSender();
+    } else {
+      const slackMod = await import('../channels/slack.mjs');
+      sender = new slackMod.SlackChannel({ requireInbound: false });
+      await sender.start(async () => '', { gate: null });
+    }
+    const res = await sender.send(channel, text);
+    return { posted: true, ts: res?.ts || null, channel };
+  } catch (e) {
+    return { posted: false, error: e?.message || String(e), channel };
+  } finally {
+    try { if (sender && typeof sender.stop === 'function') await sender.stop(); } catch { /* best-effort */ }
+  }
+}
+
+// Run a named workflow and (when it has a bound channel) post its reply. Pure
+// enough to test in-process: pass makeSender + fetchImpl. Returns
+// { result, reply, post }.
+export async function runNamedAndReport(name, cfg, opts = {}) {
+  const entry = getNamedWorkflow(cfg, name);
+  if (!entry) throw new Error(`no workflow named "${name}"`);
+  const result = await runNamedWorkflow(name, cfg, { providerLookup, fetchImpl: opts.fetchImpl, input: opts.input });
+  const reply = namedReplyText(result, entry);
+  let post = { posted: false };
+  if (entry.channel && reply) post = await postReply(entry.channel, reply, { makeSender: opts.makeSender });
+  return { result, reply, post };
+}
+
+export async function cmdWorkflow(sub, positional = [], flags = {}) {
+  switch (sub) {
+    case undefined:
+    case 'list':
+      emitJson({ ok: true, workflows: listNamedWorkflows(readConfig()) });
+      return;
+
+    case 'show': {
+      const name = positional[0];
+      const entry = name && getNamedWorkflow(readConfig(), name);
+      if (!entry) { console.error(`workflow show: no workflow "${name}"`); process.exit(2); }
+      emitJson({ ok: true, name, ...entry });
+      return;
+    }
+
+    case 'add': {
+      const name = positional[0];
+      const file = positional[1];
+      if (!name || !file) {
+        console.error('Usage: lazyclaw workflow add <name> <def.json> [--channel slack:#x] [--cron "<spec>"] [--reply-node <id>]');
+        process.exit(2);
+      }
+      if (!validWorkflowName(name)) { console.error(`workflow add: invalid name "${name}" (letters/digits/.-_ only)`); process.exit(2); }
+      let def;
+      try {
+        const text = fs.readFileSync(file, 'utf8');
+        def = /\.ya?ml$/i.test(file)
+          ? await (await import('../workflow/declarative.mjs')).parseWorkflowYaml(text)
+          : parseWorkflow(text);
+      } catch (e) { console.error(`workflow add: ${e.message}`); process.exit(2); }
+      const entry = { def };
+      if (flags.channel && flags.channel !== true) entry.channel = String(flags.channel);
+      if (flags.cron && flags.cron !== true) entry.schedule = String(flags.cron);
+      if (flags['reply-node'] && flags['reply-node'] !== true) entry.replyNode = String(flags['reply-node']);
+      const cfg = readConfig();
+      cfg.workflows = cfg.workflows || {};
+      cfg.workflows[name] = entry;
+      writeConfig(cfg);
+      // Install a cron job when a schedule was given (C-3).
+      if (entry.schedule) {
+        try {
+          const { attachWorkflowCron } = await import('../workflow/named_cron.mjs');
+          attachWorkflowCron(name, entry.schedule);
+        } catch (e) { console.error(`workflow add: stored, but cron install failed: ${e.message}`); }
+      }
+      emitJson({ ok: true, added: name, channel: entry.channel || null, schedule: entry.schedule || null });
+      return;
+    }
+
+    case 'remove':
+    case 'rm':
+    case 'delete': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw workflow remove <name>'); process.exit(2); }
+      const cfg = readConfig();
+      if (!getNamedWorkflow(cfg, name)) { console.error(`workflow remove: no workflow "${name}"`); process.exit(2); }
+      delete cfg.workflows[name];
+      writeConfig(cfg);
+      emitJson({ ok: true, removed: name });
+      return;
+    }
+
+    case 'run': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw workflow run <name>'); process.exit(2); }
+      const cfg = readConfig();
+      try {
+        const { result, reply, post } = await runNamedAndReport(name, cfg, {});
+        emitJson({ ok: result.success, success: result.success, reply, post, ...(result.error ? { error: result.error, failedAt: result.failedAt } : {}) });
+        if (!result.success) process.exit(1);
+      } catch (e) { console.error(`workflow run: ${e.message}`); process.exit(1); }
+      return;
+    }
+
+    default:
+      console.error('Usage: lazyclaw workflow <list|show|add|remove|run> ...');
+      process.exit(2);
+  }
+}
+
+void configPath; // configPath kept available for callers that derive the dir.

package/config-validate.mjs

@@ -6,7 +6,16 @@
 // `GET /config/validate` (daemon) so both produce bit-for-bit
 // identical output.
 
-const KNOWN_KEYS = new Set(['provider', 'model', 'api-key', 'rates']);
+// Top-level cfg.json keys the codebase reads. Anything else warns (a likely
+// typo). Kept in sync with the actual readers: sandbox (tui/run_turn,
+// sandbox/index), channels/authProfiles/authActiveProfile/nodes/messaging/
+// pairing (config_features), cron (cron.mjs), mcp + orchestra (daemon.mjs),
+// security (gateway_guard), skills + workspace (commands/chat).
+const KNOWN_KEYS = new Set([
+  'provider', 'model', 'api-key', 'rates', 'trainer', 'orchestrator', 'persona', 'customProviders', 'chat',
+  'sandbox', 'channels', 'authProfiles', 'authActiveProfile', 'nodes', 'messaging', 'pairing',
+  'cron', 'mcp', 'orchestra', 'security', 'skills', 'workspace', 'recall', 'workflows',
+]);
 
 /**
  * @param {Record<string, unknown>} cfg

package/config_features.mjs

@@ -303,6 +303,51 @@ export function chatWindowSet(cfg, { turns, tokens } = {}) {
   return cfg;
 }
 
+// ── Chat agentic REPL + plan mode (cfg.chat.{agentic,tools,planMode}) ────
+// Group 1 — when agentic mode is ON the chat turn routes through the MAS
+// tool loop (runAgentTurn) instead of plain streaming. Opt-in, OFF by
+// default, so existing users keep the exact streaming behavior. Plan mode
+// rides on the same loop but intersects the tool whitelist down to a
+// read-only set ("propose, don't mutate"). Accessors are the registration
+// surface for these keys, mirroring chatWindowGet/Set above.
+//
+// Default whitelist is read-only + safe: a chat turn that can silently
+// propose bash is higher-risk than /task, so bash/write are opt-in per tool
+// via cfg.chat.tools. Sensitive tools still pass the fail-closed approval
+// gate in mas/tool_runner.mjs regardless.
+export const DEFAULT_CHAT_TOOLS = ['read', 'grep', 'skill_view'];
+// Read-only safe set used to intersect the whitelist in plan mode (drops
+// bash/write/delegate and any other sensitive verb). Kept narrow on purpose.
+export const READONLY_CHAT_TOOLS = ['read', 'grep', 'skill_view'];
+
+export function chatAgenticGet(cfg) {
+  return !!(cfg && cfg.chat && cfg.chat.agentic === true);
+}
+export function chatPlanModeGet(cfg) {
+  return !!(cfg && cfg.chat && cfg.chat.planMode === true);
+}
+export function chatToolsGet(cfg) {
+  const c = (cfg && cfg.chat && typeof cfg.chat === 'object') ? cfg.chat : {};
+  return Array.isArray(c.tools) ? c.tools.slice() : DEFAULT_CHAT_TOOLS.slice();
+}
+
+// Persist a chat.* boolean/array key, mutating cfg in place. Returns cfg.
+export function chatSet(cfg, key, value) {
+  cfg.chat = (cfg.chat && typeof cfg.chat === 'object') ? cfg.chat : {};
+  cfg.chat[key] = value;
+  return cfg;
+}
+
+// Resolve the effective tool whitelist for an agentic chat turn. In plan
+// mode the configured whitelist is intersected with the read-only set so
+// no mutating tool can be proposed; otherwise the configured list is used
+// as-is (default read-only safe set when unset).
+export function effectiveChatTools(cfg, { planMode = false } = {}) {
+  const tools = chatToolsGet(cfg);
+  if (!planMode) return tools;
+  return tools.filter((t) => READONLY_CHAT_TOOLS.includes(t));
+}
+
 // ── Orchestrator — multi-agent config (cfg.orchestrator) ────────────────
 // Shared by the setup wizard, the /orchestrator slash, and the CLI so the
 // "planner + workers" config has one shape. Orchestration is ACTIVE only when

package/cron.mjs

@@ -192,14 +192,25 @@ export function buildPlist(name, schedule, command) {
   const dom   = expandField(parsed.dom,    { min: 1,  max: 31 });
   const month = expandField(parsed.month,  { min: 1,  max: 12 });
   const dow   = expandField(parsed.dow,    { min: 0,  max: 6  });
-  // launchd takes a single dict per fire-time. We expand the cron
-  // schedule into the cartesian product of (Minute × Hour × Day ×
-  // Month × Weekday); each null field means "every" so we encode
-  // nothing for it. For most schedules this is small (e.g. "every
-  // weekday 9 AM" = 5 entries).
-  const entries = cartesian([
-    minOrNull(min), minOrNull(hour), minOrNull(dom), minOrNull(month), minOrNull(dow),
-  ]);
+  // launchd takes a single dict per fire-time. We expand the cron schedule
+  // into the cartesian product of (Minute × Hour × Day × Month × Weekday);
+  // each null field means "every" so we encode nothing for it.
+  //
+  // BUT cron treats day-of-month and day-of-week with OR semantics when BOTH
+  // are restricted: `0 9 13 * 5` fires on the 13th OR on any Friday. A plain
+  // cartesian product ANDs them (only when the 13th IS a Friday) — diverging
+  // from crontab on Linux. So when both are restricted, emit the UNION of two
+  // sets: one keyed on Day (Weekday=every) and one on Weekday (Day=every).
+  let entries;
+  if (dom !== null && dow !== null) {
+    const byDom = cartesian([minOrNull(min), minOrNull(hour), dom, minOrNull(month), [null]]);
+    const byDow = cartesian([minOrNull(min), minOrNull(hour), [null], minOrNull(month), dow]);
+    entries = [...byDom, ...byDow];
+  } else {
+    entries = cartesian([
+      minOrNull(min), minOrNull(hour), minOrNull(dom), minOrNull(month), minOrNull(dow),
+    ]);
+  }
   const intervals = entries.map(([Minute, Hour, Day, Month, Weekday]) => {
     const dict = {};
     if (Minute  !== null) dict.Minute  = Minute;