codehere 0.7.1 → 1.0.1

package/dist/infrastructure/orchestration/agents-config-seed.js

@@ -1,21 +1,22 @@
+import { writeFileAtomic } from '../storage/atomic-write.js';
 /**
  * Seed ~/.codehere/agents.yaml on first daemon start.
  *
- * Ships with NO pre-populated adapters. Users who want codehere to drive a
- * CLI agent beyond the built-in four (Claude Code, Codex, Aider, OpenCode)
- * add their own entry to `~/.codehere/agents.yaml` and restart the daemon.
+ * Ships with ONE pre-wired generic adapter — Cursor — because it's been verified
+ * on a real machine (cursor-agent headless, authed via the Cursor subscription).
+ * It stays hidden in the UI until `cursor-agent` is installed + logged in, so it
+ * never inflates the agent count dishonestly. Any other CLI agent: users add their
+ * own entry to `~/.codehere/agents.yaml` and restart the daemon.
  *
- * Rationale: shipping scaffolded entries we hadn't actually verified on real
- * machines produced a "9 agents supported" claim that wasn't honest. The
- * generic-cli-adapter mechanism is still available — users opt in per agent
- * by editing the YAML themselves.
+ * Rationale: the bar for shipping a scaffolded entry is "verified on a real
+ * machine," not "plausible." Cursor met it; the rest stay opt-in via the YAML.
  *
  * Re-seed never overwrites an existing file.
  */
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
-const CONFIG_PATH = join(homedir(), '.codehere', 'agents.yaml');
+const CONFIG_PATH = join(process.env.CODEHERE_HOME || homedir(), '.codehere', 'agents.yaml');
 const DEFAULT_YAML = `# codehere — pluggable agent adapters
 #
 # Built-in adapters (no configuration needed — just install the CLI):
@@ -40,14 +41,25 @@ const DEFAULT_YAML = `# codehere — pluggable agent adapters
 #     install_command: brew install my-agent-cli   # optional · enables "Install" button
 #     install_url: https://example.com/docs         # optional · docs link
 
