codehere 0.5.0-alpha.6 → 0.6.0

package/README.md

@@ -1,15 +1,22 @@
 # codehere
 
-> **Every AI action, traced. Every agent, verified.**
+> **Your AI agents shouldn't lock you in.**
+> Codehere keeps your memory, audit, safety, and reports portable across every coding agent you use.
 
 [![npm](https://img.shields.io/npm/v/codehere)](https://www.npmjs.com/package/codehere)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](../LICENSE)
-[![Tests](https://img.shields.io/badge/tests-443%2F443-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-668%2F668-brightgreen)]()
 [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
 
-codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, OpenCode, or Gemini), spawns it, streams its work back to you, and hands you a plain-English Final Report with a **trust score on every file changed**. Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; other adapters are session-traced and reported, with per-tool hook parity planned for v0.4.
+**Codehere is the vendor-neutral layer between you and the coding agents you already use** — Claude Code, Codex, Aider, Gemini, OpenCode. One `npm install`. Local-first, OSS, no account, no IAM, no compliance prereqs. Switch agent, keep your memory. End the day with one Final Report covering everything they did.
 
-One manager, many specialists, every action recorded.
+Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; the other adapters are session-traced and reported, with per-tool hook parity in progress for v0.6. The vendor-neutral *memory*, *audit log*, and *Final Report* surfaces ship across all 5 adapters today.
+
+The enterprise tier is owned by [OpenAI Frontier](https://openai.com/index/introducing-openai-frontier/) (8-14 weeks of deploy prereqs, sales-team gated) and [Anthropic Cowork](https://www.anthropic.com/product/claude-cowork) (paid Claude subscription, single-vendor). Codehere fills the gap they structurally can't reach: **the individual / small-team / no-IT-department tier, vendor-neutral**.
+
+> See [`docs/STRATEGIC_VISION.md`](../docs/STRATEGIC_VISION.md) Appendix C and [`docs/figures/positioning-matrix.svg`](../docs/figures/positioning-matrix.svg) for the full positioning chart.
+
+One layer, every agent, your work stays portable.
 
 ---
 
@@ -22,7 +29,7 @@ One manager, many specialists, every action recorded.
 
 | | | |
 |---|---|---|
-| 1 | **Install** | `npm install -g codehere` (Node 20+) |
+| 1 | **Install** | `npm install -g codehere@alpha` (Node 20+) — current alpha track is v0.5; `@latest` still on v0.4 |
 | 2 | **Detect environment** | `codehere setup` — checks API key, finds your repo |
 | 3 | **Install the safety hook** | `codehere hook install` — every Claude Code tool call now audited |
 | 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode / Gemini also supported · see [docs/integrations/](../docs/integrations/) for Cursor MCP setup) |
@@ -142,6 +149,9 @@ codehere status             · dashboard · sessions, blocked calls, audit trend
 codehere trust [path]       · static trust scan · score 0-100, grade A-F
 codehere report             · generate a shareable markdown audit report
 codehere hook               · install/uninstall/inspect the PreToolUse safety hook
+codehere permission         · manage this folder's allow-list (skip false-positive blocks)
+codehere budget             · daily-spend ceiling · `set <usd>` blocks paid spawns at the cap
+codehere narrator           · customize the PM narrator prompt (~/.codehere/narrator-prompt.md)
 codehere setup              · interactive first-run setup wizard
 codehere config             · manage configuration and preferences
 codehere health             · system health check
@@ -182,10 +192,10 @@ Exposes 4 read-only tools to any MCP client (Claude Desktop, Cursor, Zed, Contin
 
 For depth beyond this README:
 
-- **[CODEHERE.md](../CODEHERE.md)** · product spec · positioning, six-ring adoption funnel, F0–F6 foundations, defensibility, GTM, revenue model
-- **[EXPERIENCE.md](../EXPERIENCE.md)** · the human story · how engineering teams, CISOs, and regulated-industry buyers adopt codehere
-- **[AUDIT.md](../AUDIT.md)** · pre-publish audit report · methodology, findings, remediation
+- **[docs/STRATEGIC_VISION.md](../docs/STRATEGIC_VISION.md)** · 20-year invariants + v4 positioning (individual-tier vendor-neutral) · figures in `docs/figures/`
+- **[docs/PRD.md](../docs/PRD.md)** · master decision document · features, architecture, roadmap
 - **[docs/SECURITY_AUDIT_2026-05-01.md](../docs/SECURITY_AUDIT_2026-05-01.md)** · first-party security audit · OWASP Top 10 + STRIDE · 0 critical / 0 high · 2 medium fixed inline · methodology disclosed · reproducible
+- **[docs/archive/](../docs/archive/)** · earlier living docs (CODEHERE spec, EXPERIENCE story, AUDIT) preserved for history
 - **[CONTRIBUTING.md](../CONTRIBUTING.md)** · how to contribute · setup, commit discipline, testing philosophy
 - **[SECURITY.md](../SECURITY.md)** · responsible disclosure · `security@codehere.uk`
 - **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** · community standards

package/dist/application/use-cases/generate-narration.js

@@ -0,0 +1,111 @@
+/**
+ * PM Narration — v0.6 M3 mid-task summary.
+ *
+ * While a task is in flight, periodically generates a one-paragraph
+ * plain-English summary of what the agent has done so far. Fires on
+ * step-count or elapsed-time thresholds (caller decides when).
+ *
+ * Per claim_user_persona HIGH: non-technical users primary. They don't
+ * read tool calls; they read narration. Mid-task narration tells them
+ * "the agent is currently editing your auth file and ran the tests"
+ * instead of forcing them to interpret a list of Bash/Edit/Read steps.
+ *
+ * Per feedback_overconfidence_guard.md: narration is an LLM call.
+ * Hallucination is possible. Surface MUST frame it as "narrator says…"
+ * not authoritative truth. The PROMPT_TEMPLATE includes the same
+ * anti-hallucination rule as generate-final-report (ground every claim
+ * in the structured data).
+ *
+ * Provider strategy: same as generate-final-report (try claude-free
+ * first, fall back to claude). Returns null if neither is installed.
+ */
+import { spawn } from 'child_process';
+import { loadTemplate, renderTemplate } from './narrator-prompt-template.js';
+/** v0.6 S6 — prompt template lifted into ~/.codehere/narrator-prompt.md so
+ *  the user can edit the agent's voice. loadTemplate() falls back to the
+ *  baked-in default on missing file or missing required placeholders, so
+ *  the prompt is never silently broken. See narrator-prompt-template.ts. */
+function buildPrompt(input) {
+    const { template } = loadTemplate();
+    return renderTemplate(template, input);
+}
+function selectProviderBinary() {
+    // Same precedence as generate-final-report: env override → claude-free → claude.
+    const override = process.env.CODEHERE_NARRATOR_BINARY?.trim();
+    if (override)
+        return [override];
+    return ['claude-free', 'claude'];
+}
+export async function generateNarration(input) {
+    const prompt = buildPrompt(input);
+    const candidates = selectProviderBinary();
+    for (const binary of candidates) {
+        const result = await tryProvider(binary, prompt, input.sessionId, input.steps.length);
+        if (result)
+            return result;
+    }
+    return null;
+}
+function tryProvider(binary, prompt, sessionId, stepCount) {
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        let stdout = '';
+        let stderr = '';
+        let resolved = false;
+        const finish = (val) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(val);
+        };
+        let child;
+        try {
+            // Same shape as generate-final-report's tryProvider — claude --bare -p.
+            child = spawn(binary, ['--bare', '-p', prompt], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        // 20s timeout — narration should be SNAPPIER than Final Report
+        // (which is 60s). Mid-task = the user is actively waiting.
+        const timeout = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+            finish(null);
+        }, 20_000);
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf-8'); });
+        child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf-8'); });
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                // Non-zero usually means binary missing OR the model refused. Either
+                // way silent fail; caller treats null as "no narration this cycle".
+                void stderr;
+                void sessionId;
+                finish(null);
+                return;
+            }
+            const summary = stdout.trim();
+            if (!summary || summary.length < 10) {
+                finish(null);
+                return;
+            }
+            finish({
+                summary,
+                generatedAt: Date.now(),
+                durationMs: Date.now() - startedAt,
+                stepCountAtSnapshot: stepCount,
+            });
+        });
+        child.on('error', () => {
+            clearTimeout(timeout);
+            finish(null);
+        });
+    });
+}
+//# sourceMappingURL=generate-narration.js.map

