codehere 0.6.2 → 0.7.0

package/dist/presentation/cli/repl.js

@@ -119,6 +119,38 @@ const SLASH_COMMANDS = [
         noKey: true,
         subcommand: 'status',
     },
+    {
+        name: 'verify',
+        args: '[session-id]',
+        description: "Verify a session's Final Report against recorded reality",
+        kind: 'sub',
+        noKey: true,
+        subcommand: 'verify',
+    },
+    {
+        name: 'audit',
+        args: '[verify|show]',
+        description: 'Inspect the hash-chained audit log',
+        kind: 'sub',
+        noKey: true,
+        subcommand: 'audit',
+    },
+    {
+        name: 'context-source',
+        args: '[list|connect|disconnect]',
+        description: 'Connect Linear/Figma via OAuth',
+        kind: 'sub',
+        noKey: true,
+        subcommand: 'context-source',
+    },
+    {
+        name: 'thread',
+        args: '<sub> [arg]',
+        description: 'Share or import a signed session bundle',
+        kind: 'sub',
+        noKey: true,
+        subcommand: 'thread',
+    },
     { name: 'health', args: '', description: 'System health check', kind: 'sub', noKey: true, subcommand: 'health' },
     {
         name: 'setup',
@@ -278,7 +310,6 @@ export async function runInteractiveRepl() {
     let escTimer = null;
     const cols = () => stdout.columns || 80;
     function truncate(s, maxWidth) {
-        // eslint-disable-next-line no-control-regex -- ANSI escape stripping requires the literal ESC byte
         const visible = s.replace(/\x1b\[[0-9;]*m/g, '');
         if (visible.length <= maxWidth)
             return s;

package/dist/presentation/cli/task-deliverable.js

@@ -0,0 +1,127 @@
+/**
+ * Task deliverable · the CLI counterpart to the web UI session card.
+ *
+ * After a task finishes, the non-technical user needs the SAME thing they get
+ * in the dashboard, just in the terminal: what the agent did (Final Report),
+ * which files changed + the trust score, whether the report's claims check out
+ * (verifier), and one obvious next step. No raw event types, no jargon.
+ *
+ * Shared by `task --watch` (print on completion) and the daemon-fetch path so
+ * both surfaces say the same honest thing. Per feedback_no_screen_lies: every
+ * line here traces to recorded state — we never print a success we can't prove.
+ */
+import http from 'http';
+import { colors } from '../../ui.js';
+/** Pull one session's full result from a running daemon's /api/tasks. Matches
+ *  by exact id or short prefix. Returns null if the daemon is unreachable or
+ *  the id isn't found. */
+export function fetchSessionResult(base, sessionId) {
+    return new Promise((resolve) => {
+        const r = http.get(`${base}/api/tasks`, (res) => {
+            let buf = '';
+            res.on('data', (c) => {
+                buf += c.toString();
+            });
+            res.on('end', () => {
+                try {
+                    const j = JSON.parse(buf);
+                    const all = [...(j.spawned ?? []), ...(j.persisted ?? [])];
+                    const exact = all.find((s) => s.sessionId === sessionId);
+                    resolve(exact ?? all.find((s) => s.sessionId.startsWith(sessionId)) ?? null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        r.on('error', () => resolve(null));
+    });
+}
+/** Poll the daemon until the Final Report lands (or we give up). The report is
+ *  generated asynchronously after the agent exits, so a single fetch right at
+ *  'exit' often misses it. */
+export async function waitForDeliverable(base, sessionId, opts = {}) {
+    // Real agents take ~30-60s to synthesize the Final Report after the agent
+    // exits (mock is instant). 90s covers a real claude run without giving up early.
+    const timeoutMs = opts.timeoutMs ?? 90_000;
+    const intervalMs = opts.intervalMs ?? 500;
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    while (Date.now() < deadline) {
+        last = await fetchSessionResult(base, sessionId);
+        if (last && (last.finalReport || last.failedReport || last.status === 'error' || last.status === 'killed')) {
+            return last;
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return last;
+}
+/** Plain-English deliverable block. The terminal twin of the dashboard card. */
+export function formatDeliverable(r) {
+    const lines = [];
+    const bar = colors.dim('─'.repeat(60));
+    const verb = r.status === 'completed'
+        ? 'Done'
+        : r.status === 'error'
+            ? 'Failed'
+            : r.status === 'killed'
+                ? 'Stopped'
+                : 'Finished';
+    lines.push('');
+    lines.push(bar);
+    lines.push(`${colors.bold(verb)} · ${r.agent} · ${colors.dim(r.sessionId.slice(0, 8))}`);
+    lines.push(bar);
+    if (r.stalledReason) {
+        lines.push(colors.warning(`The agent stalled: ${r.stalledReason}`));
+    }
+    // 1 · What the agent did (the Final Report narrative).
+    if (r.finalReport?.summary) {
+        lines.push(r.finalReport.summary.trim());
+    }
+    else if (r.failedReport) {
+        lines.push(colors.dim("codehere couldn't write a report for this run."));
+    }
+    else if (r.status === 'error') {
+        lines.push(colors.dim('The agent ran into an error before finishing.'));
+    }
+    else {
+        lines.push(colors.dim('No report yet.'));
+    }
+    // 2 · Files changed + trust score (or the honest can't-track note).
+    const files = r.artifacts?.files ?? [];
+    if (r.artifacts?.noGitTracking) {
+        lines.push('');
+        lines.push(colors.dim("Files: codehere couldn't track changes here (this folder isn't a git repository)."));
+    }
+    else if (files.length > 0) {
+        lines.push('');
+        lines.push(colors.bold('Files changed:'));
+        for (const f of files) {
+            const trust = typeof f.trust === 'number' ? ` · trust ${f.trust}/100` : '';
+            lines.push(`  • ${f.path}  ${colors.success('+' + f.added)}/${colors.error('-' + f.removed)}${colors.dim(trust)}`);
+        }
+    }
+    else {
+        lines.push('');
+        lines.push(colors.dim('Files: none changed.'));
+    }
+    // 3 · Did the report's claims check out? (verifier cross-check)
+    if (r.verifyResult) {
+        const v = r.verifyResult;
+        const label = v.status === 'verified'
+            ? colors.success('verified')
+            : v.status === 'broken'
+                ? colors.error('does not match reality')
+                : v.status === 'partial'
+                    ? colors.warning('partly unverifiable')
+                    : colors.dim('nothing to check');
+        lines.push('');
+        lines.push(`${colors.bold('Check:')} ${label} — ${v.summary}`);
+        for (const f of v.findings.filter((x) => x.severity !== 'info')) {
+            lines.push(colors.dim(`    • ${f.message}`));
+        }
+    }
+    lines.push(bar);
+    return lines.join('\n');
+}
+//# sourceMappingURL=task-deliverable.js.map

package/dist/testing/cassette.js

@@ -0,0 +1,125 @@
+/**
+ * Cassette schema (LOCKED — do not modify; see docs/TEST_PLAN_v0.7.md §3.L3b).
+ *
+ * JSONL at `agent/test/cassettes/<adapter>/<scenario>-YYYY-MM-DD.jsonl`. One line per chunk.
+ *
+ *   Line 1 (header):
+ *     {"t":0,"meta":{"adapter":"<id>","scenario":"<id>","captured_at":"<ISO>","binary_version":"<x.y.z|synthetic>","origin":"real"|"synthetic","prompt":"<original>","cwd_hint":"<relpath>","schema":1}}
+ *   Line 2..N (events):
+ *     {"t":<ms-from-start>,"stream":"stdout"|"stderr","data":"<raw bytes, newlines preserved>"}
+ *   Line N+1 (term):
+ *     {"t":<ms-from-start>,"exit_code":<int>,"signal":<string|null>}
+ *
+ * Loaders validate shape and reject malformed cassettes loudly — a silently-
+ * misparsed cassette would produce a false-green test, defeating L3b's point.
+ */
+import { readFileSync } from 'fs';
+function isObject(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function parseLine(line, lineNo, path) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cassette ${path} line ${lineNo}: invalid JSON (${msg})`, { cause: err });
+    }
+}
+/** Read a JSONL cassette from disk, validate shape, return structured form. */
+export function loadCassette(path) {
+    const raw = readFileSync(path, 'utf-8');
+    const rawLines = raw.split('\n');
+    const lines = [];
+    for (let i = 0; i < rawLines.length; i++) {
+        const line = rawLines[i].trim();
+        if (line)
+            lines.push({ line, no: i + 1 });
+    }
+    if (lines.length < 2) {
+        throw new Error(`Cassette ${path}: needs at least header + terminal lines (got ${lines.length})`);
+    }
+    // Header
+    const headerRaw = parseLine(lines[0].line, lines[0].no, path);
+    if (!isObject(headerRaw) || headerRaw.t !== 0 || !isObject(headerRaw.meta)) {
+        throw new Error(`Cassette ${path} line ${lines[0].no}: header must be {"t":0,"meta":{...}}`);
+    }
+    const meta = headerRaw.meta;
+    const requiredMeta = [
+        'adapter',
+        'scenario',
+        'captured_at',
+        'binary_version',
+        'origin',
+        'prompt',
+        'cwd_hint',
+        'schema',
+    ];
+    for (const k of requiredMeta) {
+        if (!(k in meta)) {
+            throw new Error(`Cassette ${path}: header meta missing required field "${k}"`);
+        }
+    }
+    if (meta.schema !== 1) {
+        throw new Error(`Cassette ${path}: schema must be 1, got ${String(meta.schema)}`);
+    }
+    if (meta.origin !== 'real' && meta.origin !== 'synthetic') {
+        throw new Error(`Cassette ${path}: meta.origin must be "real" or "synthetic"`);
+    }
+    // Terminal (last line)
+    const termEntry = lines[lines.length - 1];
+    const termRaw = parseLine(termEntry.line, termEntry.no, path);
+    if (!isObject(termRaw) || typeof termRaw.t !== 'number' || !('exit_code' in termRaw) || !('signal' in termRaw)) {
+        throw new Error(`Cassette ${path} line ${termEntry.no}: terminal must be {"t":...,"exit_code":...,"signal":...}`);
+    }
+    if (typeof termRaw.exit_code !== 'number') {
+        throw new Error(`Cassette ${path} line ${termEntry.no}: terminal.exit_code must be a number`);
+    }
+    if (termRaw.signal !== null && typeof termRaw.signal !== 'string') {
+        throw new Error(`Cassette ${path} line ${termEntry.no}: terminal.signal must be string or null`);
+    }
+    // Middle: events
+    const events = [];
+    for (let i = 1; i < lines.length - 1; i++) {
+        const { line, no } = lines[i];
+        const ev = parseLine(line, no, path);
+        if (!isObject(ev) || typeof ev.t !== 'number') {
+            throw new Error(`Cassette ${path} line ${no}: event must have numeric "t"`);
+        }
+        if (ev.stream !== 'stdout' && ev.stream !== 'stderr') {
+            throw new Error(`Cassette ${path} line ${no}: event.stream must be "stdout" or "stderr"`);
+        }
+        if (typeof ev.data !== 'string') {
+            throw new Error(`Cassette ${path} line ${no}: event.data must be a string`);
+        }
+        events.push({ t: ev.t, stream: ev.stream, data: ev.data });
+    }
+    const cassette = {
+        header: { t: 0, meta: meta },
+        events,
+        terminal: {
+            t: termRaw.t,
+            exit_code: termRaw.exit_code,
+            signal: termRaw.signal,
+        },
+    };
+    validateCassette(cassette);
+    return cassette;
+}
+/** Sanity-check ordering invariants. Throws on violation. */
+export function validateCassette(c) {
+    if (c.header.t !== 0)
+        throw new Error('Cassette: header.t must be 0');
+    let prev = 0;
+    for (let i = 0; i < c.events.length; i++) {
+        const t = c.events[i].t;
+        if (t < prev) {
+            throw new Error(`Cassette: events out of order at index ${i} (t=${t} < prev=${prev})`);
+        }
+        prev = t;
+    }
+    if (c.terminal.t < prev) {
+        throw new Error(`Cassette: terminal.t (${c.terminal.t}) must be >= last event.t (${prev})`);
+    }
+}
+//# sourceMappingURL=cassette.js.map

package/dist/testing/replay-adapter.js

@@ -0,0 +1,166 @@
+/**
+ * L3b cassette byte-replay shim — see docs/TEST_PLAN_v0.7.md §3.L3b.
+ *
+ * This module swaps `child_process.spawn` so a real adapter's stdout/stderr/
+ * exit handlers receive bytes from a cassette instead of a live subprocess.
+ * The adapter under test is the production code path — only its boundary with
+ * the OS process layer is substituted. That keeps L3b honest about the parser
+ * + state-machine behavior the adapter exhibits on real captured bytes.
+ *
+ * Why a module-level "active cassette" instead of dependency injection:
+ * `vi.mock('child_process', factory)` hoists to module load and runs once.
+ * The factory has no way to receive a per-test cassette argument. The factory
+ * therefore reads `getActiveCassette()` lazily at every `spawn()` call. Tests
+ * call `setActiveCassette(loadCassette(path))` in `beforeEach`, then call
+ * `SessionManager.getInstance().spawn(...)` to drive the adapter.
+ *
+ * Honest call-out: this approach mocks the entire `child_process` import in
+ * the test file. The same factory wraps `execFileSync` so adapter `which X`
+ * probes succeed even when the binary is absent on the test host. Anything
+ * else (git, ps) passes through to the real implementation.
+ *
+ * The synthetic `ChildProcess` honors what the per-adapter spawn boundary
+ * actually touches per `/tmp/l3b-spawn-boundary-map.json`:
+ *   - `stdout` / `stderr` Readable that emit `data` events at the cassette `t`s
+ *   - `stdin` writable that swallows writes (codex's prompt write is recorded
+ *     by the capture-cassette script on the spawn side; stdin replay deferred)
+ *   - `exit` then `close` at the terminal `t`
+ *   - `kill(signal)` cancels pending timers and emits exit with that signal
+ *   - `pid` set to a fake non-zero integer
+ *   - `unref()` / `ref()` no-ops (gemini detached path)
+ */
+import { EventEmitter } from 'events';
+import { Readable, Writable } from 'stream';
+import { loadCassette } from './cassette.js';
+// ── Active cassette holder (single-cassette-per-test pattern) ───────────────
+let _activeCassette;
+export function setActiveCassette(c) {
+    _activeCassette = c;
+}
+export function getActiveCassette() {
+    return _activeCassette;
+}
+let _fakePidCounter = 1_000_000;
+/** Drop-in replacement for `child_process.spawn`. Plays the cassette through
+ *  a synthetic ChildProcess; ignores cmd/args/options because the cassette
+ *  describes the stream end-to-end. */
+export function createReplaySpawn(cassette) {
+    const replaySpawn = ((_cmd, _args, _opts) => {
+        return makeReplayChild(cassette);
+    });
+    return replaySpawn;
+}
+function makeReplayChild(cassette) {
+    const child = new EventEmitter();
+    const timers = [];
+    let killed = false;
+    // Readable streams. We push() bytes manually as timers fire; no _read backpressure
+    // because the adapter parsers consume eagerly via 'data' events.
+    const stdout = new Readable({ read() { } });
+    const stderr = new Readable({ read() { } });
+    const stdin = new Writable({
+        write(_chunk, _enc, cb) {
+            cb();
+        },
+        final(cb) {
+            cb();
+        },
+    });
+    Object.defineProperty(child, 'stdout', { value: stdout, configurable: true });
+    Object.defineProperty(child, 'stderr', { value: stderr, configurable: true });
+    Object.defineProperty(child, 'stdin', { value: stdin, configurable: true });
+    Object.defineProperty(child, 'pid', { value: ++_fakePidCounter, configurable: true });
+    Object.defineProperty(child, 'killed', {
+        get: () => killed,
+        configurable: true,
+    });
+    // child_process API surface adapters touch (per /tmp/l3b-spawn-boundary-map.json).
+    child.kill = ((signal) => {
+        if (killed)
+            return false;
+        killed = true;
+        for (const t of timers)
+            clearTimeout(t);
+        timers.length = 0;
+        const sig = typeof signal === 'string' ? signal : 'SIGTERM';
+        queueMicrotask(() => {
+            try {
+                stdout.push(null);
+            }
+            catch {
+                /* readable already ended */
+            }
+            try {
+                stderr.push(null);
+            }
+            catch {
+                /* readable already ended */
+            }
+            child.emit('exit', null, sig);
+            child.emit('close', null, sig);
+        });
+        return true;
+    });
+    child.unref = (() => child);
+    child.ref = (() => child);
+    child.disconnect = (() => {
+        /* noop for replay */
+    });
+    // Schedule cassette events. setTimeout is fine for replay — Vitest doesn't
+    // need fake timers; the test waits on the session reaching an exited status.
+    for (const ev of cassette.events) {
+        const handle = setTimeout(() => {
+            if (killed)
+                return;
+            const stream = ev.stream === 'stdout' ? stdout : stderr;
+            try {
+                stream.push(Buffer.from(ev.data, 'utf-8'));
+            }
+            catch {
+                /* stream ended early — ignore */
+            }
+        }, ev.t);
+        timers.push(handle);
+    }
+    // Terminal.
+    const termHandle = setTimeout(() => {
+        if (killed)
+            return;
+        try {
+            stdout.push(null);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            stderr.push(null);
+        }
+        catch {
+            /* ignore */
+        }
+        const code = cassette.terminal.signal ? null : cassette.terminal.exit_code;
+        child.emit('exit', code, cassette.terminal.signal);
+        child.emit('close', code, cassette.terminal.signal);
+    }, cassette.terminal.t);
+    timers.push(termHandle);
+    return child;
+}
+/** Test convenience: load cassette, set it active, spawn via SessionManager.
+ *
+ *  Callers MUST install `vi.mock('child_process', factory)` at the top of
+ *  their test file with a factory that delegates `spawn` to
+ *  `createReplaySpawn(getActiveCassette())`. See cassette-replay.test.ts
+ *  for the canonical setup.
+ *
+ *  Returns the spawned TaskSession (typed loosely to avoid pulling the
+ *  whole adapter type tree into src/testing/).
+ */
+export async function replayThroughAdapter(cassettePath, sessionManager) {
+    const cassette = loadCassette(cassettePath);
+    setActiveCassette(cassette);
+    const session = sessionManager.spawn(cassette.header.meta.prompt, cassette.header.meta.adapter, {
+        cwd: cassette.header.meta.cwd_hint,
+    });
+    return session;
+}
+//# sourceMappingURL=replay-adapter.js.map

package/dist/ui.js

@@ -285,7 +285,10 @@ import { getVersionWithPrefix } from './utils/version.js';
 export function createWelcomeMessage() {
     const logo = createCodehereLogo();
     const version = getVersionWithPrefix();
-    const tagline = 'AI coding agent with built-in safety';
+    // Matches the positioning in `codehere --help` and `codehere help`. codehere
+    // is the LAYER over your coding agents, not itself an agent — the old
+    // "AI coding agent with built-in safety" line implied the opposite.
+    const tagline = 'A PM for your AI coding agents';
     return `
 ${colors.bold(logo)} ${colors.dim(version)}
 ${colors.dim(tagline)}
@@ -422,6 +425,20 @@ export const SLASH_COMMANDS = [
     { name: 'trust', args: '[path]', description: 'Scan for vulnerabilities', noKey: true },
     { name: 'report', args: '[path]', description: 'Shareable security audit', noKey: true },
     { name: 'status', args: '', description: 'Security dashboard — hook activity', noKey: true },
+    {
+        name: 'verify',
+        args: '[session-id]',
+        description: "Verify a session's Final Report against recorded reality",
+        noKey: true,
+    },
+    { name: 'audit', args: '[verify|show]', description: 'Inspect the hash-chained audit log', noKey: true },
+    {
+        name: 'context-source',
+        args: '[list|connect|disconnect]',
+        description: 'Connect Linear/Figma via OAuth',
+        noKey: true,
+    },
+    { name: 'thread', args: '<sub> [arg]', description: 'Share or import a signed session bundle', noKey: true },
     { name: 'health', args: '', description: 'System health + metrics', noKey: true },
     // Orchestration
     { name: 'start', args: '', description: 'Open the dashboard at localhost:3773' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "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",
@@ -31,7 +31,8 @@
     "format": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
     "format:check": "prettier --check 'src/**/*.ts' 'test/**/*.ts'",
     "sbom": "npm sbom --sbom-format=spdx --omit=dev",
-    "pretag:check": "../scripts/pretag-npm-check.sh"
+    "pretag:check": "../scripts/pretag-npm-check.sh",
+    "cassette:record": "../scripts/capture-cassette.sh"
   },
   "keywords": [
     "ai-coding-agents",
@@ -76,6 +77,7 @@
     "@types/cli-progress": "^3.11.5",
     "@types/node": "^20.19.25",
     "eslint": "^10.2.0",
+    "playwright": "^1.60.0",
     "prettier": "^3.8.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",