codehere 0.6.1 → 0.7.0

package/README.md

@@ -5,12 +5,14 @@
 
 [![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-1196%2F1196-brightgreen)]()
-[![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
+[![Internal tests](https://img.shields.io/badge/internal_tests-1200%2F1200-brightgreen)]()
+[![Honest status](https://img.shields.io/badge/v0.7--honest--reframe-2026--05--19-blue)](../docs/TRUTHFUL_STATE_2026-05-19.md)
 
 **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.
 
-All 5 adapters (Claude Code, Codex, Aider, Gemini, OpenCode) get session-tracing, Final Reports, and trust scoring. Claude Code additionally gets full pre-execution safety-hook enforcement on every tool call. The *memory*, *audit log*, *failover*, and *Final Report* surfaces ship across all 5 adapters today.
+All 5 adapters (Claude Code, Codex, Aider, Gemini, OpenCode) ship adapter code for session-tracing, Final Reports, and trust scoring. Claude Code additionally gets full pre-execution safety-hook enforcement on every tool call via the Claude Agent SDK. The *memory*, *audit log*, *failover*, and *Final Report* surfaces are wired across all 5 adapters today.
+
+> **Honest status (2026-05-19)** — The 1200 internal tests verify codehere's code against codehere's own assumptions about what each adapter emits. They do **not** systematically verify against real-adapter outputs in production. Real-adapter contract verification is the v0.7 release work — see [`docs/TRUTHFUL_STATE_2026-05-19.md`](../docs/TRUTHFUL_STATE_2026-05-19.md) for the verified / assumed / unverified classification of every surface.
 
 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**.
 

package/dist/application/use-cases/domain-trust.js

@@ -0,0 +1,110 @@
+/**
+ * Per-domain trust grade for W-PASS write targets · v0.9 must-ship.
+ *
+ * Demo v12 + locked v1 tier scope: "linear.app A · *.atlassian.net B ·
+ * unknown F · first-write confirmation per domain."
+ *
+ * Two pieces of state:
+ *   1. WELL_KNOWN_GRADES · hardcoded · the platforms we've vetted ourselves
+ *      ship with grade A. Subdomain wildcards get B. Everything else
+ *      defaults to F (forces explicit user confirmation on first write).
+ *   2. USER_TRUSTED_DOMAINS · ~/.codehere/keys/trusted-domains.json ·
+ *      domains the user has explicitly trusted after a first-write prompt.
+ *      Domains here promote from F → B.
+ *
+ * Pure logic. CLI + HTTP wrap it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+const WELL_KNOWN_GRADES = [
+    // Grade A · platforms codehere has shipped+tested adapters for
+    { pattern: /^api\.linear\.app$/i, grade: 'A', reason: 'official Linear API · codehere ships a vetted adapter' },
+    { pattern: /^api\.github\.com$/i, grade: 'A', reason: 'official GitHub API · codehere ships a vetted adapter' },
+    { pattern: /^api\.figma\.com$/i, grade: 'A', reason: 'official Figma API · codehere ships a vetted adapter' },
+    // Grade B · same vendor, surrounding subdomains
+    { pattern: /^[a-z0-9-]+\.linear\.app$/i, grade: 'B', reason: 'Linear subdomain · adjacent to the vetted API' },
+    { pattern: /^[a-z0-9-]+\.github\.com$/i, grade: 'B', reason: 'GitHub subdomain · adjacent to the vetted API' },
+    { pattern: /^[a-z0-9-]+\.figma\.com$/i, grade: 'B', reason: 'Figma subdomain · adjacent to the vetted API' },
+    {
+        pattern: /^[a-z0-9-]+\.atlassian\.net$/i,
+        grade: 'B',
+        reason: 'Atlassian-hosted instance · vendor known but instance not vetted',
+    },
+    // Grade C · public hosts known to be commonly used
+    { pattern: /^raw\.githubusercontent\.com$/i, grade: 'C', reason: 'GitHub-hosted raw content · static, read-mostly' },
+];
+function trustedDomainsPath() {
+    const home = process.env.CODEHERE_HOME || homedir();
+    return join(home, '.codehere', 'keys', 'trusted-domains.json');
+}
+export function loadTrustedDomains() {
+    const path = trustedDomainsPath();
+    if (!existsSync(path))
+        return { schema: 1, domains: {} };
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        if (raw && raw.schema === 1 && typeof raw.domains === 'object')
+            return raw;
+    }
+    catch {
+        /* fall through · empty trust store */
+    }
+    return { schema: 1, domains: {} };
+}
+export function trustDomain(host, note) {
+    const file = loadTrustedDomains();
+    file.domains[host.toLowerCase()] = { addedAt: Date.now(), note };
+    mkdirSync(dirname(trustedDomainsPath()), { recursive: true });
+    writeFileSync(trustedDomainsPath(), JSON.stringify(file, null, 2) + '\n', 'utf-8');
+}
+export function untrustDomain(host) {
+    const file = loadTrustedDomains();
+    const key = host.toLowerCase();
+    if (!file.domains[key])
+        return false;
+    delete file.domains[key];
+    writeFileSync(trustedDomainsPath(), JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    return true;
+}
+export function gradeDomain(host) {
+    const userFile = loadTrustedDomains();
+    const userTrusted = !!userFile.domains[host.toLowerCase()];
+    for (const rule of WELL_KNOWN_GRADES) {
+        if (rule.pattern.test(host)) {
+            return {
+                host,
+                grade: rule.grade,
+                reason: rule.reason,
+                userTrusted,
+                requiresFirstWriteConfirmation: false,
+            };
+        }
+    }
+    if (userTrusted) {
+        return {
+            host,
+            grade: 'B',
+            reason: 'previously trusted by you · stored in trusted-domains.json',
+            userTrusted: true,
+            requiresFirstWriteConfirmation: false,
+        };
+    }
+    return {
+        host,
+        grade: 'F',
+        reason: 'unknown domain · not in well-known list · not previously trusted',
+        userTrusted: false,
+        requiresFirstWriteConfirmation: true,
+    };
+}
+/** Extract the host from a fully-resolved HTTPS URL. */
+export function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=domain-trust.js.map

package/dist/application/use-cases/generate-final-report.js

@@ -24,6 +24,8 @@
  * Claude Squad, AI-Agents-Orchestrator) advertise.
  */
 import { spawn } from 'child_process';
+import { isMockMode } from '../../infrastructure/orchestration/mocks/resolve-agent-spawn.js';
+import { mockFinalReport } from '../../infrastructure/orchestration/mocks/mock-synthesis.js';
 const PROMPT_TEMPLATE = (i) => `You are a PM reporting back to a developer about what their AI coding agent
 just did. Write 3 short paragraphs in plain English. No headers, no bullet
 lists, no markdown — just three paragraphs separated by blank lines.
@@ -41,8 +43,12 @@ Paragraph 1: What the agent ATTEMPTED. Verb-led. Describe steps as listed.
              Mention specific filenames ONLY if they appear in the data
              below. 1-3 sentences.
 Paragraph 2: What was TOUCHED. Reference ONLY the "Files changed" list
-             below. If the list is empty, say "No files were changed."
-             1-2 sentences.
+             below. If the list is empty AND "File tracking" says git is
+             available, say "No files were changed." If "File tracking" says
+             git is NOT available, say codehere could not track file changes
+             because this folder is not a git repository — do NOT say no files
+             were changed, because the agent may well have changed files
+             codehere cannot see. 1-2 sentences.
 Paragraph 3: What the developer should LOOK AT. If steps + files data show
              nothing risky, say so explicitly ("nothing to verify; the
              session was read-only" or similar). 1-2 sentences.
@@ -59,9 +65,13 @@ Status: ${i.status}
 Steps the agent took:
 ${i.steps.length ? i.steps.map((s) => `- ${s.label} (${s.state})`).join('\n') : '(no structured steps captured)'}
 
+File tracking: ${i.artifacts?.noGitTracking ? 'git NOT available (this folder is not a git repository — file changes cannot be tracked)' : 'git available'}
+
 Files changed:
 ${i.artifacts?.files?.length
-    ? i.artifacts.files.map((f) => `- ${f.path} (+${f.added}/-${f.removed}${f.trust !== undefined ? `, trust: ${f.trust}` : ''})`).join('\n')
+    ? i.artifacts.files
+        .map((f) => `- ${f.path} (+${f.added}/-${f.removed}${f.trust !== undefined ? `, trust: ${f.trust}` : ''})`)
+        .join('\n')
     : '(no file artifacts captured)'}
 
 Token usage: ${i.artifacts?.usage?.inputTokens ?? 0} in / ${i.artifacts?.usage?.outputTokens ?? 0} out
@@ -75,16 +85,75 @@ function selectProviderBinary() {
         return [override];
     return ['claude-free', 'claude'];
 }
+/**
+ * UAT-003 — patterns that indicate the wrapped agent's session terminated
+ * because of a network / auth / quota failure rather than a real task.
+ * When we see these in the would-be summary text, we prepend a plain-English
+ * recovery hint instead of letting the raw provider error echo through.
+ *
+ * Pre-fix: bare `exit` in REPL → Conductor spawned claude-code → real API
+ * call failed with "All connection attempts failed Request ID: req_...";
+ * Final Report quoted that text verbatim. Per Core Values #4 + #6, this is
+ * unacceptable — the user sees a Request ID that means nothing.
+ */
+const NETWORK_FAILURE_PATTERNS = /(?:all connection attempts failed|ECONNREFUSED|ENOTFOUND|fetch failed|network error|request id:\s*req_|connection timed out|getaddrinfo)/i;
+function isLikelyNetworkFailureSummary(text) {
+    return NETWORK_FAILURE_PATTERNS.test(text);
+}
+function buildErrorRecoveryReport(input, durationMs) {
+    // Tailor the hint to the specific failure shape we can detect from input.
+    const agentName = input.agent === 'conductor' ? 'the agent codehere chose' : input.agent;
+    return {
+        summary: `The ${agentName} session ended without completing the task. ` +
+            `This usually means a network hiccup, an expired login, or a rate limit on the provider.\n\n` +
+            `What to try: check your internet, run \`codehere health\` to confirm reachability + auth, ` +
+            `or wait a minute and rerun the same prompt. If it keeps happening, try a different agent ` +
+            `from the dropdown — codehere is vendor-neutral on purpose.\n\n` +
+            `codehere couldn't confirm any file changes from this attempt.`,
+        generatedAt: Date.now(),
+        durationMs,
+    };
+}
 /**
  * Generate a Final Report. Returns null if no provider is reachable.
  * Never throws — failure modes return null + log a debug line.
+ *
+ * UAT-003 — when the input.status is 'error', we skip the LLM call entirely
+ * and return a deterministic recovery hint. Saves tokens on a known-failed
+ * task AND gives the user a plain-English next step instead of waiting for
+ * a possibly-unhelpful LLM summary.
  */
 export async function generateFinalReport(input) {
+    // CODEHERE_MOCK — synthesize a grounded report with zero API so the full
+    // demo flow (incl. this headline deliverable + the verify cross-check) runs
+    // under mock. Errors still get the deterministic recovery report below.
+    if (isMockMode() && input.status !== 'error') {
+        return mockFinalReport(input);
+    }
+    // Short-circuit on errored sessions — don't waste tokens summarizing nothing.
+    if (input.status === 'error') {
+        return buildErrorRecoveryReport(input, 0);
+    }
     const prompt = PROMPT_TEMPLATE(input);
     for (const binary of selectProviderBinary()) {
         const result = await tryProvider(binary, prompt, input.sessionId);
-        if (result)
+        if (result) {
+            // Defense-in-depth: even on 'completed' status, if the generated
+            // summary leaks a provider network-failure string (e.g., the wrapped
+            // agent exited 0 but its assistant text was an error message), wrap
+            // the summary with a recovery preamble.
+            if (isLikelyNetworkFailureSummary(result.summary)) {
+                return {
+                    summary: `Couldn't reach the provider cleanly — the agent's session text looks like a network or auth failure.\n\n` +
+                        `What to try: check your internet, run \`codehere health\`, or rerun in a minute. ` +
+                        `If it persists, switch agents from the dropdown.\n\n` +
+                        `— Raw agent message —\n${result.summary}`,
+                    generatedAt: result.generatedAt,
+                    durationMs: result.durationMs,
+                };
+            }
             return result;
+        }
     }
     return null;
 }
@@ -100,7 +169,17 @@ function tryProvider(binary, prompt, sessionId) {
             settled = true;
             resolve(result);
         };
-        const child = spawn(binary, ['--bare', '-p', prompt], {
+        // Provider args per-binary:
+        //   - `claude-free` (FCC proxy binary) needs `--bare` to skip session
+        //     setup that the proxy doesn't implement.
+        //   - Standard `claude` (the Claude Code Max CLI) MUST NOT use `--bare`
+        //     because `--bare` explicitly rejects OAuth and keychain auth — and
+        //     Claude Code Max users authenticate via OAuth. With `--bare`, the
+        //     fallback path returned empty silently, no Final Report ever
+        //     reached the UI, and the dashboard showed `✓ Final Report` on a
+        //     missing artifact. (May 21, 2026 — root cause of CRIT #1.)
+        const args = binary === 'claude-free' ? ['--bare', '-p', prompt] : ['-p', prompt];
+        const child = spawn(binary, args, {
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         const timeout = setTimeout(() => {

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

@@ -21,6 +21,8 @@
  */
 import { spawn } from 'child_process';
 import { loadTemplate, renderTemplate } from './narrator-prompt-template.js';
+import { isMockMode } from '../../infrastructure/orchestration/mocks/resolve-agent-spawn.js';
+import { mockNarration } from '../../infrastructure/orchestration/mocks/mock-synthesis.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
@@ -37,6 +39,15 @@ function selectProviderBinary() {
     return ['claude-free', 'claude'];
 }
 export async function generateNarration(input) {
+    if (isMockMode()) {
+        const m = mockNarration({ steps: input.steps });
+        return {
+            summary: m.summary,
+            generatedAt: Date.now(),
+            durationMs: m.durationMs,
+            stepCountAtSnapshot: input.steps.length,
+        };
+    }
     const prompt = buildPrompt(input);
     const candidates = selectProviderBinary();
     for (const binary of candidates) {
@@ -75,11 +86,17 @@ function tryProvider(binary, prompt, sessionId, stepCount) {
             try {
                 child.kill();
             }
-            catch { /* ignore */ }
+            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.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) {

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

@@ -21,6 +21,8 @@
  * available; degrades silently to "(untitled)" when no provider responds.
  */
 import { spawn } from 'child_process';
+import { isMockMode } from '../../infrastructure/orchestration/mocks/resolve-agent-spawn.js';
+import { mockTitle } from '../../infrastructure/orchestration/mocks/mock-synthesis.js';
 const TITLE_TIMEOUT_MS = 15_000; // titles are short; abort fast if stuck
 const PROMPT_TEMPLATE = (firstPrompt, cwd) => `Generate a 4-6 word project title from this first user prompt.
 
@@ -163,6 +165,8 @@ export function sanitizeTitle(raw) {
  * Never throws — failure modes return null.
  */
 export async function generateThreadTitle(firstPrompt, cwd) {
+    if (isMockMode())
+        return sanitizeTitle(mockTitle(firstPrompt, cwd)) || null;
     const prompt = PROMPT_TEMPLATE(firstPrompt, cwd);
     for (const binary of selectProviderBinary()) {
         const result = await tryProvider(binary, prompt);

package/dist/application/use-cases/thread-export.js

@@ -0,0 +1,155 @@
+/**
+ * Thread export · v0.8 S4 · signed-payload "GitHub for agent sessions"
+ *
+ * Produces a self-contained, Ed25519-signed bundle of one PersistedSession
+ * that a colleague can verify and replay locally. Local-first by design:
+ * never relayed through codehere's infrastructure · the user shares the
+ * file (or signed URL) by their preferred channel (Slack, email, PR
+ * description) and the recipient runs `codehere thread import <file>`.
+ *
+ * The signature covers a CANONICAL JSON form of the bundle body so two
+ * machines that re-serialize the same data get the same hash. Verification
+ * recomputes the canonical form, re-derives the hash, checks the signature
+ * against the included public key, and returns one of:
+ *   - 'valid'         · signature matches · safe to replay
+ *   - 'tampered'      · signature does NOT match · refuse
+ *   - 'malformed'     · bundle is structurally wrong · refuse
+ *   - 'unknown_key'   · signature valid but public key not in user's trust
+ *                       store · prompt user to trust+continue or refuse
+ *
+ * Pure logic. The CLI + HTTP routes wrap this and do I/O.
+ */
+import { sign as cryptoSign, verify as cryptoVerify, generateKeyPairSync, createPrivateKey, createPublicKey, } from 'crypto';
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Canonicalization · deterministic JSON form so signatures match            */
+/* ──────────────────────────────────────────────────────────────────────── */
+/**
+ * Stable JSON: object keys sorted, no whitespace, primitives preserved.
+ * Two machines that build the same body MUST produce the same bytes for
+ * the signature to verify. We deliberately don't use JSON.stringify with
+ * a replacer because Node's serializer doesn't guarantee key order across
+ * versions/realms.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`cannot canonicalize non-finite number: ${value}`);
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalize).join(',') + ']';
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const parts = keys
+            .filter((k) => obj[k] !== undefined) // undefined → drop the key (JSON convention)
+            .map((k) => JSON.stringify(k) + ':' + canonicalize(obj[k]));
+        return '{' + parts.join(',') + '}';
+    }
+    if (value === undefined)
+        return 'null';
+    throw new Error(`cannot canonicalize type: ${typeof value}`);
+}
+/** Generate a fresh Ed25519 keypair · used for first-time setup. */
+export function generateKeypair() {
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    return { publicKey, privateKey };
+}
+/** Sign a bundle body and produce the full ThreadBundle.
+ *  Ed25519 is NOT a hash-then-sign scheme · pass the message directly to
+ *  crypto.sign(null, msg, key) · the algorithm is implied by the key. */
+export function signBundle(body, keys) {
+    const canonical = canonicalize(body);
+    const sig = cryptoSign(null, Buffer.from(canonical, 'utf-8'), keys.privateKey);
+    const pubRaw = keys.publicKey.export({ format: 'der', type: 'spki' });
+    return {
+        body,
+        signature: sig.toString('base64'),
+        publicKey: pubRaw.toString('base64'),
+        alg: 'ed25519',
+    };
+}
+/**
+ * Verify a bundle. Returns one of:
+ *   - valid        · signature matches AND the publicKey is in trustedKeys
+ *   - valid-untrusted · signature matches but the key isn't in trustedKeys
+ *                        (returned with status='valid' but trusted=false)
+ *   - tampered     · signature doesn't match the recomputed body bytes
+ *   - malformed    · bundle structure broken
+ */
+export function verifyBundle(bundle, trustedKeys = new Set()) {
+    if (!isBundle(bundle))
+        return { status: 'malformed', reason: 'bundle shape is invalid' };
+    if (bundle.alg !== 'ed25519')
+        return { status: 'malformed', reason: `unsupported alg: ${bundle.alg}` };
+    try {
+        const canonical = canonicalize(bundle.body);
+        const pubBuf = Buffer.from(bundle.publicKey, 'base64');
+        const sigBuf = Buffer.from(bundle.signature, 'base64');
+        const pubKey = createPublicKey({ key: pubBuf, format: 'der', type: 'spki' });
+        const ok = cryptoVerify(null, Buffer.from(canonical, 'utf-8'), pubKey, sigBuf);
+        if (!ok)
+            return { status: 'tampered', reason: 'signature does not match body' };
+        const trusted = trustedKeys.has(bundle.publicKey);
+        if (!trusted) {
+            return { status: 'unknown_key', bundle, publicKey: bundle.publicKey };
+        }
+        return { status: 'valid', bundle, trusted: true };
+    }
+    catch (err) {
+        return { status: 'malformed', reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+function isBundle(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const obj = x;
+    if (typeof obj.signature !== 'string')
+        return false;
+    if (typeof obj.publicKey !== 'string')
+        return false;
+    if (typeof obj.alg !== 'string')
+        return false;
+    const body = obj.body;
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const b = body;
+    if (b.schema !== 1)
+        return false;
+    if (b.kind !== 'thread')
+        return false;
+    if (typeof b.sessionId !== 'string')
+        return false;
+    if (typeof b.session !== 'object' || b.session === null)
+        return false;
+    return true;
+}
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Key derivation helpers · PEM encoding for storage                          */
+/* ──────────────────────────────────────────────────────────────────────── */
+export function exportPrivatePem(key) {
+    return key.export({ format: 'pem', type: 'pkcs8' }).toString();
+}
+export function exportPublicPem(key) {
+    return key.export({ format: 'pem', type: 'spki' }).toString();
+}
+export function importPrivatePem(pem) {
+    return createPrivateKey({ key: pem, format: 'pem', type: 'pkcs8' });
+}
+export function importPublicPem(pem) {
+    return createPublicKey({ key: pem, format: 'pem', type: 'spki' });
+}
+/** Compute the base64 publicKey string for a KeyObject · same encoding as in bundles. */
+export function publicKeyToBase64(key) {
+    return key.export({ format: 'der', type: 'spki' }).toString('base64');
+}
+/** Short fingerprint used in human-readable output. */
+export function shortFingerprint(publicKeyB64) {
+    return publicKeyB64.slice(0, 8) + '...' + publicKeyB64.slice(-4);
+}
+//# sourceMappingURL=thread-export.js.map