@dashclaw/cli 0.3.1 → 0.4.0

package/bin/dashclaw.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { execFileSync } from 'child_process';
+import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DashClaw } from 'dashclaw';
@@ -10,7 +11,7 @@ import {
   green, red,
 } from '../lib/render.js';
 import { runDoctor as runDoctorCommand } from '../lib/doctor.js';
-import { resolveConfig, clearConfigFile, configPath } from '../lib/config.js';
+import { resolveConfig, clearConfigFile, configPath, ask, askSecret } from '../lib/config.js';
 import { runIngest, defaultClaudeProjectsDir } from '../lib/code/ingest.js';
 import { runMemo } from '../lib/code/memo.js';
 import { runApply } from '../lib/code/apply.js';
@@ -20,13 +21,18 @@ import {
   defaultCodexOutDir,
 } from '../lib/code/ingest-codex.js';
 import { installCodex, codexConfigPath, codexHooksDir } from '../lib/codex/install.js';
+import { installClaude } from '../lib/claude/install.js';
+import { runCost } from '../lib/cost.js';
 import { runCodexNotify } from '../lib/codex/notify.js';
 import { apiRequest } from '../lib/api.js';
 import { fetchPosture, fetchFindings, fetchNext, resolveFinding } from '../lib/posture.js';
+import { fetchAgentEnv, splitEnvArgv, formatEnvNames, runWithEnv } from '../lib/env.js';
 
 process.on('unhandledRejection', (reason) => {
   console.error('Unhandled Rejection:', reason);
-  process.exit(1);
+  // exitCode (not process.exit) — a hard exit during in-flight I/O trips a
+  // libuv teardown assert on Windows.
+  process.exitCode = 1;
 });
 
 // -- Config -------------------------------------------------------------------
@@ -54,6 +60,17 @@ function getFlag(name) {
   return undefined;
 }
 
