codehere 0.8.0 → 1.0.2

package/dist/index.js

@@ -1,360 +1,98 @@
 #!/usr/bin/env node
 /**
- * codehere CLI entry · v0.3 PM-for-AI-coding-agents surface.
- *
- * Command surface trimmed to the v0.3 story (see Decision 10 in memory):
- *   setup · config · help · health · status · trust · report · hook ·
- *   serve · start · task · kill · scan-tool · completion
- *
- * v0.2 commands (ask / fix / plan / explain / refactor / index / etc.) and
- * their backing code were removed in the D7 trim. The v0.2 npm releases
- * retain that surface for users who depended on it.
+ * codehere CLI entry: `check` re-runs a project's tests and reports what actually passed.
+ * The earlier orchestrator, daemon, web UI and the other commands are on the legacy/2026-10 branch.
  */
 import { Command } from 'commander';
-import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { homedir } from 'os';
-// ── Global crash safety ───────────────────────────────────────────────────
-// Unhandled rejections and exceptions must never silently kill the daemon.
-process.on('unhandledRejection', (reason) => {
-    console.error('[codehere] unhandledRejection:', reason instanceof Error ? reason.stack : reason);
-});
+import { readFileSync } from 'fs';
+// A crash must stop the process: `process.exitCode = 1` is only honoured once the event loop drains.
+function safeVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf-8')).version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function crashReport(kind, err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    return [
+        '',
+        `[codehere] ${kind} — this process is stopping.`,
+        `  version : ${safeVersion()}`,
+        `  node    : ${process.version} on ${process.platform} ${process.arch}`,
+        '',
+        (e.stack ?? e.message)
+            .split('\n')
+            .map((l) => `  ${l}`)
+            .join('\n'),
+        '',
+        '  Report at https://github.com/muhammadegaa/codehere/issues with the block above.',
+        '',
+    ].join('\n');
+}
 process.on('uncaughtException', (err) => {
-    console.error('[codehere] uncaughtException:', err.stack);
-    // persist what we can before dying
-    process.exitCode = 1;
+    console.error(crashReport('uncaughtException', err));
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    console.error(crashReport('unhandledRejection', reason));
+    process.exit(1);
 });
-import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
-import { executeInitCommand } from './presentation/cli/commands/init-command.js';
-import { executeMemoryCommand } from './presentation/cli/commands/memory-command.js';
-import { executeProtocolsCommand } from './presentation/cli/commands/protocols-command.js';
-import { executeConfigCommand } from './presentation/cli/commands/config-command.js';
+import { executeCheckCommand } from './presentation/cli/commands/check-command.js';
 import { executeHelpCommand } from './presentation/cli/commands/help-command.js';
-import { executeStatusCommand } from './presentation/cli/commands/status-command.js';
-import { executeHookCommand } from './presentation/cli/commands/hook-command.js';
-import { executePermissionCommand } from './presentation/cli/commands/permission-command.js';
-import { executeBudgetCommand } from './presentation/cli/commands/budget-command.js';
-import { executeNarratorCommand } from './presentation/cli/commands/narrator-command.js';
-import { executeTrustCommand } from './presentation/cli/commands/trust-command.js';
-import { executeReportCommand } from './presentation/cli/commands/report-command.js';
-import { executeScanToolCommand } from './presentation/cli/commands/scan-tool-command.js';
-import { executeVerifyCommand } from './presentation/cli/commands/verify-command.js';
-import { executeAuditCommand } from './presentation/cli/commands/audit-command.js';
-import { executeContextSourceCommand } from './presentation/cli/commands/context-source-command.js';
-import { executeThreadCommand } from './presentation/cli/commands/thread-command.js';
-import { displayError } from './presentation/cli/error-display.js';
-import { performHealthCheck, formatHealthStatus, getMetrics } from './monitoring.js';
-import { colors, createBanner, createTable, createWelcomeMessage, success, error, info, sectionHeader, formatNumber, newline, isMinimalStyle, printMinimalHeader, } from './ui.js';
-// Load .env — agent dir first, then cwd
-try {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    const agentDir = join(__dirname, '..');
-    config({ path: join(agentDir, '.env') });
-}
-catch {
-    // Fallback to cwd
-}
-config();
+import { error } from './ui.js';
 import { getVersion } from './utils/version.js';
 import { checkTypo, looksLikeUnknownCommand } from './utils/typo-guard.js';
 const program = new Command();
 program
     .name('codehere')
-    .description('A PM for your AI coding agents. Delegate a task, watch it run, and get a plain-English report with a trust score on every file it changed.')
+    .description('Re-run your project\'s tests yourself, so an AI\'s "all tests pass" is checked, not taken on trust.')
     .version(getVersion())