package/dist/application/use-cases/generate-thread-title.js

@@ -88,9 +88,21 @@ function tryProvider(binary, prompt) {
         });
     });
 }
-/** Strip whitespace / quotes / trailing punctuation. Cap at 80 chars (safety). */
-function sanitizeTitle(raw) {
-    const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+/**
+ * Strip whitespace / quotes / trailing punctuation. Cap at 80 chars.
+ *
+ * Garbage rejection (added 2026-05-06 after dogfood Bug A4): the underlying
+ * `claude --bare` call can return error-shaped text on stdout with exit 0
+ * (rate-limit messages, auth errors, refusals). Pre-fix those flowed straight
+ * into the project sidebar as titles like "Request ID: req_xyz...". We now
+ * detect obvious error / refusal patterns and return '' so the caller falls
+ * back to the cwd-derived title.
+ */
+export function sanitizeTitle(raw) {
+    const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
     if (lines.length === 0)
         return '';
     let title = lines[lines.length - 1]; // last non-empty line is the answer
@@ -101,7 +113,49 @@ function sanitizeTitle(raw) {
     // Cap at 80 chars
     if (title.length > 80)
         title = title.slice(0, 77) + '...';
-    return title.trim();
+    title = title.trim();
+    if (!title)
+        return '';
+    // Garbage rejection — patterns that indicate an error response, NOT a title.
+    // Each pattern matches a real failure mode observed in dogfood:
+    //   - "Request ID: req_..."         → API error envelope leaking through
+    //   - "Error:" / "ERROR" / "error " → generic error prefix
+    //   - "I cannot" / "I can't"        → model refusal
+    //   - "I apologize" / "I'm sorry"   → model refusal
+    //   - "Rate limit" / "rate-limited" → quota error
+    //   - "Authentication" / "Unauthorized" / "401" / "403" → auth failure
+    //   - Long sentences (>10 words)    → not a title; model ignored the rules
+    //   - Contains http:// or https://  → URL leakage from error envelope
+    const lower = title.toLowerCase();
+    const garbageMarkers = [
+        /^request\s+id\s*[:=]/i,
+        /^error\b/i,
+        /\berror[:\s]/i,
+        /^i\s+(cannot|can'?t|am\s+unable|won'?t)\b/i,
+        /^i\s+(apologi[sz]e|am\s+sorry)\b/i,
+        /^i'?m\s+sorry\b/i,
+        /\brate\s*[-_]?\s*limit/i,
+        /\b(authentication|unauthori[sz]ed|forbidden)\b/i,
+        /\b(401|403|429|500|502|503)\b/i,
+        /https?:\/\//i,
+        /api[_-]?key/i,
+    ];
+    if (garbageMarkers.some((re) => re.test(lower))) {
+        if (process.env.CODEHERE_DEBUG === '1') {
+            console.error(`[title-agent] rejected garbage title: ${title.slice(0, 60)}`);
+        }
+        return '';
+    }
+    // Length sanity: a real title is 4-6 words per the prompt; allow up to 10
+    // for slack. Anything longer is the model ignoring instructions.
+    const wordCount = title.split(/\s+/).filter(Boolean).length;
+    if (wordCount > 10) {
+        if (process.env.CODEHERE_DEBUG === '1') {
+            console.error(`[title-agent] rejected long title (${wordCount} words): ${title.slice(0, 60)}`);
+        }
+        return '';
+    }
+    return title;
 }
 /**
  * Generate a thread title from the first user prompt + cwd context.

package/dist/application/use-cases/narrator-prompt-template.js

@@ -0,0 +1,158 @@
+/**
+ * v0.6 S6 — editable PM narrator prompt template.
+ *
+ * The mid-task narration (M3) used to ship a hard-coded prompt baked into
+ * generate-narration.ts. That made the agent's "voice" un-tunable: a user
+ * who wanted shorter / longer / more-jargony / less-jargony narration
+ * had no lever short of forking the source.
+ *
+ * S6 lifts the template into ~/.codehere/narrator-prompt.md, a plain
+ * Markdown file the user edits with whatever editor they like. The file
+ * uses `{{placeholder}}` substitution for the runtime values:
+ *   {{prompt}}            — the user's original task ask (truncated 500ch)
+ *   {{agent}}             — which adapter is running ("claude-code" etc.)
+ *   {{elapsed_seconds}}   — how long the task has been running
+ *   {{step_count}}        — how many steps completed/in-progress
+ *   {{steps}}             — last 15 steps, "  N. [state] label"
+ *
+ * If the file is missing OR the user-edited file is missing required
+ * placeholders, we fall back to the baked-in DEFAULT_TEMPLATE so a typo
+ * never breaks narration silently.
+ *
+ * Per claim_user_persona HIGH: the narrator IS the product voice for
+ * non-technical users. Letting them control it is a v1 promise.
+ *
+ * Per feedback_overconfidence_guard.md: the DEFAULT_TEMPLATE keeps the
+ * anti-hallucination rule + "frame as narrator not authority" cue. Users
+ * editing the template can drop those rules at their own risk; the file
+ * comment warns about it.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+/** The required placeholders. If a user-edited template is missing ANY of
+ *  these we fall back to the default so the rendered prompt is never
+ *  silently broken. {{step_count}} is omitted from the required list — it's
+ *  derivable from {{steps}} and a custom template might intentionally drop it. */
+const REQUIRED_PLACEHOLDERS = ['{{prompt}}', '{{agent}}', '{{elapsed_seconds}}', '{{steps}}'];
+export const DEFAULT_TEMPLATE = `<!--
+  codehere narrator prompt — drives the mid-task summary the user sees as
+  "narrator says…" while their AI coding agent is working. Edit freely.
+
+  Available placeholders (substituted at render time):
+    {{prompt}}            user's original task ask
+    {{agent}}             which adapter is running
+    {{elapsed_seconds}}   how long the task has been running
+    {{step_count}}        number of steps completed/in-progress
+    {{steps}}             last 15 steps, formatted as "  N. [state] label"
+
+  REQUIRED: {{prompt}}, {{agent}}, {{elapsed_seconds}}, {{steps}}.
+  Missing any of those → codehere falls back to its baked-in default.
+
+  Reset to default any time with: codehere narrator reset
+-->
+
+You are a PM giving a 1-sentence-or-2 mid-task update to a non-technical user
+about what their AI coding agent is doing RIGHT NOW. Write ONE short paragraph
+(2-3 sentences). No headers, no bullet lists, no markdown.
+
+CRITICAL anti-hallucination rule: ground every claim in the structured data
+below. Do not invent file names, status, or actions not in the steps list.
+If you don't know what something does, say "the agent is working on …" with
+the literal target. Better to under-claim than to over-claim.
+
+Tone: like a colleague checking in. "It's reading the auth file and ran the
+tests — looks like 2 failed so far." Not robotic, not breathless.
+
+Reference frame for the user (not for the LLM): the user did NOT see this
+list directly; you're translating it for them. The user only sees your
+paragraph.
+
+────────── Structured data (the only source of truth) ──────────
+Task: "{{prompt}}"
+Agent: {{agent}}
+Elapsed: {{elapsed_seconds}}s
+Steps so far ({{step_count}}):
+{{steps}}
+
+Write the paragraph now. Do not preface with "Update:" or anything similar.
+Plain prose. No "I'm currently…" — narrate the AGENT, not yourself.
+`;
+function templateFile() {
+    return join(homedir(), '.codehere', 'narrator-prompt.md');
+}
+/** Read the user-customized template if present and valid. Falls back to
+ *  baked-in default on missing file, parse failure, or missing required
+ *  placeholders (so a typo never silently breaks narration). */
+export function loadTemplate() {
+    const path = templateFile();
+    if (!existsSync(path))
+        return { source: 'default', template: DEFAULT_TEMPLATE };
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return { source: 'default', template: DEFAULT_TEMPLATE };
+    }
+    for (const ph of REQUIRED_PLACEHOLDERS) {
+        if (!raw.includes(ph)) {
+            return { source: 'default', template: DEFAULT_TEMPLATE };
+        }
+    }
+    return { source: 'user', template: raw };
+}
+/** Persist the default template to disk so the user has a starting point
+ *  to edit. Used by `codehere narrator edit`. Doesn't overwrite an existing
+ *  user-edited file unless `force` is set. */
+export function writeDefaultTemplate(force = false) {
+    const path = templateFile();
+    if (!force && existsSync(path))
+        return { wrote: false, path };
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(path, DEFAULT_TEMPLATE, 'utf-8');
+    return { wrote: true, path };
+}
+/** Delete the user-customized template. Future loads use the baked-in
+ *  default. Idempotent: missing file is a no-op success. */
+export function resetTemplate() {
+    const path = templateFile();
+    if (!existsSync(path))
+        return { removed: false, path };
+    try {
+        unlinkSync(path);
+        return { removed: true, path };
+    }
+    catch {
+        return { removed: false, path };
+    }
+}
+/** Substitute the runtime values into the template. Same {{placeholder}}
+ *  protocol as the template-file comments document. */
+export function renderTemplate(template, input) {
+    const stepsBlock = input.steps
+        .slice(-15)
+        .map((s, idx) => `  ${idx + 1}. [${s.state}] ${(s.label ?? '').slice(0, 120)}`)
+        .join('\n');
+    const replacements = {
+        '{{prompt}}': input.prompt.slice(0, 500),
+        '{{agent}}': input.agent,
+        '{{elapsed_seconds}}': String(Math.round(input.elapsedMs / 1000)),
+        '{{step_count}}': String(input.steps.length),
+        '{{steps}}': stepsBlock,
+    };
+    let out = template;
+    for (const [k, v] of Object.entries(replacements)) {
+        // Replace ALL occurrences. Use split/join to avoid regex escaping
+        // pain on the curly braces.
+        out = out.split(k).join(v);
+    }
+    return out;
+}
+/** Path to the user-customized template (for CLI status display). */
+export function templatePath() {
+    return templateFile();
+}
+//# sourceMappingURL=narrator-prompt-template.js.map

package/dist/index.js

@@ -23,6 +23,9 @@ import { executeConfigCommand } from './presentation/cli/commands/config-command
 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';
@@ -41,7 +44,7 @@ catch {
 }
 config();
 import { getVersion } from './utils/version.js';
-import { checkTypo } from './utils/typo-guard.js';
+import { checkTypo, looksLikeUnknownCommand } from './utils/typo-guard.js';
 const program = new Command();
 program
     .name('codehere')
@@ -58,18 +61,24 @@ program
 // codehere offers TWO surfaces, both first-class: the CLI REPL (here) and the
 // web UI (`codehere start`). Users pick whichever fits their workflow.
 program
-    .argument('[query]', 'Optional initial task to delegate (otherwise enter interactive REPL)')
-    .action(async (query) => {
+    // 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 (query && query.trim()) {
-        const trimmed = query.trim();
+    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 '${trimmed}'.`);
+            console.error(`codehere: unknown command '${firstToken}'.`);
             console.error('');
             console.error('  Did you mean:');
             for (const s of suggestions)
@@ -78,6 +87,21 @@ program
             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;
@@ -343,6 +367,51 @@ program
         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')
@@ -411,10 +480,12 @@ program
     .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)
@@ -482,11 +553,23 @@ program
         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();
         process.on('SIGINT', () => {
+            if (cloud) {
+                const { stopCloudSync } = require('./infrastructure/protocols/cloud-sync.js');
+                stopCloudSync();
+            }
             server.close();
             console.log(colors.dim('\ncodehere stopped'));
             process.exit(0);