codehere 0.4.1 → 0.5.0-alpha.3

package/README.md

@@ -4,7 +4,7 @@
 
 [![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-362%2F362-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-443%2F443-brightgreen)]()
 [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
 
 codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, OpenCode, or Gemini), spawns it, streams its work back to you, and hands you a plain-English Final Report with a **trust score on every file changed**. Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; other adapters are session-traced and reported, with per-tool hook parity planned for v0.4.
@@ -26,8 +26,9 @@ One manager, many specialists, every action recorded.
 | 2 | **Detect environment** | `codehere setup` — checks API key, finds your repo |
 | 3 | **Install the safety hook** | `codehere hook install` — every Claude Code tool call now audited |
 | 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode / Gemini also supported · see [docs/integrations/](../docs/integrations/) for Cursor MCP setup) |
-| 5 | **Scaffold this repo** | `cd /your/repo && codehere init` — creates `.codehere/CONTEXT.md`, `HANDOVER.md`, `PROMPTS.md` |
-| 6 | **Fill in CONTEXT.md** | 5 minutes. The agent will follow what's written there. |
+| 5 | **Scaffold this repo** | `cd /your/repo && codehere init` — creates `.codehere/` with the F3 memory tree (working / episodic / semantic / personal / candidates) plus `AGENTS.md` (project briefing) and `skills/` (prompt templates) |
+| 6 | **Fill in AGENTS.md** | 5 minutes. The agent will follow what's written there. |
+| 7 | **Build the symbol map (optional)** | `codehere memory repo-map` — JSON map of every top-level export in your repo, ranked by reference count. Spawned agents read it on entry instead of cold-grepping. |
 
 You're done. `codehere start` opens the web UI at `:3773`; you delegate from there.
 
@@ -43,11 +44,20 @@ Context  +  End State  +  Constraints
 
 ### Folder convention (what `codehere init` writes)
 
-| File | Purpose | Committed? |
+The v0.5 layout — F3 project memory:
+
+| Path | Purpose | Committed? |
 |---|---|---|
-| `.codehere/CONTEXT.md` | What this repo is. Conventions. Style. Constraints. | yes |
-| `.codehere/HANDOVER.md` | Cross-session continuity (until F3 memory ships in v0.5). | **no** |
-| `.codehere/PROMPTS.md` | Your library of recurring task prompts. | yes |
+| `.codehere/AGENTS.md` *(or legacy `CONTEXT.md`)* | What this repo is. Conventions. Style. Constraints. | yes |
+| `.codehere/memory/working/session.md` *(or legacy `HANDOVER.md`)* | What's in flight in the current session. | **no** |
+| `.codehere/memory/episodic/AGENT_LEARNINGS.jsonl` | Symlink to your full session history at `~/.codehere/sessions.jsonl`. | (symlink) |
+| `.codehere/memory/episodic/repo_map.json` | Ranked symbol map. Built by `codehere memory repo-map`. | yes |
+| `.codehere/memory/semantic/lessons.jsonl` | Project-specific lessons promoted from episodic patterns. | yes |
+| `.codehere/memory/personal/preferences.json` | Per-developer prefs. | **no** |
+| `.codehere/skills/<name>/SKILL.md` *(or legacy flat `PROMPTS.md`)* | Prompt templates — one folder per skill. | yes |
+| `.codehere/protocols/permissions.md` + `hook_patterns.json` | Safety policy for the PreToolUse hook. | yes |
+
+Upgrading from v0.4.1? Run `codehere memory init` once — it migrates `CONTEXT/HANDOVER/PROMPTS` into the new layout and leaves symlinks at the old paths so back-compat holds. `--dry-run` shows what would move first.
 
 ---
 
@@ -75,6 +85,52 @@ codehere status         # quick dashboard · sessions, blocks, trust trends
 
 The hook intercepts every `Bash`, `Edit`, `Write`, `MultiEdit`, and `NotebookEdit` call from any Claude Code session running on your machine, runs it through the trust-scorer pattern bank in under 5 ms, blocks anything matching the destructive / credential / injection patterns, and appends every decision to an append-only JSONL audit log at `~/.codehere/audit/`. (Hook coverage today is Claude Code-only — Codex / Aider / OpenCode adapters spawn through their native CLIs and emit to `~/.codehere/sessions.jsonl`; full hook parity across all adapters is v0.4 work.)
 