-agents: []
+# Cursor — verified on a real machine (2026-06-22): cursor-agent runs headless and
+# authenticates with your Cursor subscription, so it's a cost-bounded cross-vendor
+# peer to the metered APIs. Hidden until \`cursor-agent\` is installed + logged in.
+agents:
+  - id: cursor
+    label: Cursor
+    command: cursor-agent
+    args: [-p, --output-format, stream-json, -f, --model, gpt-5.5-high]
+    prompt_via: argv
+    format: jsonl
+    install_command: curl https://cursor.com/install -fsS | bash
+    install_url: https://docs.cursor.com/cli
 `;
 export function seedAgentsConfig() {
     try {
         if (existsSync(CONFIG_PATH))
             return;
         mkdirSync(dirname(CONFIG_PATH), { recursive: true });
-        writeFileSync(CONFIG_PATH, DEFAULT_YAML, 'utf-8');
+        writeFileAtomic(CONFIG_PATH, DEFAULT_YAML);
     }
     catch {
         /* best-effort */

package/dist/infrastructure/orchestration/aider-adapter.js

@@ -18,6 +18,7 @@ import { randomUUID } from 'crypto';
 import { startRecording } from './cassette-recorder.js';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { resolveAgentSpawn } from './mocks/resolve-agent-spawn.js';
+import { detectOllama } from './detect-ollama.js';
 import { applyMemoryPrefix } from './memory-injector.js';
 import { mirrorToolCallToAudit } from '../hooks/mirror-tool-call-to-audit.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
@@ -27,6 +28,12 @@ const HEADLESS_FLAGS = [
     '--no-pretty', // disable ANSI colors in output
     '--no-stream', // stream=false → one chunk per turn, cleaner stdout parsing
     '--no-auto-commits', // don't auto-commit — leave file changes for artifacts-extractor
+    // Aider detects URLs in the message and, under --yes-always, silently
+    // scrapes them. Our injected context (memory pack, repo docs) legitimately
+    // contains URLs — live 2026-07-02 a verify run burned its whole turn failing
+    // to scrape `codehere.uk` (markdown backtick glued onto the URL) and that
+    // noise became the report. Headless runs never want surprise scraping.
+    '--no-detect-urls',
 ];
 // v0.7 HIGH-1 fix — extended ERROR_PATTERNS for the 18+ provider families
 // Aider supports. Pre-fix: 4 regexes shaped only for Anthropic + OpenAI text.
@@ -39,7 +46,9 @@ const ERROR_PATTERNS = [
     {
         code: 'credit_low',
         // Anthropic + OpenAI canonical + DeepSeek ("Insufficient Balance").
-        regex: /credit balance is too low|insufficient.*credit|no credits|you exceeded your current quota|insufficient.balance/i,
+        // Adjacent words only — a spanning /insufficient.*credit/ combines distant
+        // benign prose under the de-wrap collapse (2026-06-07 cold review).
+        regex: /credit balance is too low|insufficient\s+credits?\b|no credits\b|you exceeded your current quota|insufficient\s+balance/i,
         message: 'The API key has no credit (or balance is too low).',
         recovery: 'Aider needs a billed API key with balance. Top up at your provider (console.anthropic.com / ' +
             'platform.openai.com / platform.deepseek.com), or switch the task to Claude Code / Codex / Gemini ' +
@@ -49,7 +58,7 @@ const ERROR_PATTERNS = [
         code: 'auth_invalid',
         // Anthropic + OpenAI + Anthropic's actual "invalid x-api-key" + Gemini's
         // "API key not valid" + Bedrock's "UnrecognizedClientException" + generic.
-        regex: /invalid api key|invalid x-api-key|api key not valid|authentication.*failed|401 unauth|please provide your.*api key|unrecognizedclientexception|the security token included in the request is invalid/i,
+        regex: /invalid api key|invalid x-api-key|api key not valid|authentication\s+(?:request\s+)?failed|401 unauth|please provide your\s+\S{0,20}\s*api key|unrecognizedclientexception|the security token included in the request is invalid/i,
         message: 'Aider auth was rejected or missing.',
         recovery: 'Check the API key for your model provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, ' +
             'GEMINI_API_KEY, AWS_ACCESS_KEY_ID for Bedrock, etc.). Re-export and retry.',
@@ -57,13 +66,19 @@ const ERROR_PATTERNS = [
     {
         code: 'rate_limit',
         // Generic 429 + named providers (Gemini RESOURCE_EXHAUSTED, Bedrock ThrottlingException).
-        regex: /rate.?limit(ed)?|429|too many requests|resource.exhausted|throttlingexception/i,
+        // Deliberately requires error-shaped context ("rate limited", "rate limit
+        // exceeded") — a bare /rate.?limit/ matches the literal filename
+        // rate-limit.ts in an "Applied edit to …" line and flags a SUCCESSFUL run
+        // as failed (2026-06-07 batch cold review, HIGH).
+        regex: /\brate.?limited\b|rate.?limit\s*(?:exceeded|reached|hit|error)|hit.{0,20}rate.?limit|\b429\b|too many requests|resource.?exhausted|throttlingexception/i,
         message: 'Aider was rate-limited by the provider.',
         recovery: 'Wait a minute and retry, or switch --model via extraArgs to a different provider.',
     },
     {
         code: 'model_unavailable',
-        regex: /model.*(not found|not available|unavailable|does not exist)|invalidmodelid/i,
+        // Bounded gap (≤40 chars, no sentence boundary) so "model X not found"
+        // matches but "model" + distant "not found" in prose doesn't combine.
+        regex: /model\b[^.!?]{0,40}(not found|not available|unavailable|does not exist)|invalidmodelid/i,
         message: 'Aider could not find the model.',
         recovery: 'Run `aider --list-models` and pass `--model <name>` via extraArgs.',
     },
@@ -76,11 +91,58 @@ const ERROR_PATTERNS = [
         recovery: 'Network or provider endpoint issue. For local Ollama: confirm `ollama serve` is running. ' +
             'For cloud providers: check internet + provider status page.',
     },
+    // 2026-06-07 user-#1 dogfood (session 4b6bc481): aider HARD-WRAPS its error
+    // body at ~80 cols, so "Your credit\nbalance is too low" lands on two lines.
+    // The per-line scan above never sees the contiguous phrase → no failover →
+    // exit 0 → a no-op run presented as "verified". The litellm exception CLASS
+    // name always rides ONE line (it's the prefix before the wrapped JSON), so
+    // these are wrap-proof fingerprints. Keep them last so the more specific
+    // phrase patterns above win when they DO land on a single line.
+    {
+        code: 'credit_low',
+        regex: /litellm\.(?:BadRequestError|InsufficientCreditsError).*(?:credit|balance|quota)/i,
+        message: 'The API key has no credit (or balance is too low).',
+        recovery: 'Aider needs a billed API key with balance. Top up at your provider (console.anthropic.com / ' +
+            'platform.openai.com / platform.deepseek.com), or switch the task to Claude Code / Codex / Gemini ' +
+            'which use subscription or free-tier auth.',
+    },
+    {
+        code: 'auth_invalid',
+        regex: /litellm\.(?:AuthenticationError|PermissionDeniedError)/i,
+        message: 'Aider auth was rejected or missing.',
+        recovery: 'Check the API key for your model provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, ' +
+            'GEMINI_API_KEY, AWS_ACCESS_KEY_ID for Bedrock, etc.). Re-export and retry.',
+    },
+    {
+        code: 'rate_limit',
+        regex: /litellm\.RateLimitError/i,
+        message: 'Aider was rate-limited by the provider.',
+        recovery: 'Wait a minute and retry, or switch --model via extraArgs to a different provider.',
+    },
+    {
+        code: 'model_unavailable',
+        regex: /litellm\.NotFoundError/i,
+        message: 'Aider could not find the model.',
+        recovery: 'Run `aider --list-models` and pass `--model <name>` via extraArgs.',
+    },
+    {
+        code: 'network_failure',
+        regex: /litellm\.(?:APIConnectionError|Timeout|ServiceUnavailableError)/i,
+        message: "Aider couldn't reach the model provider.",
+        recovery: 'Network or provider endpoint issue. For local Ollama: confirm `ollama serve` is running. ' +
+            'For cloud providers: check internet + provider status page.',
+    },
 ];
-function scanForKnownError(text) {
+export function scanForKnownError(text) {
+    // Aider wraps long error bodies across lines; collapse whitespace so a phrase
+    // split by a hard wrap ("Your credit\nbalance is too low") is matched as one
+    // contiguous string. Scan BOTH the raw text (preserves single-line patterns
+    // like litellm class names) and the de-wrapped text (recovers wrapped phrases).
+    const dewrapped = text.replace(/\s+/g, ' ');
     for (const p of ERROR_PATTERNS) {
-        if (p.regex.test(text))
+        if (p.regex.test(text) || p.regex.test(dewrapped)) {
             return { code: p.code, message: p.message, recovery: p.recovery };
+        }
     }
     return null;
 }
@@ -105,7 +167,16 @@ export function spawnAider(prompt, options = {}) {
     let stepsSnapshot = [];
     let artifactsSnapshot;
     let textAccum = '';
+    // Bounded tail of recent stdout for error scanning. Aider hard-wraps error
+    // bodies at ~80 cols, so a wrapped phrase spans 2-3 ADJACENT lines — a small
+    // tail catches it. Scanning the WHOLE accumulated buffer instead would let
+    // prose from unrelated parts of a successful run combine into a phrase match
+    // (2026-06-07 batch cold review, HIGH: a session about rate limiting read as
+    // a rate-limit failure).
+    let scanTail = '';
+    const SCAN_TAIL_CHARS = 600;
     let usageSnapshot;
+    let aiderModel; // model aider announced in stdout → per-model cost
     let errorEmitted = false;
     const emit = (event) => {
         buffer.push(event);
@@ -120,6 +191,12 @@ export function spawnAider(prompt, options = {}) {
         if (event.type === 'stdout' && event.data?.line) {
             const line = String(event.data.line);
             textAccum += line + '\n';
+            // Aider announces its model: "Main model: claude-3-5-sonnet-... with ...".
+            if (!aiderModel) {
+                const mm = line.match(/(?:main )?model:\s*([A-Za-z0-9._/:-]+)/i);
+                if (mm)
+                    aiderModel = mm[1];
+            }
             // #110 slice 3 — mirror aider tool calls to the audit log. Match
             // the same stdout patterns the aggregator parses (per
             // learning_aider.md): "Running <cmd>" → Bash, "Applied edit to
@@ -156,6 +233,7 @@ export function spawnAider(prompt, options = {}) {
                 usageSnapshot = {
                     inputTokens: (usageSnapshot?.inputTokens ?? 0) + sent,
                     outputTokens: (usageSnapshot?.outputTokens ?? 0) + recv,
+                    ...(aiderModel ? { model: aiderModel } : {}),
                 };
             }
         }
@@ -163,7 +241,21 @@ export function spawnAider(prompt, options = {}) {
             const data = event.data;
             let text = '';
             if ((event.type === 'stderr' || event.type === 'stdout') && typeof data?.line === 'string') {
-                text = data.line;
+                // Scan a bounded RECENT tail, not just this one line and not the whole
+                // buffer. Aider hard-wraps error bodies across lines (user-#1 dogfood,
+                // session 4b6bc481), so a single-line scan misses "Your credit\nbalance
+                // is too low" — but the whole accumulated buffer lets distant prose
+                // combine into false matches. The wrapped phrase always sits on
+                // adjacent lines, so the tail window catches it. The de-wrap collapse
+                // in scanForKnownError joins the wrapped phrase. stderr is scanned
+                // line-by-line (it isn't accumulated).
+                if (event.type === 'stdout') {
+                    scanTail = (scanTail + '\n' + data.line).slice(-SCAN_TAIL_CHARS);
+                    text = scanTail;
+                }
+                else {
+                    text = data.line;
+                }
             }
             if (text) {
                 const hit = scanForKnownError(text);
@@ -193,9 +285,28 @@ export function spawnAider(prompt, options = {}) {
         }
     });
     const spawnEnv = { ...process.env, ...(options.env ?? {}) };
+    // Local-first reliable vendor: when the user hasn't pinned a model (no
+    // AIDER_MODEL / CODEHERE_AIDER_MODEL env, no --model in extraArgs) and Ollama
+    // is serving a local model, default aider to it. That turns aider into a FREE,
+    // RELIABLE, LOCAL second vendor (no rate limits, no cloud key, no waste) — the
+    // unlock for the cross-vendor wedge on a machine that has Ollama. Always
+    // overridable; opt out with CODEHERE_NO_LOCAL_OLLAMA=1.
+    const extra = options.extraArgs ?? [];
+    const modelPinned = !!spawnEnv.AIDER_MODEL ||
+        !!spawnEnv.CODEHERE_AIDER_MODEL ||
+        extra.some((a) => a === '--model' || a.startsWith('--model='));
+    const localArgs = [];
+    if (!modelPinned && spawnEnv.CODEHERE_NO_LOCAL_OLLAMA !== '1') {
+        const ollama = detectOllama();
+        if (ollama.available && ollama.model) {
+            localArgs.push('--model', `ollama_chat/${ollama.model}`);
+            if (!spawnEnv.OLLAMA_API_BASE)
+                spawnEnv.OLLAMA_API_BASE = 'http://localhost:11434';
+        }
+    }
     let child;
     try {
-        const sp = resolveAgentSpawn('aider', 'aider', ['--message', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], finalPrompt);
+        const sp = resolveAgentSpawn('aider', 'aider', ['--message', finalPrompt, ...HEADLESS_FLAGS, ...localArgs, ...extra], finalPrompt);
         child = spawn(sp.command, sp.args, {
             cwd,
             env: spawnEnv,
@@ -261,19 +372,28 @@ export function spawnAider(prompt, options = {}) {
         // Preserve 'error' if we already flipped to it on codehere:error.
         statusValue =
             killRequested || signal !== null ? 'killed' : errorEmitted ? 'error' : code === 0 ? 'completed' : 'error';
-        if (aggregator.finalize(statusValue === 'completed' ? 'completed' : statusValue === 'killed' ? 'killed' : 'error')) {
-            stepsSnapshot = aggregator.steps.map((s) => ({ ...s }));
-            emit({ type: 'codehere:steps', timestamp: Date.now(), data: { steps: stepsSnapshot } });
-        }
+        const finalizeChanged = aggregator.finalize(statusValue === 'completed' ? 'completed' : statusValue === 'killed' ? 'killed' : 'error');
+        // Extract artifacts BEFORE emitting steps so the git-diff fallback can run.
         if (statusValue === 'completed') {
             try {
                 artifactsSnapshot = { ...extractArtifacts(snapshot, textAccum), usage: usageSnapshot };
-                emit({ type: 'codehere:artifacts', timestamp: Date.now(), data: artifactsSnapshot });
             }
             catch {
                 /* best-effort */
             }
         }
+        // Aider parity safety net: if the brittle stdout-parse produced no
+        // file-action steps but git shows real changes, synthesize them from the
+        // diff so the timeline + report can't claim "did nothing" on a real edit.
+        const fallbackChanged = aggregator.applyFileFallback(artifactsSnapshot?.files);
+        // PM steps BEFORE artifacts BEFORE exit (client closes SSE on exit; order matters).
+        if (finalizeChanged || fallbackChanged) {
+            stepsSnapshot = aggregator.steps.map((s) => ({ ...s }));
+            emit({ type: 'codehere:steps', timestamp: Date.now(), data: { steps: stepsSnapshot } });
+        }
+        if (artifactsSnapshot) {
+            emit({ type: 'codehere:artifacts', timestamp: Date.now(), data: artifactsSnapshot });
+        }
         emit({
             type: 'exit',
             timestamp: Date.now(),
@@ -344,7 +464,11 @@ export function spawnAider(prompt, options = {}) {
                 let stderr = '';
                 // Route follow-ups through the mock seam too — under CODEHERE_MOCK=1 this
                 // hits the mock REPL, not real aider. (Was a real-spend leak.)
-                const sp2 = resolveAgentSpawn('aider', 'aider', ['--restore-chat-history', '--message', text, ...HEADLESS_FLAGS], text);
+                // BUG-1 (E2E 2.4) · pin the follow-up to the SAME model as the original
+                // spawn (localArgs + extra). Without them, a free ollama session's reply
+                // fell back to aider's default cloud model + env API key — a silent
+                // vendor/spend switch, observed live 2026-07-18.
+                const sp2 = resolveAgentSpawn('aider', 'aider', ['--restore-chat-history', '--message', text, ...HEADLESS_FLAGS, ...localArgs, ...extra], text);
                 const followup = spawn(sp2.command, sp2.args, {
                     cwd,
                     env: spawnEnv,
@@ -413,33 +537,73 @@ export const AiderAdapter = {
                 installHint: { command: 'brew install aider', url: 'https://aider.chat/docs/install.html' },
             };
         }
-        // Aider has no subscription path — needs a BILLED API key with credit.
-        // If neither Anthropic nor OpenAI key is present → needs_auth.
-        // If a key IS present but the user is running on a Claude Code subscription
-        // (no billing configured), Aider will hit credit_low at runtime. We can't
-        // detect that pre-spawn without making an API call. Flag the risk in the
-        // detail string so the UI can surface it.
+        // Aider has no subscription path, but it routes through LiteLLM — so it can
+        // run on a BILLED key (Anthropic/OpenAI, needs credit) OR for FREE on a
+        // Gemini AI-Studio key / DeepSeek / a local Ollama model, by passing
+        // `--model <provider>/<model>`. The pre-May "needs a BILLED key" hint was
+        // misleading for free-tier-first users (Phase 1): it sent them to top up a
+        // card when a free Gemini key would have worked. We can't verify credit
+        // pre-spawn without an API call, so we surface BOTH paths honestly.
         const hasAnthropic = !!process.env.ANTHROPIC_API_KEY;
         const hasOpenai = !!process.env.OPENAI_API_KEY;
-        if (!hasAnthropic && !hasOpenai) {
+        const hasGemini = !!process.env.GEMINI_API_KEY || !!process.env.GOOGLE_API_KEY;
+        const hasDeepseek = !!process.env.DEEPSEEK_API_KEY;
+        const FREE_PATH = 'Free option: set GEMINI_API_KEY (aistudio.google.com/apikey) and run aider with `--model gemini/gemini-2.5-flash`, or point it at a local Ollama model (`--model ollama/…`) — aider routes through LiteLLM, so no paid key is required.';
+        // A configured model + its matching key = genuinely READY (the user picked a
+        // working combo, so don't fall through to billed_key_required). AIDER_MODEL
+        // is aider's own env override (= `--model`); it's how codehere routes aider
+        // to a free provider, since the task intake doesn't pass --model. A local
+        // model (ollama/…) needs no cloud key — ready by config, like claude's
+        // subscription (runtime catches a down endpoint via the network fingerprint).
+        const model = (process.env.AIDER_MODEL || '').toLowerCase();
+        const modelReady = (model.startsWith('gemini') && hasGemini) ||
+            (model.startsWith('deepseek') && hasDeepseek) ||
+            (model.startsWith('openai') && hasOpenai) ||
+            (model.startsWith('anthropic') && hasAnthropic) ||
+            model.startsWith('ollama') ||
+            model.startsWith('ollama_chat');
+        if (modelReady) {
+            return { id: this.id, label: this.label, state: 'ready', installed: true };
+        }
+        // Local-first: a serving Ollama model makes aider ready for FREE with no
+        // cloud key. The spawn path auto-routes aider to it (detect-ollama) when no
+        // model is pinned — so readiness agrees, or the intake gate would refuse a
+        // spawn that will actually run. Mirrors the spawn-side guard on the ENV pins
+        // (AIDER_MODEL / CODEHERE_AIDER_MODEL / CODEHERE_NO_LOCAL_OLLAMA); it cannot
+        // see a per-task extraArgs `--model` (readiness has never seen extraArgs —
+        // the product's /api/task intake doesn't pass them, so this is unreachable
+        // through the surface, just honestly noted).
+        const localPinnedAway = !!process.env.CODEHERE_AIDER_MODEL || process.env.CODEHERE_NO_LOCAL_OLLAMA === '1';
+        if (!model && !localPinnedAway && detectOllama().available) {
+            return { id: this.id, label: this.label, state: 'ready', installed: true };
+        }
+        if (!hasAnthropic && !hasOpenai && !hasGemini && !hasDeepseek) {
             return {
                 id: this.id,
                 label: this.label,
                 state: 'needs_auth',
                 installed: true,
                 authHint: {
-                    detail: 'Aider needs a BILLED API key (Anthropic or OpenAI). Unlike Claude Code, it has no subscription path.',
-                    url: 'https://console.anthropic.com',
+                    command: 'export GEMINI_API_KEY=...  # free tier: https://aistudio.google.com/apikey',
+                    detail: `Aider has no subscription path, but it doesn't need a paid key either. ${FREE_PATH} A billed Anthropic/OpenAI key with credit also works.`,
+                    url: 'https://aistudio.google.com/apikey',
                 },
             };
         }
