codehere 0.4.1 → 0.5.0-alpha.3

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

@@ -31,7 +31,11 @@
 import { spawn, execFileSync } from 'child_process';
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
 import { ProgressAggregator } from './progress-aggregator.js';
+import { applyMemoryPrefix } from './memory-injector.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 // `--approval-mode=yolo` auto-accepts every tool action without prompting (the
 // older `--yolo` flag is deprecated). codehere's safety hook is the external
@@ -91,6 +95,9 @@ export function spawnGemini(prompt, options = {}) {
     let statusValue = 'running';
     let killRequested = false;
     const cwd = options.cwd ?? process.cwd();
+    // F3 Task 8 — memory injection (same shape as every other adapter).
+    const injected = applyMemoryPrefix(prompt, cwd, options);
+    const finalPrompt = injected.prompt;
     const snapshot = snapshotCwd(cwd);
     const aggregator = new ProgressAggregator('gemini');
     let stepsSnapshot = [];
@@ -187,7 +194,7 @@ export function spawnGemini(prompt, options = {}) {
     };
     let child;
     try {
-        child = spawn('gemini', ['-p', prompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+        child = spawn('gemini', ['-p', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
             cwd,
             env: spawnEnv,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -301,6 +308,7 @@ export function spawnGemini(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'gemini',
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },
@@ -379,10 +387,38 @@ export const GeminiAdapter = {
                 },
             };
         }
-        // Gemini supports GEMINI_API_KEY (free tier at aistudio.google.com), GOOGLE_API_KEY,
-        // Vertex AI (GOOGLE_GENAI_USE_VERTEXAI=true), GCA (GOOGLE_GENAI_USE_GCA=true), or
-        // cached Google login. Can't verify without a roundtrip — let runtime catch
-        // real failures via ERROR_PATTERNS.auth_missing on the result.error event.
+        // Gemini supports several auth paths:
+        //   env: GEMINI_API_KEY (free tier), GOOGLE_API_KEY, GOOGLE_GENAI_USE_VERTEXAI,
+        //        GOOGLE_GENAI_USE_GCA, GOOGLE_APPLICATION_CREDENTIALS
+        //   file: ~/.gemini/settings.json (the file gemini's own error msg points at)
+        //   file: ~/.gemini/oauth_creds.json (cached Google login)
+        //
+        // Pre-May-1 we returned 'ready' on install alone, deferring to runtime to
+        // catch missing-auth via ERROR_PATTERNS.auth_missing. That was dishonest:
+        // /api/readiness/agents would say 'ready' → user would spawn → 41s later
+        // the task errored with no clear next step. Surfaced May 1 2026 by the
+        // multi-agent dogfood test (see SECURITY_AUDIT_2026-05-01.md spirit —
+        // honest readiness signals are a UX security property).
+        const hasEnvAuth = !!process.env.GEMINI_API_KEY ||
+            !!process.env.GOOGLE_API_KEY ||
+            !!process.env.GOOGLE_GENAI_USE_VERTEXAI ||
+            !!process.env.GOOGLE_GENAI_USE_GCA ||
+            !!process.env.GOOGLE_APPLICATION_CREDENTIALS;
+        const hasFileAuth = existsSync(join(homedir(), '.gemini', 'settings.json')) ||
+            existsSync(join(homedir(), '.gemini', 'oauth_creds.json'));
+        if (!hasEnvAuth && !hasFileAuth) {
+            return {
+                id: this.id,
+                label: this.label,
+                state: 'needs_auth',
+                installed: true,
+                authHint: {
+                    command: 'export GEMINI_API_KEY=...  # free tier: https://aistudio.google.com/apikey',
+                    url: 'https://google-gemini.github.io/gemini-cli/docs/get-started/authentication.html',
+                    detail: 'Gemini found on PATH but no auth detected (no GEMINI_API_KEY env var, no ~/.gemini/settings.json, no ~/.gemini/oauth_creds.json). Free tier available at aistudio.google.com/apikey.',
+                },
+            };
+        }
         return { id: this.id, label: this.label, state: 'ready', installed: true };
     },
 };

package/dist/infrastructure/orchestration/generic-cli-adapter.js

@@ -37,6 +37,7 @@ import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
+import { applyMemoryPrefix } from './memory-injector.js';
 const CONFIG_PATH = join(homedir(), '.codehere', 'agents.yaml');
 const CONFIG_PATH_JSON = join(homedir(), '.codehere', 'agents.json');
 /** Minimal YAML parser for the narrow shape above. Intentionally NOT a full YAML
@@ -134,6 +135,12 @@ function spawnGeneric(cfg, prompt, options = {}) {
     let statusValue = 'running';
     let killRequested = false;
     const cwd = options.cwd ?? process.cwd();
+    // F3 Task 8 — memory injection (same shape as every other adapter).
+    // Apr 29: caught via the adapter-injection-wiring trip-wire — generic
+    // adapters were silently exempt from F3 even though Task 8 said
+    // "every spawned agent." Now consistent.
+    const injected = applyMemoryPrefix(prompt, cwd, options);
+    const finalPrompt = injected.prompt;
     const snapshot = snapshotCwd(cwd);
     const aggregator = new ProgressAggregator(cfg.id);
     let stepsSnapshot = [];
@@ -155,7 +162,7 @@ function spawnGeneric(cfg, prompt, options = {}) {
     const spawnEnv = { ...process.env, ...(cfg.env ?? {}), ...(options.env ?? {}) };
     const usesStdin = cfg.prompt_via === 'stdin';
     const fixedArgs = cfg.args ?? [];
-    const argv = usesStdin ? [...fixedArgs] : [...fixedArgs, prompt];
+    const argv = usesStdin ? [...fixedArgs] : [...fixedArgs, finalPrompt];
     let child;
     try {
         // SAFE · array form (not shell:true) means no shell interpretation.
@@ -172,7 +179,7 @@ function spawnGeneric(cfg, prompt, options = {}) {
             stdio: [usesStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
         });
         if (usesStdin) {
-            child.stdin?.write(prompt);
+            child.stdin?.write(finalPrompt);
             child.stdin?.end();
         }
     }
@@ -264,6 +271,7 @@ function spawnGeneric(cfg, prompt, options = {}) {
         startedAt,
         prompt,
         agent: cfg.id,
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },

package/dist/infrastructure/orchestration/memory-injector.js

@@ -0,0 +1,337 @@
+/**
+ * F3 Task 8 — memory injection into spawned-agent prompts.
+ *
+ * Builds a prompt prefix from the project's `.codehere/` memory layers
+ * (AGENTS.md briefing + working/session.md + semantic/lessons.jsonl + a
+ * slice of episodic/repo_map.json topSymbols) so spawned agents start
+ * warm — with the project's conventions, in-flight context, accumulated
+ * lessons, and the most-referenced symbols already in their context window.
+ *
+ * Pure, side-effect-free, fully unit-tested. Each adapter calls
+ * `buildMemoryPrefix(projectRoot)` near the top of `spawn()`, prepends
+ * the resulting prefix to the user's prompt, and exposes the metadata via
+ * `TaskSession.memoryInjection`.
+ *
+ * Token budget is char-count-approximated (4 chars ≈ 1 token, the
+ * Anthropic / OpenAI rule-of-thumb). Default cap is 3000 tokens —
+ * generous but well under any realistic context window. When budget is
+ * exceeded, sections are dropped in priority order:
+ *
+ *   keep    AGENTS.md         — never dropped if user-edited (the briefing
+ *                                is the primary value)
+ *   drop 3  repo_map slice    — symbols are nice-to-have; the agent can
+ *                                discover them via grep if missing
+ *   drop 2  lessons           — useful but not load-bearing
+ *   drop 1  session.md        — useful for hand-off but redundant if the
+ *                                user re-states their task
+ *
+ * Default-seed detection skips placeholder content (the init seeds for
+ * AGENTS.md / session.md). Same byte-equality-based detection pattern as
+ * memory-command.ts (per feedback_implementation_patterns_v05.md Pattern #1).
+ */
+import { existsSync, readFileSync, realpathSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+const DEFAULT_MAX_TOKENS = 3000;
+const DEFAULT_MAX_LESSONS = 10;
+const DEFAULT_MAX_SYMBOLS = 30;
+// 3 chars per token — conservative ratio per K2 Round 1 feedback. Code
+// tokenizes denser than prose under typical BPE, so the safer-defaults 4/1
+// rule-of-thumb underestimates by 1.5-2x for code-heavy prefixes (which
+// repo_map + lessons.jsonl frequently are). 3/1 stays well clear of model
+// per-message caps without dropping useful content from typical repos.
+const CHARS_PER_TOKEN = 3;
+/** Char-count → token estimate. Conservative — actual tokenization may differ. */
+function estimateTokens(s) {
+    return Math.ceil(s.length / CHARS_PER_TOKEN);
+}
+/**
+ * Detect whether the given file content is still the init-time placeholder.
+ * If so, the user hasn't customized it — injecting the placeholder would
+ * just confuse the agent with template instructions.
+ *
+ * Heuristic: presence of bracketed-instruction lines like `[One-paragraph
+ * description...]` or the `> Per-machine, gitignored` boilerplate, AND no
+ * substantive non-template content after the markers. Conservative — when
+ * in doubt, INCLUDE rather than exclude (better to over-share than miss
+ * the briefing).
+ */
+function looksLikeInitSeed(content, kind) {
+    if (kind === 'agents') {
+        // The init AGENTS/CONTEXT seed has these distinctive bracketed placeholders.
+        // If at least 2 of them are present, treat as untouched.
+        const markers = [
+            /\[One-paragraph description of what this repo does/,
+            /\[How this codebase is organized/,
+            /\[Tone for generated code\./,
+            /\[Don't do X\. Always do Y\./,
+        ];
+        const hits = markers.filter(re => re.test(content)).length;
+        return hits >= 2;
+    }
+    if (kind === 'session') {
+        // The init session.md seed has this header + structure
+        const markers = [
+            /^# Working session/m,
+            /^> Per-machine, gitignored/m,
+            /^## In flight\s*\n+- \[ \]\s*$/m,
+        ];
+        const hits = markers.filter(re => re.test(content)).length;
+        return hits >= 2;
+    }
+    return false;
+}
+/**
+ * Read the project briefing. Search order (highest-priority first):
+ *   1. <projectRoot>/AGENTS.md  — agentic-stack convention; if the user
+ *      has this file at the repo root with real content, it IS their
+ *      canonical briefing and codehere must respect it (Bug 2 from the
+ *      Apr 28 EXP-2 dogfood on `~/code/clipa`).
+ *   2. <codehereDir>/AGENTS.md  — F3-canonical (codehere's own)
+ *   3. <codehereDir>/CONTEXT.md — v0.4.1 back-compat
+ *
+ * Returns the body string + the path that was read (for the prefix
+ * header), or null if no usable briefing exists at any tier (every
+ * candidate is missing, empty, or looks like the init placeholder).
+ */
+function readBriefing(projectRoot, codehereDir) {
+    const candidates = [
+        { path: join(projectRoot, 'AGENTS.md'), label: 'AGENTS.md (repo root)' },
+        { path: join(codehereDir, 'AGENTS.md'), label: '.codehere/AGENTS.md' },
+        { path: join(codehereDir, 'CONTEXT.md'), label: '.codehere/CONTEXT.md' },
+    ];
+    for (const c of candidates) {
+        if (existsSync(c.path)) {
+            try {
+                const body = readFileSync(c.path, 'utf8').trim();
+                if (body.length === 0)
+                    continue;
+                if (looksLikeInitSeed(body, 'agents'))
+                    continue; // placeholder — try next
+                return { body, sourcePath: c.label };
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/** Read working/session.md. Skip if seed-shaped or empty. */
+function readSession(codehereDir) {
+    const p = join(codehereDir, 'memory/working/session.md');
+    if (!existsSync(p))
+        return null;
+    try {
+        const body = readFileSync(p, 'utf8').trim();
+        if (body.length === 0)
+            return null;
+        if (looksLikeInitSeed(body, 'session'))
+            return null;
+        return body;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read up to N lessons from semantic/lessons.jsonl. */
+function readLessons(codehereDir, n) {
+    const p = join(codehereDir, 'memory/semantic/lessons.jsonl');
+    if (!existsSync(p))
+        return [];
+    try {
+        const body = readFileSync(p, 'utf8');
+        return body
+            .split('\n')
+            .filter(line => line.trim().length > 0)
+            .slice(0, n)
+            .map(line => {
+            try {
+                const obj = JSON.parse(line);
+                return typeof obj.text === 'string' ? obj.text : line;
+            }
+            catch {
+                return line;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function readTopSymbols(codehereDir, n) {
+    const p = join(codehereDir, 'memory/episodic/repo_map.json');
+    if (!existsSync(p))
+        return [];
+    try {
+        const body = JSON.parse(readFileSync(p, 'utf8'));
+        if (!Array.isArray(body.topSymbols))
+            return [];
+        return body.topSymbols.slice(0, n);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Format individual sections. Each returns `null` if empty/skipped.
+ */
+function formatBriefing(briefing, sourcePath) {
+    return `# Project briefing (${sourcePath})\n\n${briefing}\n`;
+}
+function formatSession(session) {
+    return `# Current session scratch (.codehere/memory/working/session.md)\n\n${session}\n`;
+}
+function formatLessons(lessons) {
+    const items = lessons.map(l => `- ${l}`).join('\n');
+    return `# Project lessons (.codehere/memory/semantic/lessons.jsonl)\n\n${items}\n`;
+}
+function formatSymbols(symbols) {
+    const lines = symbols.map(s => `- \`${s.name}\` — ${s.file}:${s.line} (${s.references} refs)`).join('\n');
+    return `# Top symbols in this repo (.codehere/memory/episodic/repo_map.json)\n\n${lines}\n`;
+}
+/**
+ * Build the memory-injection prefix for the project at `projectRoot`.
+ *
+ * If `.codehere/` doesn't exist, returns empty (nothing to inject).
+ * Otherwise reads the four sections, formats each, fits to the token
+ * budget by dropping low-priority sections first.
+ */
+export function buildMemoryPrefix(projectRoot, options = {}) {
+    const codehereDir = join(projectRoot, '.codehere');
+    const hasCodehereDir = existsSync(codehereDir);
+    const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const maxLessons = options.maxLessons ?? DEFAULT_MAX_LESSONS;
+    const maxSymbols = options.maxSymbols ?? DEFAULT_MAX_SYMBOLS;
+    // Briefing discovery is INDEPENDENT of .codehere/ presence — a pure
+    // agentic-stack repo (root AGENTS.md, no .codehere/) is a valid
+    // injection source on its own (codex Round 1 fix on Bug 2). Only
+    // session/lessons/repo_map require the .codehere/ tree.
+    const briefing = readBriefing(projectRoot, codehereDir);
+    const session = hasCodehereDir ? readSession(codehereDir) : null;
+    const lessons = hasCodehereDir ? readLessons(codehereDir, maxLessons) : [];
+    const symbols = hasCodehereDir ? readTopSymbols(codehereDir, maxSymbols) : [];
+    // Build candidate sections in PRIORITY order (most-essential first).
+    // Drop direction is REVERSE — least-essential drops first.
+    const candidates = [];
+    if (briefing)
+        candidates.push({ key: 'agents', body: formatBriefing(briefing.body, briefing.sourcePath) });
+    if (session)
+        candidates.push({ key: 'session', body: formatSession(session) });
+    if (lessons.length > 0)
+        candidates.push({ key: 'lessons', body: formatLessons(lessons) });
+    if (symbols.length > 0)
+        candidates.push({ key: 'repo_map', body: formatSymbols(symbols) });
+    if (candidates.length === 0) {
+        return { prefix: '', included: [], tokens: 0, truncated: false };
+    }
+    // Closing separator, always added at the end.
+    const SEPARATOR = '\n---\n\n';
+    const separatorTokens = estimateTokens(SEPARATOR);
+    // Drop from least-essential (last) until everything fits in budget.
+    let truncated = false;
+    let kept = [...candidates];
+    while (kept.length > 0) {
+        const totalChars = kept.reduce((acc, c) => acc + c.body.length, 0);
+        const totalTokens = estimateTokens(kept.map(c => c.body).join('\n')) + separatorTokens;
+        if (totalTokens <= maxTokens)
+            break;
+        // Drop the last (least-essential) section.
+        kept.pop();
+        truncated = true;
+        void totalChars;
+    }
+    // Edge: even AGENTS alone is over budget — truncate AGENTS body itself.
+    if (kept.length === 1 && estimateTokens(kept[0].body) + separatorTokens > maxTokens) {
+        const room = (maxTokens - separatorTokens) * CHARS_PER_TOKEN;
+        const truncatedBody = kept[0].body.slice(0, Math.max(0, room - 32)) + '\n... [truncated to fit]\n';
+        kept = [{ key: kept[0].key, body: truncatedBody }];
+        truncated = true;
+    }
+    if (kept.length === 0) {
+        return { prefix: '', included: [], tokens: 0, truncated };
+    }
+    const prefix = kept.map(c => c.body).join('\n') + SEPARATOR;
+    return {
+        prefix,
+        included: kept.map(c => c.key),
+        tokens: estimateTokens(prefix),
+        truncated,
+    };
+}
+/**
+ * Walk up from `startPath` looking for the nearest ancestor (inclusive)
+ * that codehere can inject memory FROM — meaning EITHER:
+ *   - has a `.codehere/` directory (codehere-initialized project), OR
+ *   - has a root-level `AGENTS.md` (agentic-stack convention)
+ *
+ * Returns the REAL filesystem ancestor path (symlinks resolved), or
+ * `null` if no such ancestor exists.
+ *
+ * codex Round 1 BLOCKER fix: spawning a task from a subdirectory (e.g.
+ * `cd src/auth && codehere task ...`) would miss the project root if we
+ * only used the immediate cwd. Hence the upward walk.
+ *
+ * codex Round 2 BLOCKER fix: the upward walk must walk the REAL
+ * filesystem ancestry, not the LEXICAL one. Without `realpathSync`,
+ * `cwd` inside a symlinked subtree ascends through the lexical path and
+ * misses the real project root. Real scenario for iCloud-symlinked /
+ * shared-volume / mounted-drive projects.
+ *
+ * Bug 2 Round 2 BLOCKER fix: also accept a project root that has a
+ * root-level `AGENTS.md` even WITHOUT `.codehere/`. A pure agentic-stack
+ * repo (clipa-style) is a valid injection source on its own.
+ *
+ * Stops at the filesystem root. Symlink-following on read is the right
+ * asymmetry per ADR-012 (the symlink defense applies to writes, not reads).
+ */
+function findProjectRoot(startPath) {
+    let current;
+    try {
+        current = realpathSync(resolve(startPath));
+    }
+    catch {
+        // Broken symlink at startPath itself — fall back to lexical resolve.
+        // (Better to attempt some lookup than fail outright.)
+        current = resolve(startPath);
+    }
+    // Bound the loop at the filesystem root by checking dirname stability.
+    for (;;) {
+        if (existsSync(join(current, '.codehere')) ||
+            existsSync(join(current, 'AGENTS.md'))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Adapter-side convenience: turn a raw user prompt into the spawn-ready
+ * prompt + the diagnostic record. Each of the 5 built-in adapters calls
+ * this near the top of `spawn()` and uses the returned `prompt` going
+ * forward, plus exposes `record` via `TaskSession.memoryInjection`.
+ *
+ * Walks UPWARD from `cwd` to find the nearest ancestor with `.codehere/`,
+ * so spawning from a subdirectory still gets injection (codex Round 1 fix).
+ *
+ * Returns `{ prompt: <unchanged>, record: undefined }` when:
+ *   - `options.noMemoryPrefix` is true (caller opted out)
+ *   - no ancestor of `cwd` has `.codehere/` (nothing to inject)
+ *   - all sections are empty / placeholder seeds
+ */
+export function applyMemoryPrefix(prompt, cwd, options) {
+    if (options.noMemoryPrefix)
+        return { prompt, record: undefined };
+    const projectRoot = findProjectRoot(cwd);
+    if (projectRoot === null)
+        return { prompt, record: undefined };
+    const r = buildMemoryPrefix(projectRoot);
+    if (r.prefix === '')
+        return { prompt, record: undefined };
+    return {
+        prompt: r.prefix + prompt,
+        record: { included: r.included, tokens: r.tokens, truncated: r.truncated },
+    };
+}
+//# sourceMappingURL=memory-injector.js.map

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

@@ -13,7 +13,11 @@
 import { spawn, execFileSync } from 'child_process';
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
 import { ProgressAggregator } from './progress-aggregator.js';
+import { applyMemoryPrefix } from './memory-injector.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 const HEADLESS_FLAGS = ['run', '--format', 'json'];
 const ERROR_PATTERNS = [
@@ -45,6 +49,9 @@ export function spawnOpenCode(prompt, options = {}) {
     let statusValue = 'running';
     let killRequested = false;
     const cwd = options.cwd ?? process.cwd();
+    // F3 Task 8 — memory injection (same shape as every other adapter).
+    const injected = applyMemoryPrefix(prompt, cwd, options);
+    const finalPrompt = injected.prompt;
     const snapshot = snapshotCwd(cwd);
     const aggregator = new ProgressAggregator('opencode');
     let stepsSnapshot = [];
@@ -115,7 +122,7 @@ export function spawnOpenCode(prompt, options = {}) {
     let child;
     try {
         // OpenCode's `run` expects the message as positional args, not stdin.
-        child = spawn('opencode', [...HEADLESS_FLAGS, prompt, ...(options.extraArgs ?? [])], {
+        child = spawn('opencode', [...HEADLESS_FLAGS, finalPrompt, ...(options.extraArgs ?? [])], {
             cwd,
             env: spawnEnv,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -206,6 +213,7 @@ export function spawnOpenCode(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'opencode',
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },
@@ -266,9 +274,31 @@ export const OpenCodeAdapter = {
                 installHint: { command: 'curl -fsSL https://opencode.ai/install | bash', url: 'https://opencode.ai' },
             };
         }
-        // OpenCode manages its own provider credentials via `opencode providers`.
-        // Can't statically probe the config without reading its data dir — treat
-        // install as ready, let runtime codehere:error catch auth failures.
+        // OpenCode manages its own provider credentials via `opencode auth`
+        // (alias `opencode providers`). The auth file lives at
+        // $XDG_DATA_HOME/opencode/auth.json (default ~/.local/share/opencode/auth.json
+        // on Linux/macOS) — created with mode 600 the first time a provider is added.
+        //
+        // Pre-May-1 we returned 'ready' on install alone, deferring to runtime to
+        // catch missing-auth via ERROR_PATTERNS.auth_missing. That was dishonest:
+        // /api/readiness/agents would say 'ready' → user would spawn → ~50s later
+        // the task errored with no clear next step. Surfaced May 1 2026 by the
+        // multi-agent dogfood test alongside the same-shape gemini fix.
+        const xdgData = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+        const opencodeAuthPath = join(xdgData, 'opencode', 'auth.json');
+        if (!existsSync(opencodeAuthPath)) {
+            return {
+                id: this.id,
+                label: this.label,
+                state: 'needs_auth',
+                installed: true,
+                authHint: {
+                    command: 'opencode auth  # interactive provider/key wizard',
+                    url: 'https://opencode.ai/docs/configuration',
+                    detail: `OpenCode found on PATH but no provider configured (${opencodeAuthPath} missing). Run \`opencode auth\` once to add an AI provider — supports 75+ providers BYOK including Anthropic, OpenAI, Mistral, etc.`,
+                },
+            };
+        }
         return { id: this.id, label: this.label, state: 'ready', installed: true };
     },
 };

package/dist/infrastructure/orchestration/progress-aggregator.js

@@ -101,6 +101,8 @@ export class ProgressAggregator {
             return this.ingestCodex(type, data);
         if (this.agentId === 'gemini')
             return this.ingestGemini(type, data);
+        if (this.agentId === 'aider')
+            return this.ingestAider(type, data);
         return false;
     }
     /** Flush: mark every still-active step as failed (called on abnormal exit). */
@@ -195,6 +197,123 @@ export class ProgressAggregator {
         }
         return false;
     }
+    /**
+     * Aider observability parity (v0.5 Path B per docs/design/f3_memory_spec.md
+     * + ~/.claude/.../memory/learning_aider.md).
+     *
+     * Aider doesn't expose a structured event stream — we parse stdout lines
+     * matching the EXACT patterns aider's `base_coder.py` writes when it
+     * applies an edit, creates a new file, or runs a shell command (verified
+     * against installed aider 0.86.2 source — line refs below).
+     *
+     * Patterns we match:
+     *   "Running <command>"               — base_coder.py:2472 — fires AFTER
+     *     aider's confirm_ask returns yes (which `--yes-always` answers
+     *     automatically). Aider has already started executing by the time we see
+     *     this — OBSERVABILITY, not blocking.
+     *   "Applied edit to <path>"          — base_coder.py:2334 — fires after
+     *     a SEARCH/REPLACE block lands. Used for both edits AND net-new files
+     *     created via the same flow (aider doesn't distinguish in this message).
+     *   "Creating empty file <path>"      — base_coder.py:461 — fires when
+     *     aider creates a brand-new empty file as scaffolding before edits.
+     *
+     * Patterns we DELIBERATELY do NOT match:
+     *   "Did not apply edit to ..."       — explicit non-event; we drop these
+     *     (would be a false-positive Edit step otherwise).
+     *   "Create new file?"                — that's a CONFIRM_ASK prompt, not a
+     *     tool_output. With `--yes-always` it never fires interactively, and
+     *     it's not the action-taken signal anyway.
+     *
+     * Each matched pattern → one ProgressStep marked done immediately (aider
+     * doesn't emit separate completion events; the line itself IS the completion).
+     *
+     * Label vocabulary is aligned with Claude / Gemini / Codex labels for
+     * cross-agent UI consistency: `Run X` for shell, `Edit <path>` for file
+     * edits, `Write <path>` for net-new file creation.
+     *
+     * ANSI handling: HEADLESS_FLAGS in aider-adapter.ts include `--no-pretty`
+     * which strips colors. As defense-in-depth (in case extraArgs override that
+     * or aider regresses), we strip ANSI escape sequences before matching.
+     *
+     * Limitation: codehere CANNOT block aider's actions via this path. The
+     * upstream-PR Path A (adding `--pre-action-hook` to aider) is what enables
+     * blocking parity. v0.5 ships observability; v0.5.x or v0.6 ships blocking
+     * once Path A merges.
+     */
+    // eslint-disable-next-line no-control-regex
+    static ANSI_RE = /\x1b\[[0-9;]*m/g;
+    /**
+     * Per-instance set of file paths aider just created via "Creating empty file ...".
+     * Aider emits BOTH `Creating empty file <p>` AND `Applied edit to <p>` for one
+     * logical net-new-file creation (file gets touched, then initial content
+     * gets applied). Without this set we'd record two steps (`Write <p>` then
+     * `Edit <p>`) for one action — codex Round 2 caught this. We suppress the
+     * subsequent `Applied edit to` for the same path so the user sees `Write`
+     * once, not `Write` followed by `Edit`.
+     */
+    aiderJustCreated = new Set();
+    ingestAider(type, data) {
+        if (type !== 'stdout')
+            return false;
+        const raw = typeof data.line === 'string' ? data.line : '';
+        // Strip ANSI escape codes BEFORE matching so the parser survives a
+        // `--no-pretty` regression or override.
+        const line = raw.replace(ProgressAggregator.ANSI_RE, '').trim();
+        if (!line)
+            return false;
+        // EXPLICIT NON-EVENT: defense-in-depth guard. The `^Applied edit to` regex
+        // below wouldn't match "Did not apply edit to ..." because of the anchor,
+        // but if either pattern ever loosens, this short-circuit prevents a false
+        // Edit step from creeping in.
+        if (/^Did not apply edit to\s+/.test(line))
+            return false;
+        // "Running <command>" — base_coder.py:2472
+        let m = line.match(/^Running\s+(.+)$/);
+        if (m) {
+            this._steps.push({
+                label: truncate('Run ' + m[1]),
+                state: 'done',
+                startedAt: Date.now(),
+                completedAt: Date.now(),
+            });
+            return true;
+        }
+        // "Applied edit to <path>" — base_coder.py:2334
+        m = line.match(/^Applied edit to\s+(.+)$/);
+        if (m) {
+            const path = m[1];
+            // If aider JUST created this file, the Write step already represents the
+            // action; skip the Edit step that aider emits for the initial content.
+            // Clear from the set after consuming so subsequent edits to the same
+            // path (in this same session) DO show as Edit.
+            if (this.aiderJustCreated.has(path)) {
+                this.aiderJustCreated.delete(path);
+                return false;
+            }
+            this._steps.push({
+                label: 'Edit ' + shortPath(path),
+                state: 'done',
+                startedAt: Date.now(),
+                completedAt: Date.now(),
+            });
+            return true;
+        }
+        // "Creating empty file <path>" — base_coder.py:461 — net-new file scaffold
+        m = line.match(/^Creating empty file\s+(.+)$/);
+        if (m) {
+            const path = m[1];
+            this.aiderJustCreated.add(path);
+            // Use "Write" to align with Claude/Gemini's net-new-file label vocabulary.
+            this._steps.push({
+                label: 'Write ' + shortPath(path),
+                state: 'done',
+                startedAt: Date.now(),
+                completedAt: Date.now(),
+            });
+            return true;
+        }
+        return false;
+    }
     ingestCodex(type, data) {
         if (type !== 'item.completed')
             return false;