+## Memory · F3 (v0.5)
+
+Once you've run `codehere init` in a project, every spawned agent — Claude Code, Codex, Aider, OpenCode, or Gemini — automatically reads the project's memory on entry. The agent starts warm with the briefing, recent lessons, and the most-referenced symbols in your codebase, instead of cold-grepping every session.
+
+**What gets injected, in priority order:**
+1. **`.codehere/AGENTS.md`** — your project briefing (conventions, style, constraints)
+2. **`.codehere/memory/working/session.md`** — what's in flight right now (per-machine, gitignored)
+3. **`.codehere/memory/semantic/lessons.jsonl`** — graduated project-wide lessons
+4. **`.codehere/memory/episodic/repo_map.json`** — top-N most-referenced symbols (run `codehere memory repo-map` to build / refresh)
+
+The injection is token-budget-aware (default ~3000 tokens, drops lower-priority sections first to fit; AGENTS.md is never dropped). Pass `--no-memory-prefix` if you want the bare prompt for a one-off task.
+
+**Inspect what would inject** before spawning anything:
+```bash
+codehere memory show injection
+```
+
+**Add a lesson** so future spawns learn from it:
+```bash
+codehere memory graduate --add "auth tests live alongside source files"
+```
+
+**See everything codehere has accumulated:**
+```bash
+codehere memory show              # one-line summary per layer
+codehere memory show semantic     # numbered lesson list
+codehere memory show episodic     # session count + top symbols
+codehere memory show protocols    # safety patterns by category
+```
+
+**Other memory commands:**
+- `codehere memory init` — migrate the v0.4.1 layout (`CONTEXT.md` / `HANDOVER.md` / `PROMPTS.md`) into the F3 layout (one shot, leaves back-compat symlinks; `--dry-run` previews)
+- `codehere memory repo-map [--rebuild]` — build the symbol map; v0.5 ships a TS-native MVP, v0.6 swaps in tree-sitter
+- `codehere protocols export [--rebuild]` — write the trust-scorer pattern bank to `.codehere/protocols/hook_patterns.json` for inspection / cross-tool ingestion
+
+## Going deeper
+
+For technical readers — the living documents that describe codehere as a system, not just a CLI:
+
+| Doc | What it is |
+|---|---|
+| [`docs/decisions/`](../docs/decisions/) | ADR registry — every locked architectural decision (audit-first moat, supervisor-agent positioning, local-first, F3 memory layout, generic-CLI adapter, ...) numbered, dated, with rejected alternatives + rollback triggers |
+| [`docs/THREAT_MODEL.md`](../docs/THREAT_MODEL.md) | Every attack surface, current mitigation, residual risk, planned hardening — npm supply chain, hook bypass, symlink redirect, audit log tampering, MCP server, prompt injection |
+| [`docs/CAPABILITIES.md`](../docs/CAPABILITIES.md) | Honest matrix of what each adapter can and cannot do today — Claude Code, Codex, Aider, OpenCode, Gemini, Generic CLI — across spawn, stream, per-tool block, audit, F3 memory, auth |
+| [`agent/REPO_MAP.md`](./REPO_MAP.md) | One-line-per-file index of the 54 source files with their top-level exports — generated, regenerated via `npm run repomap` after renames |
+
 ## Commands
 
 ```
@@ -129,6 +185,7 @@ For depth beyond this README:
 - **[CODEHERE.md](../CODEHERE.md)** · product spec · positioning, six-ring adoption funnel, F0–F6 foundations, defensibility, GTM, revenue model
 - **[EXPERIENCE.md](../EXPERIENCE.md)** · the human story · how engineering teams, CISOs, and regulated-industry buyers adopt codehere
 - **[AUDIT.md](../AUDIT.md)** · pre-publish audit report · methodology, findings, remediation
+- **[docs/SECURITY_AUDIT_2026-05-01.md](../docs/SECURITY_AUDIT_2026-05-01.md)** · first-party security audit · OWASP Top 10 + STRIDE · 0 critical / 0 high · 2 medium fixed inline · methodology disclosed · reproducible
 - **[CONTRIBUTING.md](../CONTRIBUTING.md)** · how to contribute · setup, commit discipline, testing philosophy
 - **[SECURITY.md](../SECURITY.md)** · responsible disclosure · `security@codehere.uk`
 - **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** · community standards

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

@@ -0,0 +1,144 @@
+/**
+ * Final Report — PM-UX Layer 3 · MVP (v0.5.0-alpha.3+).
+ *
+ * At task exit, generates a 3-paragraph plain-English summary of what the
+ * agent did, what was touched, and what the user should look at. Prints to
+ * stdout so the dogfood-while-building loop sees the artifact immediately.
+ *
+ * Provider strategy (MVP — try free first, fall back to paid):
+ *   - Tries `claude-free --bare -p "<prompt>"` first. The `claude-free`
+ *     wrapper is what actually routes through the FCC proxy at :8082
+ *     (verified 2026-05-02 dogfood: plain `claude --bare` does NOT route
+ *     through FCC — it hits paid Claude. The May 1 memory rule was wrong.)
+ *   - Falls back to `claude --bare -p "<prompt>"` if `claude-free` is not
+ *     installed (paid path; will fail gracefully if no credit).
+ *   - If neither binary is installed, returns null silently (no report).
+ *
+ * Env override: set CODEHERE_REPORT_BINARY=<binary-name> to force a
+ * specific provider (e.g. for testing or non-default setups).
+ *
+ * Iterations 5-9 (2026-05-02) refuted the "we own the supervisory layer"
+ * thesis. Final Report is the keystone delivery moment per the v3 chain
+ * (claim_market_position) — it's the artifact the dogfood loop produces
+ * that none of the surveyed competitors (ComposioHQ, Overstory, Praktor,
+ * Claude Squad, AI-Agents-Orchestrator) advertise.
+ */
+import { spawn } from 'child_process';
+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.
+
+Paragraph 1: What the agent DID. Verb-led. Name files specifically. 1-3 sentences.
+Paragraph 2: What was TOUCHED. Files modified, line counts, anything that looks risky. 1-3 sentences.
+Paragraph 3: What the developer should LOOK AT. Open concerns, things to verify.
+             If everything looks clean, say so explicitly. 1-2 sentences.
+
+Be specific. Don't pad. Don't editorialize. Don't praise the agent.
+
+The task was: ${i.prompt}
+The agent used: ${i.agent}
+Duration: ${i.durationMs}ms
+Status: ${i.status}
+
+Steps the agent took:
+${i.steps.length ? i.steps.map((s) => `- ${s.label} (${s.state})`).join('\n') : '(no structured steps captured)'}
+
+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')
+    : '(no file artifacts captured)'}
+
+Token usage: ${i.artifacts?.usage?.inputTokens ?? 0} in / ${i.artifacts?.usage?.outputTokens ?? 0} out
+
+Now write the 3 paragraphs.`;
+const REPORT_TIMEOUT_MS = 30_000;
+/** Provider chain: try free first, then paid. Override with CODEHERE_REPORT_BINARY. */
+function selectProviderBinary() {
+    const override = process.env.CODEHERE_REPORT_BINARY;
+    if (override)
+        return [override];
+    return ['claude-free', 'claude'];
+}
+/**
+ * Generate a Final Report. Returns null if no provider is reachable.
+ * Never throws — failure modes return null + log a debug line.
+ */
+export async function generateFinalReport(input) {
+    const prompt = PROMPT_TEMPLATE(input);
+    for (const binary of selectProviderBinary()) {
+        const result = await tryProvider(binary, prompt, input.sessionId);
+        if (result)
+            return result;
+    }
+    return null;
+}
+function tryProvider(binary, prompt, sessionId) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const child = spawn(binary, ['--bare', '-p', prompt], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const timeout = setTimeout(() => {
+            child.kill('SIGTERM');
+            if (process.env.CODEHERE_DEBUG === '1') {
+                console.error(`[final-report] ${binary} timeout after ${REPORT_TIMEOUT_MS}ms for ${sessionId}`);
+            }
+            finish(null);
+        }, REPORT_TIMEOUT_MS);
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            // ENOENT = binary not installed. Silent fallback to next provider in chain.
+            if (process.env.CODEHERE_DEBUG === '1') {
+                console.error(`[final-report] ${binary} unavailable: ${err.message}`);
+            }
+            finish(null);
+        });
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                if (process.env.CODEHERE_DEBUG === '1') {
+                    console.error(`[final-report] ${binary} exited ${code}: ${stderr.slice(0, 200)}`);
+                }
+                finish(null);
+                return;
+            }
+            const summary = stdout.trim();
+            if (!summary) {
+                finish(null);
+                return;
+            }
+            finish({ summary, generatedAt: Date.now(), durationMs: Date.now() - startedAt });
+        });
+    });
+}
+/**
+ * Pretty-print to terminal. Used by session-manager when a spawned task exits.
+ * Wrapped in try/catch upstream — never let a print failure surface.
+ */
+export function printFinalReportToTerminal(input, output) {
+    const banner = '─'.repeat(60);
+    process.stdout.write('\n');
+    process.stdout.write(`${banner}\n`);
+    process.stdout.write(`Final Report · ${input.agent} · ${input.sessionId.slice(0, 8)}\n`);
+    process.stdout.write(`${banner}\n`);
+    process.stdout.write(`${output.summary}\n`);
+    process.stdout.write(`${banner}\n`);
+    process.stdout.write(`(generated in ${output.durationMs}ms)\n`);
+    process.stdout.write('\n');
+}
+//# sourceMappingURL=generate-final-report.js.map