+        // A provider key is present. If it's only the free Gemini/DeepSeek key,
+        // aider runs at $0 but needs `--model …` to target that provider. If it's a
+        // billed Anthropic/OpenAI key, that key needs real credit. Either way the
+        // key's mere presence doesn't guarantee a successful first call.
+        const onlyFree = !hasAnthropic && !hasOpenai && (hasGemini || hasDeepseek);
         return {
             id: this.id,
             label: this.label,
             state: 'billed_key_required',
             installed: true,
             authHint: {
-                detail: 'API key detected. Aider requires the key to have billing credit (not just presence). If you run on a Claude Code subscription, Aider will fail at the first model call.',
+                detail: onlyFree
+                    ? `Free provider key detected (${hasGemini ? 'Gemini' : 'DeepSeek'}). Aider runs at $0 on it, but target it explicitly with \`--model ${hasGemini ? 'gemini/gemini-2.5-flash' : 'deepseek/deepseek-chat'}\` — aider's default model expects an Anthropic/OpenAI key.`
+                    : `API key detected. Aider needs the key to have billing credit (not just presence). If you run on a Claude Code subscription, Aider will fail at the first model call. ${FREE_PATH}`,
             },
         };
     },

package/dist/infrastructure/orchestration/artifacts-extractor.js

