codehere 0.3.4 → 0.5.0-alpha.2

package/README.md

@@ -4,10 +4,10 @@
 
 [![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, or OpenCode), 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.
+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.
 
 One manager, many specialists, every action recorded.
 
@@ -25,9 +25,10 @@ One manager, many specialists, every action recorded.
 | 1 | **Install** | `npm install -g codehere` (Node 20+) |
 | 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 also supported) |
-| 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. |
+| 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/` 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.
 
 ---
 
@@ -57,7 +67,7 @@ Context  +  End State  +  Constraints
 
 1. Spawns the agent with the right headless flags
 2. Streams the steps back as readable progress · *"Read src/auth.ts · Edit src/auth.ts · Run npm test"*
-3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live. For Codex / Aider / OpenCode tasks: emits the agent's native event stream (no per-tool blocking yet)
+3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live. For Codex / Aider / OpenCode / Gemini tasks: emits the agent's native event stream (no per-tool blocking yet)
 4. On completion, hands you a **Final report**: files changed with `+/-` lines, trust score per file, test pass/fail, token usage
 
 Claude Code tool calls are logged to `~/.codehere/audit/hook-events.jsonl`; spawned-task lifecycle (any adapter) is logged to `~/.codehere/sessions.jsonl`. Open-source MIT. Node 20+.
@@ -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
@@ -138,7 +195,7 @@ For depth beyond this README:
 
 - **Node.js 20+** (pinned in `.nvmrc` and `engines.node`)
 - **macOS or Linux** · Windows via WSL works for development; native Windows is on the v0.4 roadmap
-- **Optional but recommended:** at least one supported agent (Claude Code, Codex, Aider, or OpenCode) installed before running `codehere start`
+- **Optional but recommended:** at least one supported agent (Claude Code, Codex, Aider, OpenCode, or Gemini) installed before running `codehere start`
 
 ## License
 

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')
+    .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')

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,7 @@ export function spawnClaudeCode(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'claude-code',
+        memoryInjection: injected.record,
         get status() {
             return statusValue;
         },

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,