+function incrementCount(counts, key) {
+  counts[key] = (counts[key] || 0) + 1;
+}
+
+function runSubcommand(table, sub, errorMessage) {
+  const handler = table[sub];
+  if (handler) return handler();
+  console.error(errorMessage(sub));
+  process.exitCode = 1;
+}
+
 // -- Commands -----------------------------------------------------------------
 
 async function cmdHelp() {
@@ -64,10 +81,12 @@ ${bold('Usage:')}
   dashclaw approvals                     Interactive approval inbox
   dashclaw approve <actionId> [--reason]  Approve an action
   dashclaw deny <actionId> [--reason]     Deny an action
-  dashclaw doctor                        Diagnose and auto-fix your DashClaw instance
+  dashclaw doctor                        Diagnose your instance + this machine (report-only)
+    --fix                                Apply safe auto-fixes, then re-check and report
     --json                               Output as JSON (for CI/scripts)
-    --no-fix                             Diagnose only, skip auto-fixes
-    --category <list>                    Filter checks (e.g., database,config)
+    --no-fix                             Accepted no-op alias (report-only is the default)
+    --category <list>                    Filter remote checks (e.g., database,config)
+    --repo <path>                        Treat <path> as the DashClaw checkout for repo checks
   dashclaw code ingest [--dry-run]       Backfill Claude Code transcripts from ~/.claude/projects
     --projects-dir <path>                Override the default scan directory
   dashclaw code ingest-codex [--dry-run] Backfill Codex transcripts from ~/.codex/sessions
@@ -81,6 +100,10 @@ ${bold('Usage:')}
     --yes                                Overwrite existing files when manifest says so
     --allow-redactions                   Write files that contain redacted secret patterns
     --overwrite                          Clobber existing .NEW side-by-side files
+  dashclaw install claude [--trial]      Provision DashClaw governance into Claude Code
+    --endpoint <url>                     Your DashClaw instance URL (or DASHCLAW_BASE_URL)
+    --key <key>                          API key (or DASHCLAW_API_KEY; --trial prompts via browser signup)
+    --agent-id <id>                      Agent id for governed actions (default: claude-code)
   dashclaw install codex                 Provision DashClaw governance into Codex CLI
     --project <path>                     Project to receive AGENTS.md (default: cwd)
     --approval-policy <p>                Codex approval_policy (default: on-request)
@@ -106,11 +129,17 @@ ${bold('Usage:')}
   dashclaw behavior status               Behavior Learning sample status (local recorder)
   dashclaw behavior suggestions          Evidence-backed policy suggestions per agent
     --agent-id <id>                      Filter to one agent
+  dashclaw env [--agent <id>] -- <cmd...> Run <cmd> with managed secrets injected (memory-only)
+                                         Without -- <cmd>: list secret NAMES + count (never values)
+  dashclaw cost                          Spend readback from /api/finops/spend
+    --lens fleet|claude-code             Which rollup (default: claude-code)
+    --period 7d|30d|90d                  Window (default: 7d)
   dashclaw posture                       Governance posture score + remediation queue
   dashclaw posture resolve <key>         Draft a fix (inactive) | --snooze | --accept-risk
     --note "..."                         Attach a note to the resolution
   dashclaw next                          The single top open governance gap + its fix
   dashclaw logout                        Remove saved config (~/.dashclaw/config.json)
+  dashclaw version                       Print the CLI version
   dashclaw help                          Show this help
 
 ${bold('Config:')}
@@ -120,6 +149,12 @@ ${bold('Config:')}
 `);
 }
 
+async function cmdVersion() {
+  const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  console.log(pkg.version);
+}
+
 async function cmdLogout() {
   const removed = clearConfigFile();
   if (removed) {
@@ -131,15 +166,23 @@ async function cmdLogout() {
 
 async function cmdDoctor() {
   const jsonFlag = args.includes('--json');
+  const fixFlag = args.includes('--fix');
   const noFixFlag = args.includes('--no-fix');
   const catIdx = args.indexOf('--category');
   const catValue = catIdx !== -1 ? args[catIdx + 1] : undefined;
+  const repoIdx = args.indexOf('--repo');
+  const repoValue = repoIdx !== -1 ? args[repoIdx + 1] : undefined;
+  const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   await runDoctorCommand({
     baseUrl,
     apiKey,
     json: jsonFlag,
+    fix: fixFlag,
     noFix: noFixFlag,
     category: catValue,
+    repo: repoValue,
+    cliVersion: pkg.version,
   });
 }
 
@@ -181,211 +224,192 @@ async function cmdDeny() {
   }
 }
 
-async function cmdApprovals() {
-  const claw = createClient();
+async function fetchPendingApprovals(state) {
+  try {
+    const result = await state.claw.getPendingApprovals(50);
+    state.items = result.actions || [];
+  } catch (err) {
+    console.error(`Error fetching approvals: ${err.message}`);
+    process.exit(1);
+  }
+}
 
-  let items = [];
-  let selected = 0;
+function approvalId(action) {
+  return action.action_id || action.id;
+}
 
-  async function fetchPending() {
-    try {
-      const result = await claw.getPendingApprovals(50);
-      items = result.actions || [];
-    } catch (err) {
-      console.error(`Error fetching approvals: ${err.message}`);
-      process.exit(1);
-    }
-  }
+function renderApprovalRow(action, index, selected) {
+  const type = action.action_type || '-';
+  const agent = action.agent_id || '-';
+  const goal = (action.declared_goal || '-').slice(0, 60);
+  const risk = action.risk_score != null ? colorByRisk(action.risk_score) : dim('-');
+  const line = `  [${index + 1}] ${type} | ${agent} | ${goal} | risk: ${risk}`;
+  process.stdout.write((index === selected ? inverse(line) : line) + '\n');
+}
 
-  function render() {
-    clearScreen();
-    moveCursor(1, 1);
-    process.stdout.write(bold('DashClaw Approval Inbox') + '\n\n');
+function renderApprovals(state) {
+  clearScreen();
+  moveCursor(1, 1);
+  process.stdout.write(bold('DashClaw Approval Inbox') + '\n\n');
 
-    if (items.length === 0) {
-      process.stdout.write(dim('  No pending approvals.\n'));
-      process.stdout.write(dim('  Press R to refresh, Q to quit.\n'));
-    } else {
-      for (let i = 0; i < items.length; i++) {
-        const a = items[i];
-        const id = a.action_id || a.id || '?';
-        const type = a.action_type || '-';
-        const agent = a.agent_id || '-';
-        const goal = (a.declared_goal || '-').slice(0, 60);
-        const risk = a.risk_score != null ? colorByRisk(a.risk_score) : dim('-');
-
-        const line = `  [${i + 1}] ${type} | ${agent} | ${goal} | risk: ${risk}`;
-        process.stdout.write((i === selected ? inverse(line) : line) + '\n');
-      }
-    }
+  if (state.items.length === 0) {
+    process.stdout.write(dim('  No pending approvals.\n'));
+    process.stdout.write(dim('  Press R to refresh, Q to quit.\n'));
+  } else {
+    state.items.forEach((action, index) => renderApprovalRow(action, index, state.selected));
+  }
 
-    process.stdout.write('\n' + dim('  [A] Approve  [D] Deny  [R] Refresh  [O] Open Replay  [Q] Quit') + '\n');
+  process.stdout.write('\n' + dim('  [A] Approve  [D] Deny  [R] Refresh  [O] Open Replay  [Q] Quit') + '\n');
+}
+
+function replayUrlIsSafe(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
   }
+  const protocolOk = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  return protocolOk && parsed.hostname && !/\s/.test(url) && !/[&|><^"'`]/.test(url);
+}
 