@@ -43,7 +43,12 @@ function statBaseline(fullPath) {
 function captureDirtyBaseline(cwd, repoRoot) {
     const baseline = new Map();
     try {
-        const out = execFileSync('git', ['status', '--porcelain', '-z'], {
+        // -uall: porcelain normally collapses an untracked DIRECTORY into one
+        // "?? dir/" entry, while changedFiles() lists its contents per-file via
+        // ls-files --others — so the baseline could never match those paths and a
+        // whole pre-existing untracked dir got attributed to the agent (2026-06-07
+        // v1 walk: memory-init's .codehere/ scaffolding showed as 8 agent edits).
+        const out = execFileSync('git', ['status', '--porcelain', '-uall', '-z'], {
             cwd,
             encoding: 'utf-8',
             timeout: 5000,
@@ -117,6 +122,13 @@ export function snapshotCwd(cwd) {
     }
 }
 /** Collect {path, +, -} from git diff (numstat) + untracked files (wc -l). */
+// codehere's own per-project state dir. Its contents (memory, protocols,
+// skills, context packs) are product plumbing, not the user's code — they
+// never belong in the room's "what the agent changed" list, even when the
+// memory write-back touches them mid-session.
+function isInternalPath(path) {
+    return path === '.codehere' || path.startsWith('.codehere/') || path.includes('/.codehere/');
+}
 function changedFiles(snap) {
     if (!snap.isGitRepo)
         return [];
@@ -134,6 +146,8 @@ function changedFiles(snap) {
             if (!m)
                 continue;
             const [, aStr, rStr, path] = m;
+            if (isInternalPath(path))
+                continue;
             out.push({
                 path,
                 added: aStr === '-' ? 0 : parseInt(aStr, 10) || 0,
@@ -155,6 +169,8 @@ function changedFiles(snap) {
         for (const rel of untracked.split('\n')) {
             if (!rel.trim())
                 continue;
+            if (isInternalPath(rel))
+                continue;
             // Count lines in the new file. Untracked paths come from git relative
             // to repoRoot — must join with repoRoot, not cwd, when cwd is a subdir.
             try {
@@ -315,8 +331,50 @@ function filterBySpawnBaseline(snap, files) {
         }
     });
 }
+/** The spawned tool's OWN housekeeping — never the task's work product. Live
+ *  2026-07-02: aider wrote .aider* + a .gitignore line on a run that did
+ *  nothing else, the audit confirmed those writes on disk, and a no-op run
+ *  graded proven/green off its tool's litter. Chat histories, tool caches,
+ *  and the .gitignore edits tools make to hide them don't count as work.
+ *  .gitignore is dropped ONLY when every added line is tool litter — a task
+ *  whose real job is editing .gitignore still counts. */
+const TOOL_HOUSEKEEPING = /(^|\/)\.(aider|claude|codehere|gemini|codex|opencode)[^/]*($|\/)/i;
+const LITTER_LINE = /^\s*($|#|\.?(aider|claude|codehere|gemini|codex|opencode))/i;
+function gitignoreOnlyLitter(snap, path) {
+    try {
+        const d = execFileSync('git', ['diff', snap.head ?? 'HEAD', '--', path], {
+            cwd: snap.cwd,
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        let added = d
+            .split('\n')
+            .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+            .map((l) => l.slice(1));
+        if (added.length === 0) {
+            // Untracked (brand-new) .gitignore: git diff HEAD shows nothing — the
+            // whole file is the addition.
+            added = readFileSync(join(snap.cwd, path), 'utf-8').split('\n');
+        }
+        const lines = added.filter((l) => l.trim().length > 0);
+        return lines.length > 0 && lines.every((l) => LITTER_LINE.test(l));
+    }
+    catch {
+        return false; // can't inspect — keep it counted (honest over-count beats hiding work)
+    }
+}
+function dropToolHousekeeping(snap, files) {
+    return files.filter((f) => {
+        if (TOOL_HOUSEKEEPING.test(f.path))
+            return false;
+        if (/(^|\/)\.gitignore$/.test(f.path))
+            return !gitignoreOnlyLitter(snap, f.path);
+        return true;
+    });
+}
 export function extractArtifacts(snap, collectedStdout) {
-    const raw = changedFiles(snap);
+    const raw = dropToolHousekeeping(snap, changedFiles(snap));
     const sessionScoped = filterByMtime(snap, raw);
     const agentLikely = filterBySpawnBaseline(snap, sessionScoped);
     const files = annotateTrust(snap, agentLikely);

package/dist/infrastructure/orchestration/cassette-recorder.js

@@ -38,7 +38,7 @@ const NULL_RECORDER = {
 export function startRecording(opts) {
     if (process.env[ENV_FLAG] !== '1')
         return NULL_RECORDER;
-    const outDir = opts.outDir ?? join(homedir(), '.codehere', 'cassettes', opts.adapter);
+    const outDir = opts.outDir ?? join(process.env.CODEHERE_HOME || homedir(), '.codehere', 'cassettes', opts.adapter);
     const scenario = `organic-${opts.sessionId.slice(0, 8)}`;
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
     const path = join(outDir, `${scenario}-${stamp}.jsonl`);