-    .configureHelp({ helpWidth: 80, sortSubcommands: true })
-    // rc.18: many users hit `codehere --help` first and get Commander's flat
-    // list. The grouped `codehere help` is more useful for discovery. Surface
-    // it inline so muscle-memory `--help` users find the better page.
-    // (Pin: no raw ANSI in --help output — existing commands.test.ts asserts
-    // this, see test/cli/commands.test.ts "no raw ANSI escape codes in --help".)
-    .addHelpText('after', '\nTip: `codehere help` shows commands grouped by use case (Delegate · Safety & Trust · Configuration).');
-// Default action · show welcome, then drop into the interactive REPL on TTY.
-// codehere offers TWO surfaces, both first-class: the CLI REPL (here) and the
-// web UI (`codehere start`). Users pick whichever fits their workflow.
-program
-    // Variadic so multi-token input is preserved end-to-end. Without this,
-    // `codehere fix the bug` would silently drop "the bug" and only delegate
-    // "fix" — and `codehere daemon start` would never see "start", letting the
-    // typo guard miss the unknown-command shape. See typo-guard.ts.
-    .argument('[query...]', 'Optional initial task to delegate (otherwise enter interactive REPL)')
-    .action(async (queryParts) => {
-    const joined = queryParts && queryParts.length > 0 ? queryParts.join(' ') : '';
-    // One-shot delegate: `codehere "review src/auth.ts"` runs that task and exits.
-    // Useful for scripting or quick one-offs without entering the REPL.
-    if (joined && joined.trim()) {
-        const trimmed = joined.trim();
-        // Typo guard — see src/utils/typo-guard.ts for heuristics.
-        // Returns suggestions when input looks like a typo; null falls through.
-        const known = program.commands.map((c) => c.name());
-        const firstToken = trimmed.split(/\s+/)[0];
-        const suggestions = checkTypo(trimmed, known);
-        if (suggestions) {
-            console.error(`codehere: unknown command '${firstToken}'.`);
-            console.error('');
-            console.error('  Did you mean:');
-            for (const s of suggestions)
-                console.error(`    codehere ${s}`);
-            console.error('');
-            console.error(`  If you meant to ask a question, quote it: codehere "${trimmed}"`);
-            process.exit(1);
-        }
-        // Second guard — `cmd subcmd` shape (e.g. `daemon start`) where the first
-        // token isn't close enough for typo suggestions but is clearly a command
-        // attempt rather than a natural-language prompt. Without this, the input
-        // silently spawns an LLM task on the user's behalf and burns API tokens.
-        const unknownFirst = looksLikeUnknownCommand(trimmed, known);
-        if (unknownFirst) {
-            console.error(`codehere: unknown command '${unknownFirst}'.`);
-            console.error('');
-            console.error('  Run `codehere help` to see available commands.');
-            console.error('');
-            console.error('  If you meant to delegate this as a task, either:');
-            console.error(`    codehere task ${trimmed}`);
-            console.error(`    codehere "${trimmed}"`);
-            process.exit(1);
-        }
-        const { runOneShot } = await import('./presentation/cli/repl.js');
-        await runOneShot(trimmed);
-        return;
-    }
-    if (!process.stdin.isTTY) {
-        console.log(createWelcomeMessage());
-        // Non-interactive (piped / scripted): the REPL can't run, so leave the
-        // user with ONE clear next step instead of a dead-end welcome screen.
-        console.log(colors.dim('  Next: ') + colors.cyan('codehere start') + colors.dim('   open the dashboard'));
-        console.log(colors.dim('  New here? ') + colors.cyan('codehere setup') + colors.dim('   one-time setup\n'));
-        return;
-    }
-    const { runInteractiveRepl } = await import('./presentation/cli/repl.js');
-    await runInteractiveRepl();
-});
-// ── setup ────────────────────────────────────────────────────────────────────
-program
-    .command('setup')
-    .description('Interactive setup wizard for first-time users')
-    .option('-f, --force', 'Force reconfiguration even if already set up')
-    .action(async (options) => {
-    await executeSetupCommand(options.force || false);
-});
-// ── init ─────────────────────────────────────────────────────────────────────
-program
-    .command('init')
-    .description('Scaffold .codehere/ in this repo · CONTEXT, HANDOVER, PROMPTS')
-    .option('-f, --force', 'Overwrite existing files in .codehere/')
-    .option('--no-gitignore', 'Skip updating .gitignore')
-    .action((options) => {
-    executeInitCommand({ force: options.force, noGitignore: !options.gitignore });
-});
-// ── memory ───────────────────────────────────────────────────────────────────
-// F3 v0.5: project memory operations. `memory init` migrates v0.4.1 layout
-// (CONTEXT/HANDOVER/PROMPTS) into the four-layer F3 layout (AGENTS.md +
-// memory/ + skills/). `memory repo-map` builds a JSON symbol map. Future:
-// memory show, memory graduate.
-program
-    .command('memory')
-    .description('F3 project memory · init / repo-map / show / graduate / help')
-    .argument('[action]', 'Action: init, repo-map, show, graduate, help')
-    .argument('[layer]', 'Layer for `memory show` (working / episodic / semantic / personal / skills / protocols / injection)')
-    .option('-f, --force', 'Overwrite existing target files (memory init)')
-    .option('--no-symlinks', 'Delete old paths instead of leaving back-compat symlinks (memory init)')
-    .option('--dry-run', 'Print planned moves without touching disk (memory init)')
-    .option('--rebuild', 'Force a fresh build (memory repo-map)')
-    .option('--add <text>', 'Add a free-text lesson directly (memory graduate)')
-    .option('--accept <id>', 'Graduate a candidate by id (memory graduate)')
-    .option('--reject <id>', 'Reject a candidate by id without graduating (memory graduate)')
-    .action((action, layer, options) => {
-    executeMemoryCommand(action, {
-        force: options.force,
-        noSymlinks: !options.symlinks,
-        dryRun: options.dryRun,
-        rebuild: options.rebuild,
-        layer,
-        add: options.add,
-        accept: options.accept,
-        reject: options.reject,
-    });
-});
-// ── protocols ────────────────────────────────────────────────────────────────
-// F3 v0.5: protocols layer operations. `protocols export` writes the
-// trust-scorer pattern bank to .codehere/protocols/hook_patterns.json so
-// auditors / cross-tool consumers can read codehere's safety surface.
-program
-    .command('protocols', { hidden: true }) // hidden from --help (May 2 cut: power-user F3 export, see docs/MEMORY.md)
-    .description('F3 protocols layer · export (write hook_patterns.json from trust-scorer bank)')
-    .argument('[action]', 'Action: export, help')
-    .option('--rebuild', 'Refresh built-in patterns (project patterns are preserved)')
-    .action((action, options) => {
-    executeProtocolsCommand(action, { rebuild: options.rebuild });
-});
-// ── config ───────────────────────────────────────────────────────────────────
-program
-    .command('config')
-    .description('Manage configuration and preferences')
-    .argument('[action]', 'Action: show, get, set, reset')
-    .argument('[key]', 'Preference key (for get/set)')
-    .argument('[value]', 'Preference value (for set)')
-    .action(async (action, key, value) => {
-    await executeConfigCommand(action, key, value);
-});
-// ── help ─────────────────────────────────────────────────────────────────────
-program
-    .command('help')
-    .description('Show help for commands')
-    .argument('[command]', 'Command name to get help for')
-    .option('--all', 'Show all commands (including advanced)')
-    .action(async (commandName, options) => {
-    if (options?.all && !commandName) {
-        for (const cmd of program.commands) {
-            cmd._hidden = false;
-        }
+    .configureHelp({ helpWidth: 80, sortSubcommands: true });
+// Bare `codehere` prints help. Anything else that is not a command goes through the typo guard.
+program.allowExcessArguments(true).action(() => {
+    const input = program.args.join(' ').trim();
+    if (!input) {
         program.outputHelp();
-    }
-    else {
-        await executeHelpCommand(commandName);
-    }
-});
-// ── health ───────────────────────────────────────────────────────────────────
-program
-    .command('health')
-    .description('Check system health and metrics')
-    .option('-m, --metrics', 'Show detailed metrics')
-    .option('--json', 'Machine-readable JSON (for monitoring/CI)')
-    .action((options) => {
-    const health = performHealthCheck();
-    if (options.json) {
-        // Machine-readable: status + checks (+ metrics when --metrics).
-        // Stdout is the contract — never mix with the human banner.
-        // Use process.exitCode (not process.exit) so a piped consumer sees the
-        // full JSON before the process tears down (rc.16: Codex flagged the old
-        // process.exit call as a truncation hazard under stdout redirection).
-        const payload = { status: health.status, checks: health.checks };
-        if (options.metrics)
-            payload.metrics = getMetrics();
-        console.log(JSON.stringify(payload, null, 2));
-        if (health.status === 'unhealthy')
-            process.exitCode = 1;
         return;
     }
-    if (isMinimalStyle()) {
-        printMinimalHeader('health', '');
+    const known = program.commands.map((c) => c.name());
+    const suggestions = checkTypo(input, known);
+    const unknown = suggestions
+        ? input.split(/\s+/)[0]
+        : (looksLikeUnknownCommand(input, known) ?? input.split(/\s+/)[0]);
+    console.error(`codehere: unknown command '${unknown}'.`);
+    console.error('');
+    if (suggestions) {
+        console.error('  Did you mean:');
+        for (const s of suggestions)
+            console.error(`    codehere ${s}`);
     }
     else {
-        newline();
-        console.log(createBanner('System Health', 'Quick status check'));
-        newline();
-    }
-    console.log(formatHealthStatus(health));
-    if (options.metrics) {
-        newline();
-        sectionHeader('Metrics');
-        const metrics = getMetrics();
-        const metricsTable = createTable(['Metric', 'Value'], [
-            ['Total Operations', formatNumber(metrics.operations.total)],
-            ['Successful', formatNumber(metrics.operations.successful)],
-            ['Failed', formatNumber(metrics.operations.failed)],
-            ['Retries', formatNumber(metrics.operations.retries)],
-            ['Avg Response Time', `${metrics.performance.avgResponseTime.toFixed(2)}ms`],
-            ['API Calls', formatNumber(metrics.performance.apiCalls)],
-            ['Cache Hits', formatNumber(metrics.performance.cacheHits)],
-        ]);
-        console.log(metricsTable.toString());
-    }
-    newline();
-    if (health.status === 'unhealthy') {
-        process.exit(1);
+        console.error('  Run `codehere help` to see available commands.');
     }
+    console.error('');
+    process.exit(1);
 });
-// ── status ───────────────────────────────────────────────────────────────────
 program
-    .command('status')
-    .description('Security dashboard — hook activity, blocked calls, cost routing')
-    .option('--json', 'Machine-readable JSON')
-    .option('--tasks', 'Show recent tasks (experimental)')
-    .option('--sessions', 'Show per-session audit trail (multi-agent analysis)')
-    .option('--session <id>', 'Drill into a specific session (first 8+ chars of session ID)')
-    .option('--trust', 'Include a quick trust scan of the current directory')
-    .option('--weekly', 'Show shareable weekly agent-activity recap (last 7 days)')
-    .option('--export <format>', 'Export raw audit events: jsonl, json, csv, or md')
-    .option('--since <duration>', 'Limit --export window, e.g. 24h, 7d, 4w')
-    .option('--env', 'Show environment details')
-    .option('--track', 'Show command success rates')
-    .addHelpText('after', `
-Examples:
-  $ codehere status                          # full dashboard
-  $ codehere status --weekly                 # shareable 7-day agent recap
-  $ codehere status --sessions               # show per-session breakdown
-  $ codehere status --session abc12345       # drill into a specific session
-  $ codehere status --export jsonl > audit.jsonl    # raw audit log export
-  $ codehere status --export csv --since 7d  # 7-day CSV for spreadsheets
-  $ codehere status --export md --since 24h  # 24-hour markdown report
-  `)
-    .action(async (options) => {
-    await executeStatusCommand({
-        json: Boolean(options.json),
-        tasks: Boolean(options.tasks),
-        sessions: Boolean(options.sessions),
-        session: options.session,
-        trust: Boolean(options.trust),
-        weekly: Boolean(options.weekly),
-        export: options.export,
-        since: options.since,
-        env: Boolean(options.env),
-        track: Boolean(options.track),
-    });
-});
-// ── trust ────────────────────────────────────────────────────────────────────
-program
-    .command('trust')
-    .description('Layer 0 trust score — instant static analysis, zero API calls')
-    .argument('[target]', 'File, directory, or omit to scan current directory')
-    .option('--diff [ref]', 'Score a git diff (default: HEAD)')
-    .option('--badge', 'Output shield badge markdown')
-    .option('--json', 'Output JSON report')
-    .option('--verbose', 'Show all findings with line numbers')
-    .option('--ci', 'CI mode: exit 1 if score < 60')
-    .action(async (target, options) => {
-    try {
-        await executeTrustCommand(target, {
-            diff: options?.diff === true ? 'HEAD' : options?.diff,
-            badge: options?.badge,
-            json: options?.json,
-            verbose: options?.verbose,
-            ci: options?.ci,
-        });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── report ───────────────────────────────────────────────────────────────────
-program
-    .command('report')
-    .description('Generate a shareable security audit report — narrative, not just a score')
-    .argument('[target]', 'File or directory to audit (default: current directory)')
-    .option('--out <file>', 'Write report to a specific file (default: codehere-audit.md for markdown)')
-    .option('--stdout', 'Print the report to stdout (already the default for --json)')
-    .option('--json', 'Output machine-readable JSON to stdout (pipe to jq, etc.)')
-    .option('--simple', 'Plain English output — no jargon, for non-technical stakeholders')
-    .addHelpText('after', `
-Examples:
-  $ codehere report                     # writes codehere-audit.md, prints summary
-  $ codehere report src/               # audit a subdirectory
-  $ codehere report --out my-audit.md  # write to a specific path
-  $ codehere report --stdout           # print to terminal (pipe-friendly)
-  $ codehere report --json             # machine-readable output
-  $ codehere report --simple           # plain English for non-technical stakeholders
-  `)
+    .command('check')
+    .description('Re-run your tests independently — proof of what the AI actually did, not what it claimed')
+    .argument('[target]', 'Repo or directory to check (default: current directory)')
+    .option('--json', 'Machine-readable output')
+    .option('--proof', 'Emit a paste-ready proof block for a PR description or review comment')
+    .option('--claim <text>', "The AI's own summary: test files it names that are not in the repo are flagged")
+    .option('--base <ref>', 'Look for weakened tests in everything since this branch left <ref> (e.g. origin/main)')
     .action(async (target, options) => {
     try {
-        await executeReportCommand(target, {
-            out: options?.out,
-            stdout: options?.stdout,
+        process.exitCode = await executeCheckCommand(target, {
             json: options?.json,
-            simple: options?.simple,
+            proof: options?.proof,
+            claim: options?.claim,
+            base: options?.base,
         });
     }
     catch (err) {
@@ -362,680 +100,12 @@ Examples:
         process.exit(1);
     }
 });
-// ── verify ───────────────────────────────────────────────────────────────────
-// v0.7 verifier-agent (F-03). Catches the easy lies a Final Report makes
-// against the structured artifacts recorded during the session.
-program
-    .command('verify')
-    .description("Verify a session's Final Report against the recorded reality (catches optimistic claims)")
-    .argument('[session-id]', 'Session id (or short prefix) to verify. Omit to list recent sessions.')
-    .option('--json', 'Output machine-readable JSON instead of formatted findings')
-    .addHelpText('after', `
-Examples:
-  $ codehere verify                     # list recent sessions to pick from
-  $ codehere verify a1b2c3d4            # verify by short id prefix
-  $ codehere verify a1b2c3d4 --json     # machine-readable verdict for CI
-
-Exit codes:
-  0 = verified, partial (warnings only), or no Final Report to verify
-  1 = broken (a claim contradicts recorded reality)
-  2 = session not found
-  `)
-    .action(async (sessionId, options) => {
-    try {
-        // Per codex Round 2: set exitCode instead of calling process.exit so a
-        // piped --json consumer sees the full payload before Node tears down.
-        // The picker mode can write ~15 sessions worth of JSON · enough to
-        // exceed pipe buffer + race the process exit. exitCode preserves the
-        // intent (CI uses the exit code) without forcing an immediate teardown.
-        process.exitCode = await executeVerifyCommand(sessionId, { json: options.json });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exitCode = 1;
-    }
-});
-// ── audit ────────────────────────────────────────────────────────────────────
-// F-05 of the demo v12 backlog · expose the hash-chain verifier as a CLI.
 program
-    .command('audit')
-    .description('Inspect the hash-chained audit log · verify the chain or show one entry')
-    .argument('[subcommand]', 'verify | show', 'verify')
-    .argument('[arg]', 'For `show`: the sequence number to print.')
-    .option('--json', 'Output machine-readable JSON instead of formatted text')
-    .addHelpText('after', `
-Examples:
-  $ codehere audit                  # equivalent to: codehere audit verify
-  $ codehere audit verify           # walk the chain, report intact/tampered
-  $ codehere audit verify --json    # machine-readable verdict for CI
-  $ codehere audit show 42          # print entry with seq=42
-  $ codehere audit show 42 --json
-
-Exit codes:
-  0 = chain intact OR entry found
-  1 = chain BROKEN (one or more break points detected)
-  2 = invalid input / no entry found
-  `)
-    .action((sub, arg, options) => {
-    try {
-        process.exitCode = executeAuditCommand(sub, arg, { json: options.json });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exitCode = 1;
-    }
-});
-// ── context-source ───────────────────────────────────────────────────────────
-// v0.8 S2.5 · OAuth click-to-connect for Linear, Figma, etc.
-program
-    .command('context-source')
-    .alias('cs')
-    .description('Manage context sources (Linear, Figma) · connect via OAuth, list status, disconnect')
-    .argument('[subcommand]', 'list | connect | disconnect', 'list')
-    .argument('[provider]', 'For connect/disconnect: linear | figma | ...')
-    .option('--json', 'Machine-readable output')
-    .option('--no-open', 'For connect: skip auto-opening the browser (just print the URL)')
-    .addHelpText('after', `
-Examples:
-  $ codehere context-source                    # equivalent to: list
-  $ codehere context-source list
-  $ codehere context-source connect linear
-  $ codehere context-source connect figma --no-open
-  $ codehere context-source disconnect linear
-
-  Tokens persist at ~/.codehere/context-sources.json (0600 mode).
-  Requires the daemon running: codehere start
-  Provider client IDs come from env: CODEHERE_LINEAR_CLIENT_ID, CODEHERE_FIGMA_CLIENT_ID
-  `)
-    .action(async (sub, provider, options) => {
-    try {
-        process.exitCode = await executeContextSourceCommand(sub, provider, {
-            json: options.json,
-            open: options.open,
-        });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exitCode = 1;
-    }
-});
-// ── thread ───────────────────────────────────────────────────────────────────
-// v0.8 S4 · signed-payload "GitHub for agent sessions" · share/import threads
-program
-    .command('thread')
-    .description('Share or import a session · Ed25519-signed bundle · local-first')
-    .argument('<subcommand>', 'export | import | keys | trust | untrust')
-    .argument('[arg]', 'For export: session-id · For import/trust/untrust: file path or pubkey')
-    .argument('[label]', 'For trust: an optional human label for the key')
-    .option('--out <file>', 'For export: write the signed bundle to a file (default: stdout)')
-    .option('--trust', 'For import: trust the signer key automatically if unknown')
-    .option('--json', 'Machine-readable output')
-    .addHelpText('after', `
-Examples:
-  $ codehere thread export a1b2c3d4 --out demo-thread.json
-  $ codehere thread import ./shared.json --trust
-  $ codehere thread keys
-  $ codehere thread trust <pubkey-base64> "Daniel"
-  $ codehere thread untrust <pubkey-base64>
-
-  Bundles include: spawned · steps · artifacts · finalReport · signature.
-  No source code · only the synthesized record.
-  Recipient must trust the signer key (or pass --trust) before replay.
-  `)
-    .action((sub, arg, label, options) => {
-    try {
-        process.exitCode = executeThreadCommand(sub, arg, label, {
-            out: options.out,
-            trust: options.trust,
-            label,
-            json: options.json,
-        });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exitCode = 1;
-    }
-});
-// ── hook ─────────────────────────────────────────────────────────────────────
-program
-    .command('hook')
-    .description('Manage Claude Agent SDK hook integration (intercepts all tool calls)')
-    .argument('[subcommand]', 'install | uninstall | status | log')
-    .option('--log-only', 'Log events but never block (audit mode)')
-    .option('--block-mode <level>', 'Block threshold: critical (default), high, all')
-    .option('--tail <n>', 'Lines to show in log mode', '20')
-    .option('--debug', 'Verbose debug output')
-    .action(async (subcommand, options) => {
-    try {
-        await executeHookCommand(subcommand, {
-            logOnly: options?.logOnly,
-            blockMode: options?.blockMode,
-            tail: options?.tail ? parseInt(options.tail, 10) : undefined,
-            debug: options?.debug,
-        });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── permission (P18 — per-cwd allow/deny list for the trust-scorer) ─────────
-program
-    .command('permission')
-    .description("Manage this folder's .codehere/permissions.yaml allow/deny list")
-    .argument('[subcommand]', 'list | allow | deny | remove')
-    .argument('[pattern]', 'the substring pattern (for allow/deny/remove)')
-    .option('--reason <text>', 'Why this pattern is allow-listed (recorded in audit)')
-    .action(async (subcommand, pattern, options) => {
-    try {
-        await executePermissionCommand(subcommand, pattern, { reason: options?.reason });
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── narrator (S6 — editable PM narrator prompt) ──────────────────────────────
-program
-    .command('narrator')
-    .description('Customize the PM narrator prompt template (~/.codehere/narrator-prompt.md)')
-    .argument('[subcommand]', 'show | edit | reset')
-    .action(async (subcommand) => {
-    try {
-        await executeNarratorCommand(subcommand);
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── budget (S3 — daily-spend ceiling enforcement) ────────────────────────────
-program
-    .command('budget')
-    .description('Set or check the daily spend budget for spawns')
-    .argument('[subcommand]', 'show | set | off')
-    .argument('[value]', 'amount in USD (for `set`)')
-    .action(async (subcommand, value) => {
-    try {
-        await executeBudgetCommand(subcommand, value);
-    }
-    catch (err) {
-        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── serve (MCP server) ───────────────────────────────────────────────────────
-program
-    .command('serve')
-    .description('Run codehere as a background MCP server (no web UI) — for Claude Desktop / Cursor integration')
-    .option('-p, --port <number>', 'Port to listen on', '3773')
-    .option('--host <host>', 'Host to bind to (default: 127.0.0.1)', '127.0.0.1')
-    .option('--token <token>', 'Require Bearer token for authentication')
-    .option('--show-config', 'Print the MCP config block to add to Claude Desktop / Cursor settings')
-    .action(async (options) => {
-    const port = parseInt(options?.port ?? '3773', 10);
-    const host = options?.host ?? '127.0.0.1';
-    const token = options?.token;
-    if (options?.showConfig) {
-        const configBlock = {
-            mcpServers: {
-                codehere: {
-                    url: `http://${host}:${port}/mcp`,
-                    ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}),
-                },
-            },
-        };
-        console.log('\nAdd to Claude Desktop or Cursor MCP settings:\n');
-        console.log(JSON.stringify(configBlock, null, 2));
-        newline();
-        console.log(colors.dim('Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json'));
-        console.log(colors.dim('Cursor: Settings > MCP Servers'));
-        newline();
-        return;
-    }
-    try {
-        const { startMCPServer } = await import('./infrastructure/protocols/mcp-server-impl.js');
-        const server = startMCPServer({ port, host, token });
-        newline();
-        console.log(success(`codehere MCP server running`));
-        newline();
-        console.log(colors.bold('Endpoint:') + `  http://${host}:${port}/mcp`);
-        console.log(colors.bold('Health:') + `    http://${host}:${port}/health`);
-        newline();
-        console.log(colors.bold('Tools available:'));
-        console.log('  codehere_trust   — score a file or snippet (0-100, no API)');
-        console.log('  codehere_scan    — scan text for injection/threats');
-        console.log('  codehere_review  — scan a directory, return riskiest files');
-        console.log('  codehere_audit   — read hook audit log');
-        newline();
-        console.log(colors.dim('  Run with --show-config to get the MCP client config block'));
-        console.log(colors.dim('  Press Ctrl+C to stop'));
-        newline();
-        process.on('SIGINT', () => {
-            server.close();
-            console.log(colors.dim('\ncodehere MCP server stopped'));
-            process.exit(0);
-        });
-        process.on('SIGTERM', () => process.exit(0));
-        await new Promise((resolve) => {
-            server.on('close', resolve);
-        });
-    }
-    catch (err) {
-        console.error(error('Failed to start server:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── start (Mission Control: daemon + web UI) ─────────────────────────────────
-program
-    .command('start')
-    .description('Start codehere — interactive PM dashboard at localhost:3773 (delegate tasks, watch agents work)')
-    .option('-p, --port <number>', 'Port to listen on', '3773')
-    .option('--host <host>', 'Host to bind to', '127.0.0.1')
-    .option('--no-open', "Don't auto-open the browser")
-    .option('--cloud', 'Enable cloud sync — push session state to codehere.uk/app for remote monitoring')
-    .action(async (options) => {
-    const port = parseInt(options?.port ?? '3773', 10);
-    const host = options?.host ?? '127.0.0.1';
-    const shouldOpen = options?.open !== false;
-    const cloud = options?.cloud === true;
-    const url = `http://${host}:${port}/`;
-    const openBrowser = async () => {
-        if (!shouldOpen)
-            return;
-        const { spawn } = await import('child_process');
-        const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-        try {
-            spawn(opener, [url], { detached: true, stdio: 'ignore' }).unref();
-        }
-        catch {
-            /* browser open is best-effort */
-        }
-    };
-    try {
-        // v0.6.0 M1+M7 — migrate sessions.jsonl → ~/.codehere/projects/<slug>/thread.jsonl
-        // on daemon start. Idempotent: skips projects whose thread.jsonl already exists,
-        // so this is safe to run on every boot. Opt-out via CODEHERE_DISABLE_THREAD_MIGRATION=1.
-        // Failures are non-blocking — back-compat to v0.5 sessions.jsonl is preserved.
-        if (process.env.CODEHERE_DISABLE_THREAD_MIGRATION !== '1') {
-            try {
-                const { migrate } = await import('./infrastructure/storage/project-thread-migration.js');
-                const result = migrate({
-                    sourceJsonl: join(process.env.CODEHERE_HOME || homedir(), '.codehere/sessions.jsonl'),
-                    targetDir: join(process.env.CODEHERE_HOME || homedir(), '.codehere/projects'),
-                });
-                if (result.threadsWritten > 0) {
-                    console.log(colors.dim(`  v0.6 migration: created ${result.threadsWritten} project thread(s) from ${result.sessionsProcessed} sessions (${result.durationMs}ms)`));
-                }
-            }
-            catch (err) {
-                console.warn(colors.dim(`  v0.6 migration skipped: ${err instanceof Error ? err.message : String(err)}`));
-            }
-        }
-        // v0.6.0 follow-up — backfill missing titles for projects that the
-        // M9 Title agent never fired on (migration-seeded ones). Runs in the
-        // background so daemon startup isn't blocked by ~5 LLM calls.
-        // Idempotent + best-effort. Same env-var gate as M9 itself.
-        if (process.env.CODEHERE_DISABLE_TITLE_AGENT !== '1') {
-            void (async () => {
-                try {
-                    const { backfillThreadTitles } = await import('./infrastructure/storage/project-thread-title-backfill.js');
-                    const r = await backfillThreadTitles();
-                    if (r.titlesGenerated > 0 && process.env.CODEHERE_DEBUG === '1') {
-                        console.log(colors.dim(`  v0.6 title backfill: titled ${r.titlesGenerated}/${r.scanned} project(s) in ${r.durationMs}ms`));
-                    }
-                }
-                catch {
-                    /* best-effort — silent on failure */
-                }
-            })();
-        }
-        const { startMCPServer } = await import('./infrastructure/protocols/mcp-server-impl.js');
-        const server = startMCPServer({ port, host });
-        // Wait for the server to either start listening or fail. The default
-        // Node behavior on listen() failure is an unhandled 'error' event which
-        // crashes the process with a stack trace. We catch it here so the user
-        // sees a friendly message instead.
-        await new Promise((resolve, reject) => {
-            server.once('listening', () => resolve());
-            server.once('error', reject);
-        });
-        newline();
-        console.log(success('codehere is running'));
-        newline();
-        console.log(colors.bold('Tasks:') + '    ' + url);
-        console.log(colors.bold('History:') + '  ' + `http://${host}:${port}/history`);
-        console.log(colors.bold('MCP:') + '      ' + `http://${host}:${port}/mcp`);
-        if (cloud) {
-            console.log(colors.bold('Cloud:') + '     ' + 'https://codehere.uk/app');
-        }
-        newline();
-        console.log(colors.dim('  Press Ctrl+C to stop'));
-        newline();
-        // Start cloud sync if enabled
-        if (cloud) {
-            const { startCloudSync } = await import('./infrastructure/protocols/cloud-sync.js');
-            startCloudSync();
-        }
-        await openBrowser();
-        const shutdown = () => {
-            try {
-                const { SessionManager } = require('./infrastructure/orchestration/session-manager.js');
-                SessionManager.getInstance().shutdown();
-            }
-            catch {
-                /* graceful degradation — daemon may not have started fully */
-            }
-            if (cloud) {
-                try {
-                    const { stopCloudSync } = require('./infrastructure/protocols/cloud-sync.js');
-                    stopCloudSync();
-                }
-                catch {
-                    /* cloud sync may not be loaded */
-                }
-            }
-            server.close();
-        };
-        process.on('SIGINT', () => {
-            shutdown();
-            console.log(colors.dim('\ncodehere stopped'));
-            process.exit(0);
-        });
-        process.on('SIGTERM', () => {
-            shutdown();
-            process.exit(0);
-        });
-        await new Promise((resolve) => {
-            server.on('close', resolve);
-        });
-    }
-    catch (err) {
-        const code = err?.code;
-        if (code === 'EADDRINUSE') {
-            // Port is taken. Probe to find out by what — if it's a running codehere,
-            // we should hand the user the existing URL; if it's something else,
-            // tell them to pick a different port.
-            const { isCodehereOnPort } = await import('./infrastructure/protocols/probe-port.js');
-            const existing = await isCodehereOnPort(host, port);
-            newline();
-            if (existing.isCodehere) {
-                console.log(success(`codehere is already running at ${url}`));
-                if (existing.version) {
-                    console.log(colors.dim(`  version: ${existing.version}`));
-                }
-                newline();
-                // Honor --no-open here too — found via the v1 stranger walk: a second
-                // `start --no-open` against a running daemon popped a browser anyway.
-                if (shouldOpen) {
-                    console.log(colors.dim('  Opening browser...'));
-                    await openBrowser();
-                }
-                process.exit(0);
-            }
-            console.error(error(`Port ${port} is in use by another process.`));
-            console.error(colors.dim(`  Try: codehere start --port ${port + 1}`));
-            process.exit(1);
-        }
-        console.error(error('Failed to start:'), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
-});
-// ── task (spawn an agent session via CLI) ────────────────────────────────────
-program
-    .command('task <prompt...>')
-    .description('Assign a task — spawns an agent under codehere. Requires `codehere start` running.')
-    .option('-p, --port <number>', 'Daemon port', '3773')
-    .option('--host <host>', 'Daemon host', '127.0.0.1')
-    .option('--agent <id>', 'Which agent to run (claude-code, codex, aider, gemini, opencode). Default: auto.')
-    .option('--watch', 'Watch it work and print the report when it finishes')
-    .addHelpText('after', `
-Examples:
-  $ codehere task "fix the totalValue bug in inventory.js"          # assign, get a session id
-  $ codehere task "add a health check route" --watch               # watch it work + see the report
-  $ codehere task "summarize recent changes" --agent codex --watch # pick the agent
-
-Needs a running daemon: start one with \`codehere start\` (or \`codehere serve\`).`)
-    .action(async (promptParts, options) => {
-    const prompt = promptParts.join(' ').trim();
-    if (!prompt) {
-        console.error(error('No prompt. Usage: codehere task "fix auth bug in session.ts"'));
-        process.exit(1);
-    }
-    const port = parseInt(options?.port ?? '3773', 10);
-    const host = options?.host ?? '127.0.0.1';
-    const base = `http://${host}:${port}`;
-    const http = await import('http');
-    const { waitForDeliverable, formatDeliverable } = await import('./presentation/cli/task-deliverable.js');
-    const spawnResult = await new Promise((resolve) => {
-        const body = JSON.stringify({ prompt, ...(options?.agent ? { agent: options.agent } : {}) });
-        const r = http.request(`${base}/api/task`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
-        }, (res) => {
-            let buf = '';
-            res.on('data', (c) => {
-                buf += c.toString();
-            });
-            res.on('end', () => {
-                try {
-                    resolve(JSON.parse(buf));
-                }
-                catch {
-                    resolve(null);
-                }
-            });
-        });
-        r.on('error', () => resolve(null));
-        r.write(body);
-        r.end();
-    });
-    if (!spawnResult || !spawnResult.sessionId) {
-        if (spawnResult?.error)
-            console.error(error(spawnResult.error));
-        else
-            console.error(error(`Could not reach the daemon at ${base}. Start it with: codehere start`));
-        process.exit(1);
-    }
-    const sid = spawnResult.sessionId;
-    console.log(success(`Task assigned · session ${sid.slice(0, 8)}`));
-    if (!options?.watch) {
-        console.log(colors.dim(`  Watch in the browser: ${base}/`));
-        console.log(colors.dim(`  Or in the terminal:   codehere task "${prompt}" --watch`));
-        console.log(colors.dim(`  Stop it:              codehere kill ${sid.slice(0, 8)}`));
-        return;
-    }
-    // --watch · render the agent's actual steps as they complete, then print
-    // the deliverable (report + files + trust + verifier) when it's done.
-    console.log(colors.dim(`  Watching… (Ctrl-C to stop watching; the agent keeps running)`));
-    const printed = new Set();
-    await new Promise((resolve) => {
-        const r = http.get(`${base}/api/task/${sid}/events`, (res) => {
-            let buf = '';
-            res.on('data', (c) => {
-                buf += c.toString();
-                let i;
-                while ((i = buf.indexOf('\n\n')) >= 0) {
-                    const frame = buf.slice(0, i).trim();
-                    buf = buf.slice(i + 2);
-                    if (!frame.startsWith('data:'))
-                        continue;
-                    try {
-                        const event = JSON.parse(frame.slice(5).trim());
-                        const type = String(event.type || 'message');
-                        if (type === 'codehere:steps') {
-                            const steps = (event.data?.steps ?? []);
-                            for (const s of steps) {
-                                if (s.state !== 'done' && s.state !== 'failed')
-                                    continue;
-                                if (printed.has(s.label))
-                                    continue; // one line per step, on first settle
-                                printed.add(s.label);
-                                const mark = s.state === 'failed' ? colors.error('✗') : colors.success('✓');
-                                const text = s.kind === 'say' ? colors.dim(s.label) : s.label;
-                                console.log(`  ${mark} ${text}`);
-                            }
-                        }
-                        else if (type === 'codehere:error') {
-                            const d = event.data;
-                            if (d?.message)
-                                console.log(`  ${colors.error('!')} ${d.message}`);
-                            if (d?.recovery)
-                                console.log(colors.dim(`    ${d.recovery}`));
-                        }
-                        else if (type === 'exit') {
-                            res.destroy();
-                            resolve();
-                            return;
-                        }
-                    }
-                    catch {
-                        /* skip malformed frame */
-                    }
-                }
-            });
-            res.on('end', () => resolve());
-        });
-        r.on('error', () => resolve());
-    });
-    // The Final Report is generated after exit — poll for it, then print.
-    // Real agents take ~30-60s to write it, so tell the user we're waiting.
-    process.stdout.write(colors.dim('  Writing the report…'));
-    const result = await waitForDeliverable(base, sid);
-    process.stdout.write('\r' + ' '.repeat(24) + '\r'); // clear the waiting line
-    if (result && (result.finalReport || result.failedReport || result.status !== 'completed')) {
-        console.log(formatDeliverable(result));
-    }
-    else if (result) {
-        // Completed, but the report is still generating past our wait window.
-        console.log(formatDeliverable(result));
-        console.log(colors.dim('  (the written report is still being generated — run the command below in a moment)'));
-    }
-    else {
-        console.log(colors.dim('\n  Task finished, but the report could not be fetched from the daemon.'));
-    }
-    console.log(colors.dim(`Next: codehere verify ${sid.slice(0, 8)}   (see this report + the fact-check anytime)`));
-});
-// ── kill (stop a running task) ───────────────────────────────────────────────
-program
-    .command('kill <sessionId>')
-    .description('Kill a running task session.')
-    .option('-p, --port <number>', 'Daemon port', '3773')
-    .option('--host <host>', 'Daemon host', '127.0.0.1')
-    .action(async (sessionId, options) => {
-    const port = parseInt(options?.port ?? '3773', 10);
-    const host = options?.host ?? '127.0.0.1';
-    const http = await import('http');
-    await new Promise((resolve) => {
-        const r = http.request(`http://${host}:${port}/api/task/${sessionId}/kill`, { method: 'POST' }, (res) => {
-            let buf = '';
-            res.on('data', (c) => {
-                buf += c.toString();
-            });
-            res.on('end', () => {
-                if (res.statusCode === 200)
-                    console.log(success(`Killed ${sessionId}`));
-                else
-                    console.error(error(`Failed (${res.statusCode}): ${buf}`));
-                resolve();
-            });
-        });
-        r.on('error', (err) => {
-            console.error(error(err.message));
-            resolve();
-        });
-        r.end();
-    });
-});
-// ── migrate-threads — v0.6.0 schema migration sessions.jsonl → projects/<slug>/thread.jsonl
-program
-    .command('migrate-threads', { hidden: true }) // hidden from --help (v0.6.0 internal — auto-runs on daemon start once wired)
-    .description('Migrate sessions.jsonl into per-project thread.jsonl files (v0.6.0 schema)')
-    .option('--source <path>', 'Source sessions.jsonl', `${process.env.CODEHERE_HOME || homedir()}/.codehere/sessions.jsonl`)
-    .option('--target <dir>', 'Target projects dir', `${process.env.CODEHERE_HOME || homedir()}/.codehere/projects`)
-    .option('--dry-run', 'Report what migrate WOULD do, write nothing', false)
-    .option('--rollback', 'Remove the projects dir; sessions.jsonl untouched', false)
-    .option('--keep-temp-dirs', 'Include /tmp + /var/folders cwds (default skips them)', false)
-    .action(async (options) => {
-    const { migrate, dryRun, rollback } = await import('./infrastructure/storage/project-thread-migration.js');
-    if (options.rollback) {
-        const r = rollback(options.target);
-        console.log(`Rollback: removed ${r.removedDirs} project dir(s) from ${options.target}`);
-        console.log(`Source ${options.source} untouched.`);
-        return;
-    }
-    const fn = options.dryRun ? dryRun : migrate;
-    const label = options.dryRun ? 'DRY RUN' : 'MIGRATION';
-    const result = fn({
-        sourceJsonl: options.source,
-        targetDir: options.target,
-        skipTempDirs: !options.keepTempDirs,
-    });
-    console.log(`=== ${label} ===`);
-    console.log(`  source:                  ${options.source}`);
-    console.log(`  target:                  ${options.target}`);
-    console.log(`  sessions processed:      ${result.sessionsProcessed}`);
-    console.log(`  threads ${options.dryRun ? 'would write' : 'written'}:   ${result.threadsWritten}`);
-    console.log(`  threads skipped (exist): ${result.threadsSkippedExisting}`);
-    console.log(`  unknown-cwd sessions:    ${result.unknownCwdSessions}`);
-    console.log(`  abandoned sessions:      ${result.abandonedSessions}`);
-    console.log(`  temp-dir sessions skipped: ${result.tempDirSessionsSkipped}`);
-    console.log(`  duration:                ${result.durationMs}ms`);
-});
-// ── scan-tool (called by Claude Code hooks system, not users directly) ───────
-program
-    .command('scan-tool', { hidden: true }) // hidden from --help (May 2 cut: internal hook handler, called by Claude Code via stdin)
-    .description('Hook handler: reads Claude Code tool event from stdin, outputs block/allow (used by hook system)')
-    .option('--log-only', 'Never block, log only')
-    .option('--block-all', 'Block on any finding, not just critical')
-    .option('--debug', 'Debug output')
-    .action(async (options) => {
-    await executeScanToolCommand({
-        logOnly: options?.logOnly,
-        blockAll: options?.blockAll,
-        debug: options?.debug,
-    });
-});
-// ── completion (shell completion script generator) ──────────────────────────
-program
-    .command('completion', { hidden: true }) // hidden from --help (May 2 cut: shell-completion is npm convention, not product surface)
-    .description('Generate shell completion script')
-    .argument('<shell>', 'Shell type: bash, zsh, or fish')
-    .action(async (shell) => {
-    try {
-        switch (shell.toLowerCase()) {
-            case 'bash': {
-                const { generateBashCompletion } = await import('./infrastructure/completion/bash-completion.js');
-                console.log(generateBashCompletion());
-                break;
-            }
-            case 'zsh': {
-                const { generateZshCompletion } = await import('./infrastructure/completion/zsh-completion.js');
-                console.log(generateZshCompletion());
-                break;
-            }
-            case 'fish': {
-                const { generateFishCompletion } = await import('./infrastructure/completion/fish-completion.js');
-                console.log(generateFishCompletion());
-                break;
-            }
-            default:
-                console.error(error(`Unsupported shell: ${shell}`));
-                console.log(info('Supported shells: bash, zsh, fish'));
-                console.log(info('Usage: codehere completion <bash|zsh|fish>'));
-                process.exit(1);
-        }
-    }
-    catch (err) {
-        displayError(err, { operation: 'completion', showSuggestions: true });
-        process.exit(1);
-    }
+    .command('help')
+    .description('Show help for commands')
+    .argument('[command]', 'Command name to get help for')
+    .action(async (commandName) => {
+    await executeHelpCommand(commandName);
 });
-// ── slash-command routing: `codehere /trust .` → `codehere trust .` ─────────
-const rawArgs = process.argv.slice(2);
-if (rawArgs.length > 0 && rawArgs[0].startsWith('/') && rawArgs[0].length > 1) {
-    const stripped = rawArgs[0].slice(1);
-    process.argv.splice(2, 1, stripped);
-}
 program.parse();
 //# sourceMappingURL=index.js.map