-  function openReplay(actionId) {
-    const url = `${baseUrl}/replay/${actionId}`;
-    let parsed;
-    try {
-      parsed = new URL(url);
-    } catch {
-      process.stdout.write(`\n  Invalid URL, cannot open browser.\n`);
-      return;
-    }
-    const protocol = parsed.protocol;
-    if (protocol !== 'http:' && protocol !== 'https:') {
-      process.stdout.write(`\n  Invalid URL, cannot open browser.\n`);
-      return;
-    }
-    if (!parsed.hostname) {
-      process.stdout.write(`\n  Invalid URL, cannot open browser.\n`);
-      return;
-    }
-    if (/\s/.test(url)) {
-      process.stdout.write(`\n  Invalid URL, cannot open browser.\n`);
-      return;
-    }
-    // Disallow characters that are dangerous when passed through a shell
-    if (/[&|><^"'`]/.test(url)) {
-      process.stdout.write(`\n  Invalid URL, cannot open browser.\n`);
-      return;
-    }
-    try {
-      const platform = process.platform;
-      if (platform === 'darwin') {
-        execFileSync('open', [url]);
-      } else if (platform === 'win32') {
-        // Use PowerShell Start-Process instead of relying on cmd.exe parsing
-        execFileSync('powershell', ['-NoProfile', '-Command', 'Start-Process', url]);
-      } else {
-        execFileSync('xdg-open', [url]);
-      }
-    } catch (_) {
-      process.stdout.write(`\n  Could not open browser. URL: ${url}\n`);
+function openReplay(actionId) {
+  const url = `${baseUrl}/replay/${actionId}`;
+  if (!replayUrlIsSafe(url)) {
+    process.stdout.write(`\n  Invalid URL, cannot open browser.\n`);
+    return;
+  }
+  try {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+      execFileSync('open', [url]);
+    } else if (platform === 'win32') {
+      // Use PowerShell Start-Process instead of relying on cmd.exe parsing
+      execFileSync('powershell', ['-NoProfile', '-Command', 'Start-Process', url]);
+    } else {
+      execFileSync('xdg-open', [url]);
     }
+  } catch (_) {
+    process.stdout.write(`\n  Could not open browser. URL: ${url}\n`);
   }
+}
 
-  await fetchPending();
-
-  // Open SSE stream for live push of new approval requests
-  let stream = null;
+function startApprovalStream(state) {
   try {
-    stream = claw.events()
-      .on('guard.decision.created', (data) => {
-        if (data.decision !== 'require_approval') return;
-        const exists = items.some((it) => (it.action_id || it.id) === data.action_id);
-        if (exists) return;
-        items.push(data);
-        render();
-      })
+    state.stream = state.claw.events()
+      .on('guard.decision.created', (data) => handleApprovalPush(state, data))
       .on('error', () => {
-        moveCursor(items.length + 6, 1);
+        moveCursor(state.items.length + 6, 1);
         process.stdout.write(dim('  SSE stream error — live push unavailable, use R to refresh') + '\n');
       });
   } catch (_) {
     // SSE unavailable — inbox still works via manual refresh
   }
+}
+
+function handleApprovalPush(state, data) {
+  if (data.decision !== 'require_approval') return;
+  const exists = state.items.some((it) => approvalId(it) === data.action_id);
+  if (exists) return;
+  state.items.push(data);
+  renderApprovals(state);
+}
 
-  // Set up raw mode for interactive input
+function ensureApprovalTty() {
   if (!process.stdin.isTTY) {
     console.error('Error: Interactive mode requires a TTY. Use dashclaw approve/deny for non-interactive use.');
     process.exit(1);
   }
+}
+
+function selectedWithinItems(state) {
+  state.selected = Math.min(state.selected, Math.max(0, state.items.length - 1));
+}
 
+function setupApprovalTerminal(state) {
+  ensureApprovalTty();
   process.stdin.setRawMode(true);
   process.stdin.resume();
   process.stdin.setEncoding('utf8');
   hideCursor();
-
-  // Ensure cleanup on exit
-  function cleanup() {
-    if (stream) stream.close();
-    showCursor();
-    if (process.stdin.isTTY) process.stdin.setRawMode(false);
-    process.stdout.write('\n');
-  }
-  process.on('exit', cleanup);
+  process.on('exit', () => cleanupApprovalInbox(state));
   process.on('SIGINT', () => process.exit(0));
+}
 
-  render();
-
-  let busy = false;
+function cleanupApprovalInbox(state) {
+  if (state.stream) state.stream.close();
+  showCursor();
+  if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  process.stdout.write('\n');
+}
 
-  process.stdin.on('data', async (key) => {
-    if (busy) return;
+async function withApprovalBusy(state, fn) {
+  state.busy = true;
+  try {
+    await fn();
+  } finally {
+    state.busy = false;
+  }
+}
 
-    // Ctrl+C
-    if (key === '\x03') {
-      process.exit(0);
-    }
+async function refreshApprovals(state) {
+  await fetchPendingApprovals(state);
+  selectedWithinItems(state);
+  renderApprovals(state);
+}
 
-    // Arrow keys: escape sequences
-    if (key === '\x1b[A') {
-      // Up
-      if (selected > 0) selected--;
-      render();
-      return;
-    }
-    if (key === '\x1b[B') {
-      // Down
-      if (selected < items.length - 1) selected++;
-      render();
-      return;
-    }
+async function decideApproval(state, decision) {
+  const actionId = approvalId(state.items[state.selected]);
+  try {
+    await state.claw.approveAction(actionId, decision);
+    state.items.splice(state.selected, 1);
+    selectedWithinItems(state);
+  } catch (err) {
+    moveCursor(state.items.length + 5, 1);
+    process.stdout.write(red(`  Error: ${err.message}`) + '\n');
+  }
+  renderApprovals(state);
+}
 
-    const ch = key.toLowerCase();
+function moveApprovalSelection(state, delta) {
+  const next = state.selected + delta;
+  state.selected = Math.max(0, Math.min(next, state.items.length - 1));
+  renderApprovals(state);
+}
 
-    if (ch === 'q') {
-      process.exit(0);
-    }
+const EMPTY_APPROVAL_KEY_ACTIONS = {
+  q: () => process.exit(0),
+  r: (state) => withApprovalBusy(state, () => refreshApprovals(state)),
+};
 
-    if (ch === 'r') {
-      busy = true;
-      await fetchPending();
-      selected = Math.min(selected, Math.max(0, items.length - 1));
-      render();
-      busy = false;
-      return;
-    }
+const APPROVAL_KEY_ACTIONS = {
+  ...EMPTY_APPROVAL_KEY_ACTIONS,
+  a: (state) => withApprovalBusy(state, () => decideApproval(state, 'allow')),
+  d: (state) => withApprovalBusy(state, () => decideApproval(state, 'deny')),
+  o: (state) => openReplay(approvalId(state.items[state.selected])),
+};
 
-    if (items.length === 0) return;
-    const current = items[selected];
-    const actionId = current.action_id || current.id;
-
-    if (ch === 'a') {
-      busy = true;
-      try {
-        await claw.approveAction(actionId, 'allow');
-        items.splice(selected, 1);
-        selected = Math.min(selected, Math.max(0, items.length - 1));
-      } catch (err) {
-        moveCursor(items.length + 5, 1);
-        process.stdout.write(red(`  Error: ${err.message}`) + '\n');
-      }
-      render();
-      busy = false;
-      return;
-    }
+function approvalActionFor(state, key) {
+  if (key === '\x03') return () => process.exit(0);
+  if (key === '\x1b[A') return () => moveApprovalSelection(state, -1);
+  if (key === '\x1b[B') return () => moveApprovalSelection(state, 1);
+  const actions = state.items.length === 0 ? EMPTY_APPROVAL_KEY_ACTIONS : APPROVAL_KEY_ACTIONS;
+  return actions[key.toLowerCase()];
+}
 
-    if (ch === 'd') {
-      busy = true;
-      try {
-        await claw.approveAction(actionId, 'deny');
-        items.splice(selected, 1);
-        selected = Math.min(selected, Math.max(0, items.length - 1));
-      } catch (err) {
-        moveCursor(items.length + 5, 1);
-        process.stdout.write(red(`  Error: ${err.message}`) + '\n');
-      }
-      render();
-      busy = false;
-      return;
-    }
+async function handleApprovalKey(state, key) {
+  if (state.busy) return;
+  const action = approvalActionFor(state, key);
+  if (action) return action(state);
+}
 
-    if (ch === 'o') {
-      openReplay(actionId);
-      return;
-    }
-  });
+async function cmdApprovals() {
+  const state = { claw: createClient(), items: [], selected: 0, busy: false, stream: null };
+  await fetchPendingApprovals(state);
+  startApprovalStream(state);
+  setupApprovalTerminal(state);
+  renderApprovals(state);
+  process.stdin.on('data', (key) => handleApprovalKey(state, key));
 }
 
 // -- install subcommand group ------------------------------------------------
@@ -423,15 +447,63 @@ async function cmdInstallCodex() {
   }
 }
 
+async function cmdCost() {
+  const lens = getFlag('--lens') || 'claude-code';
+  const period = getFlag('--period') || '7d';
+
+  if (!baseUrl || !apiKey) {
+    console.error('Not configured. Run `dashclaw install claude` to set up,');
+    console.error('or set DASHCLAW_BASE_URL and DASHCLAW_API_KEY.');
+    process.exit(1);
+  }
+
+  try {
+    console.log(await runCost({ baseUrl, apiKey }, { lens, period }));
+  } catch (err) {
+    if (err.usage) {
+      console.error(err.message);
+    } else if (err.status === 401 || err.status === 403) {
+      console.error('API key was rejected (401/403). Re-run `dashclaw install claude` or check DASHCLAW_API_KEY.');
+    } else {
+      console.error(`Could not fetch spend from ${baseUrl}: ${err.message}`);
+      console.error('Check that the instance is running and reachable.');
+    }
+    // exitCode (not process.exit) so node drains the failed fetch socket —
+    // a hard exit here can trip a libuv teardown assert on Windows.
+    process.exitCode = 1;
+  }
+}
+
+async function cmdInstallClaude() {
+  try {
+    const result = await installClaude({
+      endpoint: getFlag('--endpoint') || baseUrl,
+      apiKey: getFlag('--key') || apiKey,
+      agentId: getFlag('--agent-id') || undefined,
+      trial: args.includes('--trial'),
+      prompt: ask,
+      promptSecret: askSecret,
+      logger: console,
+    });
+    console.log();
+    console.log(`  ${green('Done.')} Claude Code governance installed (mode: ${result.hookMode}).`);
+  } catch (err) {
+    console.error(red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
 async function cmdInstall() {
   const target = args[1];
   switch (target) {
     case 'codex':
       return cmdInstallCodex();
+    case 'claude':
+      return cmdInstallClaude();
     default:
       console.error(`Unknown install target: dashclaw install ${target || '(missing)'}\n` +
-                    'Try: dashclaw install codex [--project <path>] [--approval-policy <p>]');
-      process.exit(1);
+                    'Try: dashclaw install claude [--trial] | dashclaw install codex [--project <path>]');
+      process.exitCode = 1;
   }
 }
 
@@ -445,26 +517,26 @@ async function cmdCodexNotify() {
   // Skip the leading 'codex' and 'notify' tokens — runCodexNotify reads the
   // JSON payload from the LAST argv slot (per Codex's notify contract).
   const notifyArgv = args.slice(1); // includes 'notify' and the payload
-  await runCodexNotify({
-    argv: notifyArgv,
-    baseUrl,
-    apiKey,
-    agentId: agentId || 'codex',
-    logger: console,
-  });
+  try {
+    await runCodexNotify({
+      argv: notifyArgv,
+      baseUrl,
+      apiKey,
+      agentId: agentId || 'codex',
+      logger: console,
+    });
+  } catch {
+    // Best-effort by contract: Codex must never see a failure from its
+    // notify hook, so errors are swallowed and we still exit 0.
+  }
   process.exit(0);
 }
 
 async function cmdCodex() {
-  const sub = args[1];
-  switch (sub) {
-    case 'notify':
-      return cmdCodexNotify();
-    default:
-      console.error(`Unknown subcommand: dashclaw codex ${sub || '(missing)'}\n` +
-                    'Try: dashclaw codex notify \'<json>\'   (called by Codex notify config)');
-      process.exit(1);
-  }
+  return runSubcommand({
+    notify: cmdCodexNotify,
+  }, args[1], (sub) => `Unknown subcommand: dashclaw codex ${sub || '(missing)'}\n` +
+    'Try: dashclaw codex notify \'<json>\'   (called by Codex notify config)');
 }
 
 // -- code subcommand group ---------------------------------------------------
@@ -487,24 +559,27 @@ async function cmdCodeIngestCodex() {
     console.log('No sessions to ingest.');
     return;
   }
-  let written = 0, ingested = 0, dryRunCount = 0, skipped = 0, errors = 0;
-  for (const r of results) {
-    if (r.status === 'written_local') written++;
-    else if (r.status === 'ingested') ingested++;
-    else if (r.status === 'dry_run') dryRunCount++;
-    else if (r.status === 'skipped') skipped++;
-    else if (r.status === 'error') {
-      errors++;
-      console.error(`  ${red('error')} ${r.file}: ${r.reason}${r.detail ? ' — ' + r.detail : ''}`);
-    }
-  }
+  const counts = tallyCodexIngestResults(results);
   console.log();
-  console.log(`Done. Written: ${written}  Ingested: ${ingested}  Dry-run: ${dryRunCount}  Skipped: ${skipped}  Errors: ${errors}`);
-  if (!endpoint && written > 0) {
+  console.log(`Done. Written: ${counts.written_local}  Ingested: ${counts.ingested}  Dry-run: ${counts.dry_run}  Skipped: ${counts.skipped}  Errors: ${counts.error}`);
+  if (!endpoint && counts.written_local > 0) {
     console.log(dim(`  Local sessions saved under ${outDir}.`));
     console.log(dim(`  Server-side codex ingest will be wired in a follow-up phase.`));
   }
-  if (errors > 0) process.exit(2);
+  if (counts.error > 0) process.exit(2);
+}
+
+function tallyCodexIngestResults(results) {
+  const counts = { written_local: 0, ingested: 0, dry_run: 0, skipped: 0, error: 0 };
+  for (const r of results) {
+    incrementCount(counts, r.status);
+    if (r.status === 'error') console.error(formatCodexIngestError(r));
+  }
+  return counts;
+}
+
+function formatCodexIngestError(result) {
+  return `  ${red('error')} ${result.file}: ${result.reason}${result.detail ? ' — ' + result.detail : ''}`;
 }
 
 async function cmdCodeIngest() {
@@ -518,17 +593,17 @@ async function cmdCodeIngest() {
     dryRun,
   });
   if (!results.length) return;
-  let ingested = 0;
-  let skipped = 0;
-  let errors = 0;
+  const counts = { ingested: 0, skipped: 0, error: 0 };
   for (const r of results) {
-    if (r.status === 'ingested') ingested++;
-    else if (r.status === 'skipped_unchanged' || r.status === 'skipped' || r.status === 'dry_run') skipped++;
-    else if (r.status === 'error') errors++;
+    if (r.status === 'skipped_unchanged' || r.status === 'dry_run') {
+      incrementCount(counts, 'skipped');
+    } else {
+      incrementCount(counts, r.status);
+    }
   }
   console.log();
-  console.log(`Done. Ingested: ${ingested}  Skipped: ${skipped}  Errors: ${errors}`);
-  if (errors > 0) process.exit(2);
+  console.log(`Done. Ingested: ${counts.ingested}  Skipped: ${counts.skipped}  Errors: ${counts.error}`);
+  if (counts.error > 0) process.exit(2);
 }
 
 async function cmdCodeMemo() {
@@ -578,24 +653,16 @@ async function cmdCodeApply() {
 }
 
 async function cmdCode() {
-  const sub = args[1];
-  switch (sub) {
-    case 'ingest':
-      return cmdCodeIngest();
-    case 'ingest-codex':
-      return cmdCodeIngestCodex();
-    case 'memo':
-      return cmdCodeMemo();
-    case 'apply':
-      return cmdCodeApply();
-    default:
-      console.error(`Unknown subcommand: dashclaw code ${sub || '(missing)'}\n` +
-                    'Try: dashclaw code ingest [--dry-run]\n' +
-                    '     dashclaw code ingest-codex [--dry-run] [--out <dir>] [--endpoint <url>]\n' +
-                    '     dashclaw code memo --project=<slug> [--save]\n' +
-                    '     dashclaw code apply <manifestId> --dest=<dir> [--yes]');
-      process.exit(1);
-  }
+  return runSubcommand({
+    ingest: cmdCodeIngest,
+    'ingest-codex': cmdCodeIngestCodex,
+    memo: cmdCodeMemo,
+    apply: cmdCodeApply,
+  }, args[1], (sub) => `Unknown subcommand: dashclaw code ${sub || '(missing)'}\n` +
+    'Try: dashclaw code ingest [--dry-run]\n' +
+    '     dashclaw code ingest-codex [--dry-run] [--out <dir>] [--endpoint <url>]\n' +
+    '     dashclaw code memo --project=<slug> [--save]\n' +
+    '     dashclaw code apply <manifestId> --dest=<dir> [--yes]');
 }
 
 // -- prompts subcommand group ------------------------------------------------
@@ -839,36 +906,42 @@ function inboxClient() {
 }
 
 async function cmdInboxList() {
-  const unread = args.includes('--unread');
-  const limitFlag = getFlag('--limit');
   try {
-    const data = await apiRequest(inboxClient(), 'GET', '/api/messages', {
-      query: {
-        agent_id: agentId,
-        direction: 'inbox',
-        unread: unread ? 'true' : undefined,
-        limit: limitFlag,
-      },
-    });
-    const messages = data.messages || [];
-    if (messages.length === 0) {
-      console.log(dim('  No messages.'));
-    } else {
-      for (const m of messages) {
-        const readMark = m.is_read ? dim('read') : green('unread');
-        console.log(
-          `  ${bold(m.id)}  ${dim('from')} ${m.from_agent_id || '-'}  ${m.subject || dim('(no subject)')}  [${readMark}]`,
-        );
-      }
-    }
-    console.log();
-    console.log(dim(`  unread: ${data.unread_count ?? 0}`));
+    const data = await apiRequest(inboxClient(), 'GET', '/api/messages', { query: inboxListQuery() });
+    renderInboxList(data);
   } catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
 }
 
+function inboxListQuery() {
+  return {
+    agent_id: agentId,
+    direction: 'inbox',
+    unread: args.includes('--unread') ? 'true' : undefined,
+    limit: getFlag('--limit'),
+  };
+}
+
+function renderInboxList(data) {
+  const messages = data.messages || [];
+  if (messages.length === 0) {
+    console.log(dim('  No messages.'));
+  } else {
+    messages.forEach(renderInboxMessage);
+  }
+  console.log();
+  console.log(dim(`  unread: ${data.unread_count ?? 0}`));
+}
+
+function renderInboxMessage(message) {
+  const readMark = message.is_read ? dim('read') : green('unread');
+  console.log(
+    `  ${bold(message.id)}  ${dim('from')} ${message.from_agent_id || '-'}  ${message.subject || dim('(no subject)')}  [${readMark}]`,
+  );
+}
+
 async function cmdInboxUpdate(action) {
   const ids = args.slice(2).filter((a) => !a.startsWith('--'));
   if (ids.length === 0) {
@@ -887,21 +960,14 @@ async function cmdInboxUpdate(action) {
 }
 
 async function cmdInbox() {
-  const sub = args[1];
-  switch (sub) {
-    case 'list':
-      return cmdInboxList();
-    case 'read':
-      return cmdInboxUpdate('read');
-    case 'archive':
-      return cmdInboxUpdate('archive');
-    default:
-      console.error(`Unknown subcommand: dashclaw inbox ${sub || '(missing)'}\n` +
-                    'Try: dashclaw inbox list [--unread] [--limit N]\n' +
-                    '     dashclaw inbox read <id> [<id> ...]\n' +
-                    '     dashclaw inbox archive <id> [<id> ...]');
-      process.exit(1);
-  }
+  return runSubcommand({
+    list: cmdInboxList,
+    read: () => cmdInboxUpdate('read'),
+    archive: () => cmdInboxUpdate('archive'),
+  }, args[1], (sub) => `Unknown subcommand: dashclaw inbox ${sub || '(missing)'}\n` +
+    'Try: dashclaw inbox list [--unread] [--limit N]\n' +
+    '     dashclaw inbox read <id> [<id> ...]\n' +
+    '     dashclaw inbox archive <id> [<id> ...]');
 }
 
 // -- behavior subcommand group -----------------------------------------------
@@ -918,20 +984,28 @@ function behaviorClient() {
 async function cmdBehaviorStatus() {
   try {
     const data = await apiRequest(behaviorClient(), 'GET', '/api/behavior/samples');
-    console.log(`  Recorder:   ${data.recorder_enabled ? green('on') : dim('off')}`);
-    console.log(`  Directory:  ${dim(data.dir || '-')}`);
-    console.log(`  Samples:    ${bold(String(data.sample_count ?? 0))}  ${dim('across')} ${data.agent_count ?? 0} ${dim('agent(s)')}`);
-    console.log(`  Window:     ${dim((data.oldest_ts || '-') + ' → ' + (data.newest_ts || '-'))}`);
-    console.log(`  Ready:      ${data.ready ? green('yes') : dim('no — need ' + (data.min_samples ?? 8) + '+ samples for an agent')}`);
-    for (const a of data.agents || []) {
-      console.log(`    ${a.agent_id}  ${dim(a.count + ' samples')}`);
-    }
+    renderBehaviorStatus(data);
   } catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
 }
 
+function behaviorReadyLabel(data) {
+  return data.ready ? green('yes') : dim('no — need ' + (data.min_samples ?? 8) + '+ samples for an agent');
+}
+
+function renderBehaviorStatus(data) {
+  console.log(`  Recorder:   ${data.recorder_enabled ? green('on') : dim('off')}`);
+  console.log(`  Directory:  ${dim(data.dir || '-')}`);
+  console.log(`  Samples:    ${bold(String(data.sample_count ?? 0))}  ${dim('across')} ${data.agent_count ?? 0} ${dim('agent(s)')}`);
+  console.log(`  Window:     ${dim((data.oldest_ts || '-') + ' → ' + (data.newest_ts || '-'))}`);
+  console.log(`  Ready:      ${behaviorReadyLabel(data)}`);
+  for (const a of data.agents || []) {
+    console.log(`    ${a.agent_id}  ${dim(a.count + ' samples')}`);
+  }
+}
+
 async function cmdBehaviorSuggestions() {
   const agent = getFlag('--agent-id') || agentId;
   try {
@@ -958,18 +1032,12 @@ async function cmdBehaviorSuggestions() {
 }
 
 async function cmdBehavior() {
-  const sub = args[1];
-  switch (sub) {
-    case 'status':
-      return cmdBehaviorStatus();
-    case 'suggestions':
-      return cmdBehaviorSuggestions();
-    default:
-      console.error(`Unknown subcommand: dashclaw behavior ${sub || '(missing)'}\n` +
-                    'Try: dashclaw behavior status\n' +
-                    '     dashclaw behavior suggestions [--agent-id X]');
-      process.exit(1);
-  }
+  return runSubcommand({
+    status: cmdBehaviorStatus,
+    suggestions: cmdBehaviorSuggestions,
+  }, args[1], (sub) => `Unknown subcommand: dashclaw behavior ${sub || '(missing)'}\n` +
+    'Try: dashclaw behavior status\n' +
+    '     dashclaw behavior suggestions [--agent-id X]');
 }
 
 // -- posture subcommand group ------------------------------------------------
@@ -993,31 +1061,47 @@ function printFinding(f, indent = '   ') {
   console.log(dim(`${indent}    ${f.key}`));
 }
 
+function postureStatusLabel(status) {
+  if (status === 'healthy') return green(status);
+  if (status === 'at_risk') return red(status);
+  return status;
+}
+
+function renderPostureHeader(data) {
+  console.log();
+  console.log(`  ${bold('Governance posture')}  ${bold(String(data.score))}${dim('/100')}  ${postureStatusLabel(data.status)}` +
+    `${data.cappedBy ? '  ' + red('[capped: incident]') : ''}`);
+  console.log(dim(`  ${data.summary?.openFindings ?? 0} open · +${Math.round(data.summary?.pointsRecoverable ?? 0)} points recoverable`));
+  console.log();
+}
+
+function renderPostureDimensions(dimensions) {
+  for (const d of dimensions || []) {
+    const label = POSTURE_DIM_LABEL[d.dimension] || d.dimension;
+    const mark = d.score < 70 ? red('!') : ' ';
+    console.log(`   ${mark} ${label.padEnd(12)} ${String(d.score).padStart(3)}`);
+  }
+  console.log();
+}
+
+function renderPostureQueue(findings) {
+  console.log(dim(`  Next — ${findings.length} open`));
+  if (findings.length === 0) {
+    console.log(green('   Queue is clear — no open coverage gaps.'));
+    return;
+  }
+  for (const f of findings.slice(0, 5)) printFinding(f);
+  if (findings.length > 5) console.log(dim(`   … ${findings.length - 5} more`));
+}
+
 async function cmdPostureShow() {
   try {
     const client = postureClient();
     const [data, queue] = await Promise.all([fetchPosture(client), fetchFindings(client)]);
-    const status = data.status === 'healthy' ? green(data.status)
-      : data.status === 'at_risk' ? red(data.status) : data.status;
-    console.log();
-    console.log(`  ${bold('Governance posture')}  ${bold(String(data.score))}${dim('/100')}  ${status}` +
-      `${data.cappedBy ? '  ' + red('[capped: incident]') : ''}`);
-    console.log(dim(`  ${data.summary?.openFindings ?? 0} open · +${Math.round(data.summary?.pointsRecoverable ?? 0)} points recoverable`));
-    console.log();
-    for (const d of data.dimensions || []) {
-      const label = POSTURE_DIM_LABEL[d.dimension] || d.dimension;
-      const mark = d.score < 70 ? red('!') : ' ';
-      console.log(`   ${mark} ${label.padEnd(12)} ${String(d.score).padStart(3)}`);
-    }
-    console.log();
     const findings = queue.findings || [];
-    console.log(dim(`  Next — ${findings.length} open`));
-    if (findings.length === 0) {
-      console.log(green('   Queue is clear — no open coverage gaps.'));
-    } else {
-      for (const f of findings.slice(0, 5)) printFinding(f);
-      if (findings.length > 5) console.log(dim(`   … ${findings.length - 5} more`));
-    }
+    renderPostureHeader(data);
+    renderPostureDimensions(data.dimensions);
+    renderPostureQueue(findings);
     console.log();
   } catch (err) {
     console.error(`Error: ${err.message}`);
@@ -1077,18 +1161,79 @@ async function cmdNext() {
   }
 }
 
+// -- env command ---------------------------------------------------------------
+//
+// `dashclaw env [--agent <id>] -- <command...>` — managed-secrets delivery.
+// Fetches the delivery-enabled bundle (GET /api/secrets/env) and spawns the
+// child command with the values injected into its environment MEMORY-ONLY.
+// Secret VALUES are never printed, never written to disk, never echoed in
+// error paths; only NAMES are ever shown. Fail-closed: if the fetch fails,
+// the child is NOT run. Uses process.exitCode (not process.exit) so node
+// drains sockets — a hard exit can trip a libuv teardown assert on Windows.
+
+async function cmdEnv() {
+  const { flags, command: childArgv } = splitEnvArgv(args.slice(1));
+
+  if (flags.includes('--print')) {
+    console.error('Error: --print is not supported. Secret values are memory-only by design —');
+    console.error('they are injected into a child process environment, never printed or written to disk.');
+    console.error('Use `dashclaw env` to list secret NAMES, or `dashclaw env -- <command>` to run with them.');
+    process.exitCode = 1;
+    return;
+  }
+
+  let agent = agentId;
+  for (let i = 0; i < flags.length; i++) {
+    if (flags[i] === '--agent') agent = flags[i + 1];
+    else if (flags[i].startsWith('--agent=')) agent = flags[i].slice('--agent='.length);
+  }
+  if (!agent) {
+    console.error('Error: no agent id. Pass --agent <id> or set DASHCLAW_AGENT_ID.');
+    process.exitCode = 1;
+    return;
+  }
+
+  let bundle;
+  try {
+    bundle = await fetchAgentEnv({ baseUrl, apiKey }, agent);
+  } catch (err) {
+    console.error(`Error: could not fetch the managed-secrets bundle: ${err.message}`);
+    if (childArgv.length > 0) {
+      console.error('Fail-closed: the command was NOT run without the requested env.');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (childArgv.length === 0) {
+    console.log(formatEnvNames(bundle));
+    return;
+  }
+
+  process.exitCode = await runWithEnv(bundle, childArgv);
+}
+
 // -- Router -------------------------------------------------------------------
 
-const COMMANDS_NEEDING_CONFIG = new Set(['approvals', 'approve', 'deny', 'doctor', 'code', 'prompts', 'inbox', 'behavior', 'posture', 'next']);
+const COMMANDS_NEEDING_CONFIG = new Set(['approvals', 'approve', 'deny', 'doctor', 'code', 'prompts', 'inbox', 'behavior', 'posture', 'next', 'env']);
 // `install` deliberately omitted: provisioning hooks and AGENTS.md shouldn't
 // require the user to have already configured API keys. If config happens to
 // be present, install will pick up baseUrl for the AGENTS.md instance link.
 // `codex notify` also opt-in: if no config, the notify fail-softs to skipped
 // rather than erroring (Codex never sees the error anyway — it spawns with
 // stdio nulled).
-const COMMANDS_OPTIONAL_CONFIG = new Set(['install', 'codex']);
+// `cost` resolves config non-interactively and prints its own setup hint when
+// missing (the generic interactive prompt would be the wrong UX for a
+// read-only readback command).
+const COMMANDS_OPTIONAL_CONFIG = new Set(['install', 'codex', 'cost']);
+
+function applyConfig(config) {
+  baseUrl = config.baseUrl;
+  apiKey = config.apiKey;
+  agentId = config.agentId;
+}
 
-async function main() {
+async function loadCommandConfig() {
   if (COMMANDS_NEEDING_CONFIG.has(command)) {
     const config = await resolveConfig();
     if (!config) {
@@ -1096,68 +1241,51 @@ async function main() {
       console.error('Set them as env vars, save with an interactive first run, or use a .env file.');
       process.exit(1);
     }
-    baseUrl = config.baseUrl;
-    apiKey = config.apiKey;
-    agentId = config.agentId;
-  } else if (COMMANDS_OPTIONAL_CONFIG.has(command)) {
+    applyConfig(config);
+    return;
+  }
+  if (COMMANDS_OPTIONAL_CONFIG.has(command)) {
     const config = await resolveConfig({ interactive: false }).catch(() => null);
     if (config) {
-      baseUrl = config.baseUrl;
-      apiKey = config.apiKey;
-      agentId = config.agentId;
+      applyConfig(config);
     }
   }
+}
 
-  switch (command) {
-    case 'approvals':
-      await cmdApprovals();
-      break;
-    case 'approve':
-      await cmdApprove();
-      break;
-    case 'deny':
-      await cmdDeny();
-      break;
-    case 'doctor':
-      await cmdDoctor();
-      break;
-    case 'logout':
-      await cmdLogout();
-      break;
-    case 'code':
-      await cmdCode();
-      break;
-    case 'install':
-      await cmdInstall();
-      break;
-    case 'codex':
-      await cmdCodex();
-      break;
-    case 'prompts':
-      await cmdPrompts();
-      break;
-    case 'inbox':
-      await cmdInbox();
-      break;
-    case 'behavior':
-      await cmdBehavior();
-      break;
-    case 'posture':
-      await cmdPosture();
-      break;
-    case 'next':
-      await cmdNext();
-      break;
-    case 'help':
-    case '--help':
-    case '-h':
-      await cmdHelp();
-      break;
-    default:
-      console.error(`Unknown command: ${command}`);
-      await cmdHelp();
-      process.exit(1);
+const COMMAND_HANDLERS = {
+  approvals: cmdApprovals,
+  approve: cmdApprove,
+  deny: cmdDeny,
+  doctor: cmdDoctor,
+  logout: cmdLogout,
+  code: cmdCode,
+  install: cmdInstall,
+  codex: cmdCodex,
+  prompts: cmdPrompts,
+  inbox: cmdInbox,
+  behavior: cmdBehavior,
+  posture: cmdPosture,
+  cost: cmdCost,
+  next: cmdNext,
+  env: cmdEnv,
+  help: cmdHelp,
+  '--help': cmdHelp,
+  '-h': cmdHelp,
+  version: cmdVersion,
+  '--version': cmdVersion,
+  '-v': cmdVersion,
+};
+
+async function main() {
+  await loadCommandConfig();
+  const handler = COMMAND_HANDLERS[command];
+  if (handler) {
+    await handler();
+    return;
   }
+  console.error(`Unknown command: ${command}`);
+  await cmdHelp();
+  process.exitCode = 1;
 }
 
 main();