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

package/dist/infrastructure/storage/project-thread-title-backfill.js

@@ -158,6 +158,34 @@ export async function backfillThreadTitles(options) {
             result.titleAgentFailed++;
             continue;
         }
+        // Race guard: backfill scanned BEFORE the LLM call, but the LLM blocks
+        // for seconds. A user rename in that window leaves a userOverride:true
+        // marker the pre-scan never saw. Re-read the same file just before the
+        // write and skip if the user got there first. (Inlined rather than calling
+        // hasManualOverride() because that helper hardcodes the production
+        // projects dir; backfill supports a custom projectsDir for tests.)
+        let userBeatUs = false;
+        try {
+            const recheck = readFileSync(file, 'utf-8');
+            for (const line of recheck.split('\n')) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                try {
+                    const rec = JSON.parse(t);
+                    if (rec._meta === 'project-update' && rec.userOverride === true) {
+                        userBeatUs = true;
+                        break;
+                    }
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+        catch { /* if we can't read, fall through and let the append fail */ }
+        if (userBeatUs) {
+            result.alreadyTitled++;
+            continue;
+        }
         try {
             const updateLine = JSON.stringify({
                 _meta: 'project-update',

package/dist/presentation/cli/commands/budget-command.js

@@ -0,0 +1,79 @@
+/**
+ * `codehere budget` — read or set the daily-spend budget.
+ *
+ * Subcommands:
+ *   show               — print current ceiling, today's spend, % used
+ *   set <usd>          — set daily ceiling in USD (e.g. `codehere budget set 5`)
+ *   off                — disable the budget (omits daily_usd from yaml)
+ *
+ * Reads + writes ~/.codehere/budget.yaml via budget-config.ts. Per
+ * claim_user_persona HIGH the YAML is hand-editable; the CLI is the
+ * fast path for users who want one number, one command.
+ */
+import { loadBudget, saveBudget, budgetUsedPct, isOverBudget } from '../../../infrastructure/cost/budget-config.js';
+import { computeSpendToday } from '../../../infrastructure/cost/spend-aggregator.js';
+import { success, error, info, newline } from '../../../ui.js';
+export async function executeBudgetCommand(subcommand, value) {
+    const sub = subcommand ?? 'show';
+    switch (sub) {
+        case 'show':
+            return showBudget();
+        case 'set':
+            if (!value) {
+                console.error(error('Usage:'), 'codehere budget set <amount-in-usd>   e.g. codehere budget set 5');
+                process.exit(1);
+            }
+            return setBudget(value);
+        case 'off':
+            return disableBudget();
+        default:
+            console.error(error('Unknown subcommand:'), sub);
+            console.error(info('Try:'), 'codehere budget [show | set <usd> | off]');
+            process.exit(1);
+    }
+}
+function fmtUsd(n) {
+    return n >= 0.01 ? `$${n.toFixed(2)}` : `$${n.toFixed(3)}`;
+}
+function showBudget() {
+    const cfg = loadBudget();
+    const spend = computeSpendToday();
+    newline();
+    console.log(info('Today\'s estimated spend:'), fmtUsd(spend.totalUsd), `(${spend.sessionCount} session${spend.sessionCount === 1 ? '' : 's'})`);
+    if (cfg.dailyUsd === null) {
+        console.log(info('Daily budget:'), 'none — no enforcement');
+        console.log(info('Set one with:'), 'codehere budget set 5');
+    }
+    else {
+        const pct = budgetUsedPct(spend.totalUsd, cfg) ?? 0;
+        const over = isOverBudget(spend.totalUsd, cfg);
+        console.log(info('Daily budget:'), fmtUsd(cfg.dailyUsd), `(${pct}% used)`);
+        if (over) {
+            console.log(error('Over budget.'), 'New spawns are blocked until midnight or the budget is raised.');
+        }
+        else if (pct >= cfg.warnAtPct) {
+            console.log(info('Approaching limit.'), `Warn threshold is ${cfg.warnAtPct}%.`);
+        }
+    }
+    newline();
+}
+function setBudget(value) {
+    const n = Number(value.replace(/[$,]/g, ''));
+    if (!Number.isFinite(n) || n <= 0) {
+        console.error(error('Invalid amount:'), value, '— expected a positive USD number.');
+        process.exit(1);
+    }
+    const cfg = loadBudget();
+    cfg.dailyUsd = n;
+    saveBudget(cfg);
+    console.log(success('Daily budget set to'), fmtUsd(n));
+    console.log(info('Spawns will be blocked once today\'s estimated spend reaches this amount.'));
+    console.log(info('Disable with:'), 'codehere budget off');
+}
+function disableBudget() {
+    const cfg = loadBudget();
+    cfg.dailyUsd = null;
+    saveBudget(cfg);
+    console.log(success('Daily budget disabled.'), 'No enforcement on spawns.');
+}
+//# sourceMappingURL=budget-command.js.map

package/dist/presentation/cli/commands/narrator-command.js

@@ -0,0 +1,101 @@
+/**
+ * `codehere narrator` — read or customize the PM narrator prompt template.
+ *
+ * Subcommands:
+ *   show                  — print active template + source (user / default)
+ *                           and the path codehere reads
+ *   edit                  — write the default template to ~/.codehere/narrator-prompt.md
+ *                           if it doesn't already exist, then open in $EDITOR
+ *                           (or print the path if no $EDITOR set)
+ *   reset                 — delete the user-edited file, fall back to default
+ *
+ * The template uses {{placeholder}} substitution. Required placeholders:
+ *   {{prompt}}, {{agent}}, {{elapsed_seconds}}, {{steps}}
+ * Missing any → silent fallback to baked-in default at render time, so a
+ * typo never breaks narration.
+ *
+ * Per claim_user_persona HIGH: the narrator IS the agent's voice for
+ * non-technical users. Letting them control it is a v1 promise.
+ */
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { loadTemplate, resetTemplate, templatePath, writeDefaultTemplate, DEFAULT_TEMPLATE, } from '../../../application/use-cases/narrator-prompt-template.js';
+import { error, info, newline, success } from '../../../ui.js';
+export async function executeNarratorCommand(subcommand) {
+    const sub = subcommand ?? 'show';
+    switch (sub) {
+        case 'show':
+            return showNarrator();
+        case 'edit':
+            return editNarrator();
+        case 'reset':
+            return resetNarrator();
+        default:
+            console.error(error('Unknown subcommand:'), sub);
+            console.error(info('Try:'), 'codehere narrator [show | edit | reset]');
+            process.exit(1);
+    }
+}
+function showNarrator() {
+    const { source, template } = loadTemplate();
+    const path = templatePath();
+    newline();
+    console.log(info('Active template source:'), source === 'user' ? 'user-edited file' : 'baked-in default');
+    console.log(info('Path:'), path);
+    if (source === 'user') {
+        const sizeBytes = existsSync(path) ? readFileSync(path, 'utf-8').length : 0;
+        console.log(info('User file size:'), `${sizeBytes} bytes`);
+    }
+    else {
+        console.log(info('Customize with:'), 'codehere narrator edit');
+    }
+    newline();
+    console.log(info('Template (first 500 chars):'));
+    console.log(template.slice(0, 500) + (template.length > 500 ? '\n…(truncated)' : ''));
+    newline();
+}
+function editNarrator() {
+    const { wrote, path } = writeDefaultTemplate(false);
+    if (wrote) {
+        console.log(success('Wrote default template to:'), path);
+    }
+    else {
+        console.log(info('Existing template at:'), path);
+    }
+    const editor = process.env.EDITOR || process.env.VISUAL;
+    if (!editor) {
+        console.log(info('No $EDITOR set. Open this file in your editor of choice:'));
+        console.log('  ', path);
+        console.log(info('Then verify with:'), 'codehere narrator show');
+        return;
+    }
+    console.log(info('Opening in $EDITOR:'), editor);
+    // Fire the editor synchronously, inheriting tty so the user can edit.
+    const result = spawnSync(editor, [path], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        console.error(error('Editor exited non-zero.'), 'Edits (if any) still saved.');
+    }
+    // Reload + report — gives the user immediate confirmation their edits parsed.
+    const after = loadTemplate();
+    if (after.source === 'user') {
+        console.log(success('Active template:'), 'user-edited file (parses, all placeholders present).');
+    }
+    else {
+        console.log(error('Template missing required placeholders.'), 'Falling back to default until fixed.');
+        console.log(info('Required:'), '{{prompt}}, {{agent}}, {{elapsed_seconds}}, {{steps}}');
+    }
+}
+function resetNarrator() {
+    const { removed, path } = resetTemplate();
+    if (removed) {
+        console.log(success('Removed user-edited template.'), 'Narrator now uses the baked-in default.');
+        console.log(info('File was at:'), path);
+    }
+    else {
+        console.log(info('No user-edited template to remove.'), 'Already on the baked-in default.');
+    }
+    // Don't load DEFAULT_TEMPLATE for any side effect — just acknowledge it's the
+    // active source now. (Imported above so future test shape stays available.)
+    void DEFAULT_TEMPLATE;
+}
+//# sourceMappingURL=narrator-command.js.map

package/dist/presentation/cli/commands/permission-command.js

@@ -0,0 +1,116 @@
+/**
+ * `codehere permission` — manage per-cwd .codehere/permissions.yaml.
+ *
+ * Subcommands:
+ *   list                          — show current allow/deny entries
+ *   allow <pattern> [--reason X]  — append an allow entry
+ *   deny  <pattern> [--reason X]  — append a deny entry (reserved; no-op today)
+ *   remove <pattern>              — drop the matching entry from both buckets
+ *
+ * Always operates on the CURRENT working directory's
+ * .codehere/permissions.yaml. Creates the file if missing. Writes are
+ * idempotent — re-running `allow X` won't add a duplicate.
+ *
+ * Per claim_user_persona HIGH: the CLI is the developer escape hatch;
+ * the slice-2 web-UI panel (forthcoming) wraps the same primitive for
+ * non-technical users. The YAML format is the source of truth either way.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { loadPermissions, addPermissionEntry, removePermissionEntry, } from '../../../infrastructure/security/permissions-config.js';
+import { colors, success, error, warning, info, newline } from '../../../ui.js';
+export async function executePermissionCommand(subcommand, pattern, options = {}) {
+    const sub = subcommand ?? 'list';
+    switch (sub) {
+        case 'list':
+            return listPermissions();
+        case 'allow':
+            if (!pattern) {
+                console.error(error('Usage:'), 'codehere permission allow <pattern> [--reason "..."]');
+                process.exit(1);
+            }
+            return addEntry('allow', pattern, options.reason);
+        case 'deny':
+            if (!pattern) {
+                console.error(error('Usage:'), 'codehere permission deny <pattern> [--reason "..."]');
+                process.exit(1);
+            }
+            return addEntry('deny', pattern, options.reason);
+        case 'remove':
+            if (!pattern) {
+                console.error(error('Usage:'), 'codehere permission remove <pattern>');
+                process.exit(1);
+            }
+            return removeEntry(pattern);
+        default:
+            console.error(error('Unknown subcommand:'), sub);
+            console.error(info('Available:'), 'list · allow · deny · remove');
+            process.exit(1);
+    }
+}
+function permissionsPath() {
+    return join(process.cwd(), '.codehere', 'permissions.yaml');
+}
+function listPermissions() {
+    const cfg = loadPermissions(process.cwd());
+    if (cfg.allow.length === 0 && cfg.deny.length === 0) {
+        console.log(colors.dim('  (no permissions.yaml in this folder yet)'));
+        console.log(colors.dim('  Run `codehere permission allow <pattern> --reason "..."` to add an entry.'));
+        newline();
+        return;
+    }
+    if (cfg.allow.length > 0) {
+        console.log(success('allow:'));
+        for (const e of cfg.allow) {
+            console.log(`  • ${e.pattern}`);
+            if (e.reason)
+                console.log(colors.dim(`      reason: ${e.reason}`));
+            if (e.addedAt)
+                console.log(colors.dim(`      added:  ${e.addedAt}`));
+        }
+    }
+    if (cfg.deny.length > 0) {
+        console.log(warning('deny (reserved — currently no-op):'));
+        for (const e of cfg.deny) {
+            console.log(`  • ${e.pattern}`);
+            if (e.reason)
+                console.log(colors.dim(`      reason: ${e.reason}`));
+        }
+    }
+    newline();
+}
+function addEntry(bucket, pattern, reason) {
+    const result = addPermissionEntry({ cwd: process.cwd(), pattern, bucket, reason });
+    if (result.status === 'already_present') {
+        console.log(warning(`Pattern already in ${bucket}-list:`), pattern);
+        if (result.entry.reason)
+            console.log(colors.dim(`  reason: ${result.entry.reason}`));
+        if (reason && reason !== result.entry.reason) {
+            console.log(colors.dim('  (use `codehere permission remove <pattern>` first to change the reason)'));
+        }
+        newline();
+        return;
+    }
+    console.log(success(`Added to ${bucket}-list:`), pattern);
+    if (reason)
+        console.log(colors.dim(`  reason: ${reason}`));
+    console.log(colors.dim(`  file:   ${result.filePath}`));
+    newline();
+}
+function removeEntry(pattern) {
+    const { removed } = removePermissionEntry(process.cwd(), pattern);
+    if (removed === 0) {
+        console.log(warning('No entry found for pattern:'), pattern);
+        newline();
+        return;
+    }
+    console.log(success(`Removed ${removed} entr${removed === 1 ? 'y' : 'ies'} for:`), pattern);
+    newline();
+}
+// Ensure file is read on disk after writes (smoke test in unit tests)
+export function _readRaw() {
+    if (!existsSync(permissionsPath()))
+        return '';
+    return readFileSync(permissionsPath(), 'utf-8');
+}
+//# sourceMappingURL=permission-command.js.map

package/dist/presentation/cli/commands/scan-tool-command.js

@@ -7,10 +7,16 @@
  * This is the actual binary that Claude Code's hook system invokes.
  * It must be fast (<100ms) and never crash — any failure falls through to allow.
  *
+ * Trust-override audit (added 2026-05-06 per CC frontier Q1 — auditable
+ * permission trails): every fail-open path now writes an `overrideReason`
+ * audit entry so the audit log captures EVERY tool call, not just the ones
+ * the scanner could evaluate. Reviewers can `codehere audit --override-only`
+ * to see all cases where the safety policy didn't run normally.
+ *
  * Usage (by hook system, not user):
  *   echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | codehere scan-tool
  */
-import { processHookEvent } from '../../../infrastructure/hooks/claude-sdk-hook.js';
+import { processHookEvent, appendOverrideAudit, } from '../../../infrastructure/hooks/claude-sdk-hook.js';
 export async function executeScanToolCommand(options) {
     // Read all stdin
     let raw = '';
@@ -20,7 +26,9 @@ export async function executeScanToolCommand(options) {
         }
     }
     catch {
-        // If stdin read fails, allow the tool call
+        // If stdin read fails, allow the tool call — but log the override so
+        // the audit trail records that the scanner didn't get a chance to run.
+        appendOverrideAudit('stdin_read_failure');
         process.exit(0);
     }
     if (!raw.trim()) {
@@ -32,7 +40,12 @@ export async function executeScanToolCommand(options) {
         event = JSON.parse(raw);
     }
     catch {
-        // Malformed JSON — allow by default (fail open for dev experience)
+        // Malformed JSON — allow by default (fail open for dev experience).
+        // We still record the override with a truncated copy of the raw payload
+        // so reviewers can see what arrived (helps diagnose hook misconfiguration).
+        appendOverrideAudit('event_parse_failure', {
+            toolInput: raw.substring(0, 500),
+        });
         if (options.debug) {
             process.stderr.write('[codehere] Warning: could not parse hook event JSON\n');
         }
@@ -41,9 +54,18 @@ export async function executeScanToolCommand(options) {
     try {
         const decision = processHookEvent(event);
         if (options.logOnly) {
-            // Log-only mode: never block, but log everything
-            if (options.debug && decision) {
-                process.stderr.write(`[codehere] Would block: ${decision.reason}\n`);
+            // Log-only mode: never block, but log everything. If the scanner WOULD
+            // have blocked, record the override so the audit shows scanner intent
+            // vs actual outcome. Without this, --log-only mode produces an audit
+            // trail indistinguishable from a clean session.
+            if (decision?.decision === 'block') {
+                appendOverrideAudit('log_only_mode', {
+                    sessionId: event.session_id,
+                    toolName: event.tool_name,
+                });
+                if (options.debug) {
+                    process.stderr.write(`[codehere] Would block: ${decision.reason}\n`);
+                }
             }
             process.exit(0);
         }
@@ -58,7 +80,14 @@ export async function executeScanToolCommand(options) {
         process.exit(0);
     }
     catch {
-        // Any scan failure: fail open (allow), never break developer workflow
+        // Any scan failure: fail open (allow), never break developer workflow.
+        // Record the override so the audit trail shows the scanner crashed for
+        // this tool call — reviewers can correlate with the timestamp to find
+        // the underlying error.
+        appendOverrideAudit('scan_exception', {
+            sessionId: event.session_id,
+            toolName: event.tool_name,
+        });
         process.exit(0);
     }
 }

package/dist/utils/typo-guard.js

@@ -8,8 +8,16 @@
  *
  * Earlier rc.15 attempt (greedy edit-check + prefix match) over-matched and
  * blocked legitimate single-word prompts like "task-runner" or "h". Codex
- * caught the regression in review. This rc.16 version uses real Levenshtein,
+ * caught the regression in review. The rc.16 version uses real Levenshtein,
  * a length floor, and explicit kebab-case exemption.
+ *
+ * v0.6 extension: handle multi-token input. Original guard bailed on any
+ * whitespace, which let `setupp foo bar` and `daemon start` silently route to
+ * the task spawner. Now: checkTypo tokenizes and runs typo-detection on the
+ * first token. looksLikeUnknownCommand catches the narrow `cmd subcmd` shape
+ * (two short alphabetic tokens, first not a known command, not a typo) so
+ * cases like `daemon start` get an "unknown command" message instead of
+ * silently spawning an LLM task.
  */
 /** Standard Levenshtein distance. Bounded inputs only — no allocation guard. */
 export function levenshtein(a, b) {
@@ -34,25 +42,15 @@ export function levenshtein(a, b) {
     return dp[n];
 }
 /**
- * Decide whether a bare-action input should be treated as a typo of a known
- * subcommand. Returns the suggestions if it should block; null if it should
- * fall through to the task spawner.
- *
- * Heuristics (intentionally narrow — false positives are worse than false negatives):
- *   - Single token (no whitespace), 4–14 chars (excludes "h", "go", etc.)
- *   - Pure alphabetic, no hyphens (kebab-case is a likely real prompt)
- *   - True Levenshtein distance ≤ 2 to a known command
- *   - Distance must be < input length (avoid 2-char words matching anything)
- *   - Returns up to 3 closest commands ranked by ascending distance
+ * Internal: typo-check a single token against known commands.
+ * Returns up to 3 closest matches (Lev ≤ 2, distance < input length) or null.
  */
-export function checkTypo(input, knownCommands) {
-    if (/\s/.test(input))
+function checkTypoSingle(token, knownCommands) {
+    if (token.length < 4 || token.length > 14)
         return null;
-    if (input.length < 4 || input.length > 14)
+    if (!/^[a-z]+$/i.test(token))
         return null;
-    if (!/^[a-z]+$/i.test(input))
-        return null;
-    const lower = input.toLowerCase();
+    const lower = token.toLowerCase();
     // Defensively normalize knownCommands to lowercase too — Codex rc.16 review
     // flagged this for symmetry. Currently every Commander subcommand is lower
     // already, but a future addition that registers an uppercase name shouldn't
@@ -70,4 +68,66 @@ export function checkTypo(input, knownCommands) {
         .slice(0, 3);
     return scored.length > 0 ? scored.map((s) => s.n) : null;
 }
+/**
+ * Decide whether a bare-action input contains a typo of a known subcommand.
+ * Returns suggestions if the FIRST token looks like a typo; null otherwise.
+ *
+ * Multi-token inputs (e.g. `setupp foo bar`) tokenize on whitespace and only
+ * the first token is typo-checked — the rest are treated as positional args
+ * the user meant to pass to the suggested command.
+ *
+ * Heuristics (intentionally narrow — false positives are worse than false negatives):
+ *   - First token is 4–14 chars, pure alphabetic, no hyphens (kebab-case is a likely real prompt)
+ *   - True Levenshtein distance ≤ 2 to a known command
+ *   - Distance must be < input length (avoid 2-char words matching anything)
+ *   - Returns up to 3 closest commands ranked by ascending distance
+ */
+export function checkTypo(input, knownCommands) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    const first = trimmed.split(/\s+/)[0];
+    return checkTypoSingle(first, knownCommands);
+}
+/**
+ * Detect inputs shaped like a typed-but-unknown subcommand invocation:
+ * exactly two short alphabetic tokens, first token NOT a known command and NOT
+ * a near-typo of one. Returns the unknown first token (for error formatting)
+ * or null if input doesn't match the shape.
+ *
+ * Catches cases the typo guard misses — e.g. `daemon start`, `webui open`,
+ * `nuke session` — where the first word isn't close enough to a real command
+ * for Levenshtein suggestions but is clearly a command attempt rather than a
+ * natural-language prompt.
+ *
+ * Conservative on purpose:
+ *   - Exactly 2 tokens (3+ tokens are usually prompts: "fix the login bug")
+ *   - Both tokens pure alphabetic (a slash/period in token 2 → file path → prompt)
+ *   - First token 4-14 chars (skip "go run", "h x"); second 2-14 chars
+ *   - First not a known command and not a typo (those branches handled elsewhere)
+ */
+export function looksLikeUnknownCommand(input, knownCommands) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    if (tokens.length !== 2)
+        return null;
+    const [first, second] = tokens;
+    if (first.length < 4 || first.length > 14)
+        return null;
+    if (second.length < 2 || second.length > 14)
+        return null;
+    if (!/^[a-z]+$/i.test(first))
+        return null;
+    if (!/^[a-z]+$/i.test(second))
+        return null;
+    const lower = first.toLowerCase();
+    const knownLower = knownCommands.map((n) => n.toLowerCase());
+    if (knownLower.includes(lower))
+        return null;
+    if (checkTypoSingle(first, knownCommands))
+        return null;
+    return first;
+}
 //# sourceMappingURL=typo-guard.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "0.5.0-alpha.6",
+  "version": "0.6.0-alpha.1",
   "description": "A PM for your AI coding agents. Delegate, orchestrate, and audit Claude Code, Codex, Aider, OpenCode, Gemini, and any user-configured CLI agent from one local web UI — every AI action traced, every file scored, every spawn warmed with project memory.",
   "main": "dist/index.js",
   "type": "module",