package/dist/index.js

@@ -16,6 +16,8 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
 import { executeInitCommand } from './presentation/cli/commands/init-command.js';
+import { executeMemoryCommand } from './presentation/cli/commands/memory-command.js';
+import { executeProtocolsCommand } from './presentation/cli/commands/protocols-command.js';
 import { executeConfigCommand } from './presentation/cli/commands/config-command.js';
 import { executeHelpCommand } from './presentation/cli/commands/help-command.js';
 import { executeStatusCommand } from './presentation/cli/commands/status-command.js';
@@ -103,6 +105,47 @@ program
     .action((options) => {
     executeInitCommand({ force: options.force, noGitignore: !options.gitignore });
 });
+// ── memory ───────────────────────────────────────────────────────────────────
+// F3 v0.5: project memory operations. `memory init` migrates v0.4.1 layout
+// (CONTEXT/HANDOVER/PROMPTS) into the four-layer F3 layout (AGENTS.md +
+// memory/ + skills/). `memory repo-map` builds a JSON symbol map. Future:
+// memory show, memory graduate.
+program
+    .command('memory')
+    .description('F3 project memory · init / repo-map / show / graduate / help')
+    .argument('[action]', 'Action: init, repo-map, show, graduate, help')
+    .argument('[layer]', 'Layer for `memory show` (working / episodic / semantic / personal / skills / protocols / injection)')
+    .option('-f, --force', 'Overwrite existing target files (memory init)')
+    .option('--no-symlinks', 'Delete old paths instead of leaving back-compat symlinks (memory init)')
+    .option('--dry-run', 'Print planned moves without touching disk (memory init)')
+    .option('--rebuild', 'Force a fresh build (memory repo-map)')
+    .option('--add <text>', 'Add a free-text lesson directly (memory graduate)')
+    .option('--accept <id>', 'Graduate a candidate by id (memory graduate)')
+    .option('--reject <id>', 'Reject a candidate by id without graduating (memory graduate)')
+    .action((action, layer, options) => {
+    executeMemoryCommand(action, {
+        force: options.force,
+        noSymlinks: !options.symlinks,
+        dryRun: options.dryRun,
+        rebuild: options.rebuild,
+        layer,
+        add: options.add,
+        accept: options.accept,
+        reject: options.reject,
+    });
+});
+// ── protocols ────────────────────────────────────────────────────────────────
+// F3 v0.5: protocols layer operations. `protocols export` writes the
+// trust-scorer pattern bank to .codehere/protocols/hook_patterns.json so
+// auditors / cross-tool consumers can read codehere's safety surface.
+program
+    .command('protocols', { hidden: true }) // hidden from --help (May 2 cut: power-user F3 export, see docs/MEMORY.md)
+    .description('F3 protocols layer · export (write hook_patterns.json from trust-scorer bank)')
+    .argument('[action]', 'Action: export, help')
+    .option('--rebuild', 'Refresh built-in patterns (project patterns are preserved)')
+    .action((action, options) => {
+    executeProtocolsCommand(action, { rebuild: options.rebuild });
+});
 // ── config ───────────────────────────────────────────────────────────────────
 program
     .command('config')
