codehere 0.5.0-alpha.5 → 0.6.0-alpha.1

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')

package/dist/infrastructure/cost/budget-config.js

@@ -0,0 +1,113 @@
+/**
+ * v0.6 S3 slice 2 — daily spend budget config.
+ *
+ * Reads ~/.codehere/budget.yaml. The pre-spawn check in /api/task compares
+ * computeSpendToday().totalUsd against `daily_usd`; over-budget refuses with
+ * a friendly message instead of silently spawning another paid call.
+ *
+ * Why this is the v1 promise · claim_market_position v3 lists "cost-bounded
+ * execution" as one of the few capture-strategy edges still possibly open.
+ * Slice 1 surfaced spend; slice 2 enforces it. Together they make the edge
+ * demonstrable in 60 seconds: set a $1 budget, spawn until you hit it,
+ * watch codehere refuse the next spawn.
+ *
+ * Schema (~/.codehere/budget.yaml):
+ *
+ *   daily_usd: 5.00      # null / omitted = no budget enforcement
+ *   warn_at_pct: 70      # default 70 — chip turns yellow at 70%
+ *
+ * Single-file, hand-editable, plain YAML. Per claim_user_persona HIGH:
+ * non-technical users can edit it directly. Per overconfidence-guard:
+ * the budget is a USER ceiling, not a codehere guarantee — we can't
+ * see the actual provider invoice in real time.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+const DEFAULT_CONFIG = {
+    dailyUsd: null,
+    warnAtPct: 70,
+};
+function configFile() {
+    return join(homedir(), '.codehere', 'budget.yaml');
+}
+/** Parse a tiny subset of YAML — `key: value` pairs, # comments, blank lines.
+ *  No nesting, no lists, no multi-line. Same approach as permissions-config:
+ *  keep the dependency surface zero, schema simple. */
+function parseYaml(content) {
+    const out = {};
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.replace(/#.*$/, '').trim();
+        if (!line)
+            continue;
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const val = line.slice(colonIdx + 1).trim();
+        if (key)
+            out[key] = val;
+    }
+    return out;
+}
+/** Read the budget config from disk. Missing file or parse failure → defaults
+ *  (no enforcement). Best-effort: never throws — a corrupt file should not
+ *  break the spawn path. */
+export function loadBudget() {
+    const path = configFile();
+    if (!existsSync(path))
+        return { ...DEFAULT_CONFIG };
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = parseYaml(raw);
+        const cfg = { ...DEFAULT_CONFIG };
+        if ('daily_usd' in parsed) {
+            const n = Number(parsed.daily_usd);
+            cfg.dailyUsd = Number.isFinite(n) && n > 0 ? n : null;
+        }
+        if ('warn_at_pct' in parsed) {
+            const n = Number(parsed.warn_at_pct);
+            cfg.warnAtPct = Number.isFinite(n) && n > 0 && n <= 100 ? n : DEFAULT_CONFIG.warnAtPct;
+        }
+        return cfg;
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/** Persist the budget config. Creates ~/.codehere/ if missing. Comments
+ *  in the emitted YAML help a non-technical user edit it later. */
+export function saveBudget(cfg) {
+    const path = configFile();
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const lines = [
+        '# codehere daily-spend budget. Edit by hand or via `codehere budget set <amount>`.',
+        '# daily_usd: hard ceiling for today\'s estimated spend. Set to a number to enable.',
+        '# Leave commented out / omit to disable budget enforcement entirely.',
+    ];
+    if (cfg.dailyUsd !== null) {
+        lines.push(`daily_usd: ${cfg.dailyUsd}`);
+    }
+    else {
+        lines.push('# daily_usd: 5.00');
+    }
+    lines.push(`warn_at_pct: ${cfg.warnAtPct}`);
+    lines.push('');
+    writeFileSync(path, lines.join('\n'), 'utf-8');
+}
+/** True when today's estimated spend has hit or exceeded the daily ceiling.
+ *  Returns false when no budget is set (no enforcement). */
+export function isOverBudget(spentTodayUsd, cfg = loadBudget()) {
+    if (cfg.dailyUsd === null)
+        return false;
+    return spentTodayUsd >= cfg.dailyUsd;
+}
+/** Percentage of today's budget consumed (0-100, or null when no budget set). */
+export function budgetUsedPct(spentTodayUsd, cfg = loadBudget()) {
+    if (cfg.dailyUsd === null || cfg.dailyUsd === 0)
+        return null;
+    return Math.min(100, Math.round((spentTodayUsd / cfg.dailyUsd) * 100));
+}
+//# sourceMappingURL=budget-config.js.map