@@ -302,7 +345,7 @@ program
 // ── serve (MCP server) ───────────────────────────────────────────────────────
 program
     .command('serve')
-    .description('Start codehere as an MCP server — expose trust tools to Claude Desktop, Cursor, and any MCP client')
+    .description('Run codehere as a background MCP server (no web UI) — for Claude Desktop / Cursor integration')
     .option('-p, --port <number>', 'Port to listen on', '3773')
     .option('--host <host>', 'Host to bind to (default: 127.0.0.1)', '127.0.0.1')
     .option('--token <token>', 'Require Bearer token for authentication')
@@ -363,7 +406,7 @@ program
 // ── start (Mission Control: daemon + web UI) ─────────────────────────────────
 program
     .command('start')
-    .description('Start the codehere daemon — task intake UI + MCP server at localhost:3773')
+    .description('Start codehere — interactive PM dashboard at localhost:3773 (delegate tasks, watch agents work)')
     .option('-p, --port <number>', 'Port to listen on', '3773')
     .option('--host <host>', 'Host to bind to', '127.0.0.1')
     .option('--no-open', "Don't auto-open the browser")
@@ -556,7 +599,7 @@ program
 });
 // ── scan-tool (called by Claude Code hooks system, not users directly) ───────
 program
-    .command('scan-tool')
+    .command('scan-tool', { hidden: true }) // hidden from --help (May 2 cut: internal hook handler, called by Claude Code via stdin)
     .description('Hook handler: reads Claude Code tool event from stdin, outputs block/allow (used by hook system)')
     .option('--log-only', 'Never block, log only')
     .option('--block-all', 'Block on any finding, not just critical')
@@ -570,7 +613,7 @@ program
 });
 // ── completion (shell completion script generator) ──────────────────────────
 program
-    .command('completion')
+    .command('completion', { hidden: true }) // hidden from --help (May 2 cut: shell-completion is npm convention, not product surface)
     .description('Generate shell completion script')
     .argument('<shell>', 'Shell type: bash, zsh, or fish')
     .action(async (shell) => {

package/dist/infrastructure/hooks/claude-sdk-hook.js

@@ -13,7 +13,7 @@
  *
  * Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
  */
-import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { appendFileSync, chmodSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 const PATTERNS = [
@@ -392,9 +392,24 @@ export function appendAuditLog(entry) {
     try {
         const dir = AUDIT_FILE.substring(0, AUDIT_FILE.lastIndexOf('/'));
         if (dir && !existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
+            // mode 0o700 — owner-only directory. The audit log records every tool call
+            // including bash commands and file paths; on multi-user systems a default
+            // 0o755 dir would let other users walk in and read the file. Surfaced by
+            // the May 1 2026 /cso security audit (Finding #1, MEDIUM).
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        // mode 0o600 — owner-only file. Same reasoning as the dir above. Only takes
+        // effect on first write (file creation); existing files are chmod'd below
+        // for backwards compatibility with audit logs created before this fix.
+        appendFileSync(AUDIT_FILE, JSON.stringify(entry) + '\n', { mode: 0o600 });
+        // Idempotent: if the file existed pre-fix with 0o644, tighten it now. The
+        // chmod is cheap and silent on already-0o600 files.
+        try {
+            chmodSync(AUDIT_FILE, 0o600);
+        }
+        catch {
+            /* fall through — chmod failure shouldn't block the audit append */
         }
-        appendFileSync(AUDIT_FILE, JSON.stringify(entry) + '\n');
     }
     catch {
         // Audit log failure must not block tool execution

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

@@ -16,6 +16,7 @@ import { spawn, execFileSync } from 'child_process';
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
 import { ProgressAggregator } from './progress-aggregator.js';
+import { applyMemoryPrefix } from './memory-injector.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 const HEADLESS_FLAGS = [
     '--yes-always', // auto-accept all file-edit confirmations
@@ -70,8 +71,16 @@ export function spawnAider(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('aider'); // no-op aggregator; emits no steps
+    // ProgressAggregator parses aider's stdout for `Running ...`, `Applied edit
+    // to ...`, and `Creating empty file ...` lines and emits Run/Edit/Write
+    // ProgressSteps. Observability parity (Path B) — see ingestAider() in
+    // progress-aggregator.ts. Blocking parity (Path A) needs the upstream
+    // `--pre-action-hook` PR.
+    const aggregator = new ProgressAggregator('aider');
     let stepsSnapshot = [];
     let artifactsSnapshot;
     let textAccum = '';
@@ -139,7 +148,7 @@ export function spawnAider(prompt, options = {}) {
     const spawnEnv = { ...process.env, ...(options.env ?? {}) };
     let child;
     try {
-        child = spawn('aider', ['--message', prompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+        child = spawn('aider', ['--message', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
             cwd,
             env: spawnEnv,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -225,6 +234,7 @@ export function spawnAider(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'aider',
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },

package/dist/infrastructure/orchestration/claude-code-adapter.js

@@ -19,6 +19,7 @@ import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
+import { applyMemoryPrefix } from './memory-injector.js';
 // Runtime-error fingerprints → structured codehere:error events with recovery hints.
 // Matched against any stderr line or assistant-text content we see on the stream.
 const ERROR_PATTERNS = [
@@ -78,6 +79,12 @@ export function spawnClaudeCode(prompt, options = {}) {
     let killRequested = false;
     // PM UX Layer 2+3 state. Shared helper modules; per-session instances.
     const cwd = options.cwd ?? process.cwd();
+    // F3 Task 8 — inject project memory (AGENTS.md + lessons + repo_map slice)
+    // into the prompt prefix unless the caller opted out. Pure, side-effect-
+    // free; returns unchanged prompt + record=undefined when there's no
+    // .codehere/ at cwd.
+    const injected = applyMemoryPrefix(prompt, cwd, options);
+    const finalPrompt = injected.prompt;
     const snapshot = snapshotCwd(cwd);
     const aggregator = new ProgressAggregator('claude-code');
     let stepsSnapshot = [];
@@ -176,7 +183,7 @@ export function spawnClaudeCode(prompt, options = {}) {
     }
     let child;
     try {
-        child = spawn('claude', ['-p', prompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
+        child = spawn('claude', ['-p', finalPrompt, ...HEADLESS_FLAGS, ...(options.extraArgs ?? [])], {
             cwd,
             env: spawnEnv,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -277,6 +284,8 @@ export function spawnClaudeCode(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'claude-code',
+        canAppendMessage: true,
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },
@@ -309,6 +318,66 @@ export function spawnClaudeCode(prompt, options = {}) {
                 }
             }, 3000);
         },
+        /**
+         * Iter 12 — follow-up message to a completed session. Spawns a fresh
+         * `claude -p "<text>" -c` in the same cwd, which uses Claude Code's
+         * native -c flag to continue the most recent conversation in that dir.
+         *
+         * Scope: one-shot Q&A. No streaming, no event piping into the parent
+         * emitter. Returns the assistant's response text. Iter 13 may upgrade
+         * to a true thread-streaming model if the dogfood signal warrants.
+         */
+        appendMessage(text) {
+            const startedAt = Date.now();
+            return new Promise((resolve, reject) => {
+                let stdout = '';
+                let stderr = '';
+                const followup = spawn('claude', ['-p', text, '-c', ...HEADLESS_FLAGS], {
+                    cwd,
+                    env: spawnEnv,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                followup.on('error', (err) => reject(err));
+                followup.stdout?.on('data', (chunk) => {
+                    stdout += chunk.toString('utf-8');
+                });
+                followup.stderr?.on('data', (chunk) => {
+                    stderr += chunk.toString('utf-8');
+                });
+                followup.on('exit', (code) => {
+                    if (code !== 0) {
+                        reject(new Error(`claude -c exited ${code}: ${stderr.slice(0, 200)}`));
+                        return;
+                    }
+                    // Parse stream-json — extract assistant message text from the
+                    // 'assistant' typed lines and the final 'result' line.
+                    const lines = stdout.split('\n').filter((l) => l.trim());
+                    const fragments = [];
+                    for (const line of lines) {
+                        try {
+                            const obj = JSON.parse(line);
+                            if (obj.type === 'assistant' && obj.message?.content) {
+                                for (const block of obj.message.content) {
+                                    if (block.type === 'text' && block.text)
+                                        fragments.push(block.text);
+                                }
+                            }
+                            else if (obj.type === 'result' && typeof obj.result === 'string') {
+                                fragments.push(obj.result);
+                            }
+                        }
+                        catch {
+                            // Non-JSON line — skip
+                        }
+                    }
+                    // Dedupe trivially: if 'result' contained the same text as the
+                    // last assistant block, take just one. Conservative: prefer 'result'
+                    // if present (it's the final summary), else join assistants.
+                    const result = fragments.length ? fragments[fragments.length - 1] : '(no response captured)';
+                    resolve({ result, durationMs: Date.now() - startedAt });
+                });
+            });
+        },
     };
 }
 // ── AgentAdapter implementation ─────────────────────────────────────────────

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

@@ -18,6 +18,7 @@ import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
+import { applyMemoryPrefix } from './memory-injector.js';
 const HEADLESS_FLAGS = [
     'exec',
     '--json',
@@ -73,6 +74,9 @@ export function spawnCodex(prompt, options = {}) {
     // PM UX Layer 2+3 state — same shape as claude-code-adapter. Kept in-file (not
     // extracted to a base class) because the two CLIs diverge in more than they share.
     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('codex');
     let stepsSnapshot = [];
@@ -151,7 +155,7 @@ export function spawnCodex(prompt, options = {}) {
             env: spawnEnv,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
-        child.stdin?.write(prompt);
+        child.stdin?.write(finalPrompt);
         child.stdin?.end();
     }
     catch (err) {
@@ -241,6 +245,7 @@ export function spawnCodex(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'codex',
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },

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

@@ -284,8 +284,17 @@ function spawnConductor(prompt, options, lookup) {
     let artifactsSnapshot;
     specialistSession.subscribe((evt) => {
         buffer.push(evt);
-        emitter.emit('event', evt);
-        // Mirror progress + artifacts so PM-UX layers see them on the Conductor session, too.
+        // Mirror progress + artifacts BEFORE re-emitting so any subscriber that
+        // reads `session.status` / `session.steps` / `session.artifacts` from
+        // inside its event handler sees the up-to-date conductor state.
+        //
+        // BUG 2 (zombie RUNNING sessions, May 1 2026, 138/155 records affected):
+        // pre-fix this block emitted FIRST and updated status SECOND. session-
+        // manager.ts subscribes to the conductor session and persists `session.status`
+        // synchronously inside its on-exit handler. With emit-before-update,
+        // every conductor session was persisted with status='running' even though
+        // the underlying specialist had already finished. The fix reorders so the
+        // emit() at the end sees the freshly-mirrored statusValue.
         if (specialistSession.steps)
             stepsSnapshot = specialistSession.steps;
         if (specialistSession.artifacts)
@@ -298,6 +307,7 @@ function spawnConductor(prompt, options, lookup) {
         if (evt.type === 'exit' || evt.type === 'codehere:complete' || evt.type === 'codehere:error') {
             statusValue = specialistSession.status;
         }
+        emitter.emit('event', evt);
     });
     return {
         sessionId,