@zuzuucodes/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harshit Krishna Choudhary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# zuzuu
+
+[![ci](https://github.com/h1902y/zuzuu/actions/workflows/ci.yml/badge.svg)](https://github.com/h1902y/zuzuu/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@zuzuucodes/cli)](https://www.npmjs.com/package/@zuzuucodes/cli) [![node](https://img.shields.io/node/v/@zuzuucodes/cli)](package.json) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Give the coding agent you already run an evolving Memory, Knowledge, Actions, and Guardrails — grown from how you actually work.**
+
+Your host agent — Claude Code, Codex, Gemini CLI, OpenCode — supplies the *brain* (the reasoning loop + the model). zuzuu wraps the host you already pay for: it **serves** faculties to it, **observes** every session as an OpenTelemetry trace, and (the end-game) **evolves** the faculties from those traces — human-gated, across versioned generations. We never run a competing agent loop and never drive the host headlessly.
+
+> The CLI is `zuzuu` (package `zuzuu`, v1.0.0).
+
+> **Status (honest):** early build, moving fast. **Observe** works (5 real hosts, verified). **Serve** delivers the faculty home (`zuzuu init`), a session digest to every host, an **enforced guardrails gate** on all 5, and five faculties sharing one proposal/review spine. **Evolve** is now **wired and tested** — trace miners → a mechanical eval lens → human-gated `zuzuu review` → versioned **generations** (mint / rollback / drift-check) — but **not yet proven on a real graduation corpus** (the loop runs + passes hermetic tests; it hasn't yet improved an agent from real sessions end-to-end). Full design: [`docs/DESIGN.md`](docs/DESIGN.md).
+
+## What works today
+
+```bash
+npm install -g @zuzuucodes/cli   # zero dependencies — installs the `zuzuu` command
+
+# no coding agent yet? one command gives you a fully faculty-equipped one:
+zuzuu code        # scaffold the faculty home, install + wire OpenCode, launch it (capture + gate + grounding)
+
+# already run Claude Code / Gemini / Codex / OpenCode / pi? wrap the one you have:
+zuzuu init        # scaffold your project's agent home (agent/) — git-style, open
+zuzuu explain     # the 5 faculties + how graduation works (you're always in the loop)
+zuzuu inbox       # what's pending your approval · zuzuu review to approve/reject
+zuzuu capture     # turn your latest agent session into an OpenTelemetry trace
+zuzuu trace --last
+zuzuu enable [--host gemini-cli|codex|opencode|pi]   # live capture + the guardrails gate
+zuzuu doctor      # health + lost-session reconciliation
+```
+
+`zuzuu code` is the **bundled-host** path (Stage 2): it detects OpenCode (installs it on first run, with your OK — never an npm dependency, the zero-dep policy holds), wires the zuzuu plugin, and launches the real `opencode` — we configure + launch, never fork or drive it.
+
+| | Claude Code | Gemini CLI | Codex | OpenCode | pi |
+|---|---|---|---|---|---|
+| post-hoc capture | ✅ rich | ✅ thin | ✅ rich | ✅ rich | ✅ rich |
+| live capture | ✅ hooks | ✅ hooks | ✅ hooks¹ | ✅ plugin | ✅ extension |
+| guardrails gate | ✅ PreToolUse | ✅ BeforeTool | ✅ PreToolUse¹ | ✅ tool.execute.before | ✅ tool_call |
+
+¹ **Codex is interactive-only** — `codex exec` (headless) fires no hooks (verified, v0.138.0), so live capture + gate work when you run Codex interactively; headless Codex still gets post-hoc `zuzuu capture`.
+
+All five verified against **real sessions** — never fixtures; every host's live capture + gate was wired from **real captured hook payloads** and dogfooded end-to-end ([`experiments/LOG.md`](experiments/LOG.md) exp-11 Gemini/Codex, exp-12 OpenCode/pi). Gate semantics are host-honest: deny hard-blocks everywhere; `ask` maps to a native prompt on Claude, defers to the host elsewhere.
+
+**Prerequisites:** Node ≥ 22 — that's it. You need at least one supported agent you've already used, so a session exists to capture. (Hacking on zuzuu itself? `git clone https://github.com/h1902y/zuzuu && cd zuzuu && npm link`.)
+
+**`zuzuu init`** behaves like `git init`: empty dir → scaffolds the agent home + `AGENTS.md`/`CLAUDE.md`; existing project → adds `agent/` and injects a small delimiter-marked block into your existing instruction files (your text is never touched); already initialized → restores missing pieces only. The home is **open and self-explaining** — a visible `agent/` dir you can read and version in git: `agent/README.md` (the explainer) · `knowledge/` (verified facts) · `memory/` (curated episodes) · `actions/` (runbooks) · `instructions/` (steering) · `guardrails/` (enforced rules), plus `generations/` (your checkpoints). Machine internals are dot-prefixed + git-ignored (`agent/.traces/`, `agent/.live/`).
+
+**Live capture** (`zuzuu enable`) is invisible by design: a minimal lifecycle hook set (Claude Code, Gemini CLI, Codex), a bus plugin (OpenCode), or an extension (pi) — each wrapped so it **always exits 0 / fails open — it can never break your agent**. The same hook carries the guardrails gate, applied in each host's own idiom (Claude/Codex `hookSpecificOutput`, Gemini `{decision:"deny"}`, OpenCode throws from `tool.execute.before`, pi returns `{block:true}` from `tool_call`). Most hosts emit no clean end-signal when a terminal is killed, so `zuzuu doctor` *reconciles* lost sessions afterward from the transcript still on disk (nothing lost).
+
+**Where your data lives:** transcripts are read **read-only**; output is git-native in your repo — `agent/sessions.json` (small tracked index, each session linked to a commit) + `agent/.traces/*.otlp.jsonl` (local, git-ignored). **Nothing is uploaded**; no raw tool input/output on the trace (byte sizes only).
+
+**Verify / troubleshoot:** `npm test` (hermetic) · `npm run playground` (⏭️ skip = that host isn't on *your* machine, not a failure) · `zuzuu doctor` (env + session health). "No host detected" → use a supported agent once in the repo, then retry.
+
+## The idea in one diagram
+
+```
+   the host agent (yours)          zuzuu
+  ┌─────────────────────┐     ┌──────────────────────────────┐
+  │ Cognition · Model · │ ◄── │ SERVE   faculties:           │
+  │ Workspace           │     │   knowledge · memory ·       │
+  │  (we never drive)   │     │   actions · instructions ·   │
+  │                     │     │   guardrails (enforced)      │
+  └──────────┬──────────┘     ├──────────────────────────────┤
+             │ sessions       │ OBSERVE traces (OTel,        │
+             └──────────────► │         git-native)          │
+                              ├──────────────────────────────┤
+                              │ EVOLVE  eval → propose →     │
+                              │         human gate → new     │
+                              │         generation  [design] │
+                              └──────────────────────────────┘
+```
+
+**Five faculties**, each mapping onto a cognitive system — **Knowledge** (semantic: what's true), **Memory** (episodic: what happened), **Actions** (procedural: how to do things), **Instructions** (directive: who the agent is), **Guardrails** (protective: what it must not do — *enforced* on tool calls, fail-open). They improve across **versioned generations**, proposals mined from traces, **always human-approved**. That loop is the product; everything here is a step toward it.
+
+## Repo map
+
+| Path | What |
+|---|---|
+| [`zuzuu/`](zuzuu/) + `bin/zuzuu.mjs` | the CLI — capture, live lifecycle, faculty home (product surface) |
+| [`experiments/`](experiments/) | spike code + [`LOG.md`](experiments/LOG.md) — the build journal (hypothesis → real-data proof → conclusions per experiment) |
+| [`app/`](app/) | the durable application skeleton (be / run / evolve) — proven code harvests here |
+| [`tests/`](tests/) | hermetic unit + regression (`npm test`) + real-data smoke playgrounds (`npm run playground`) |
+| [`docs/`](docs/) | [`DESIGN.md`](docs/DESIGN.md) (the canon) + [`inspiration/`](docs/inspiration/) (the research shelf: 100-project survey + 5 audits) |
+
+## How this is built (the method)
+
+**Experiment → prove on real data → conclude → harvest.** Every capability starts as a numbered experiment with a hypothesis; it must be verified against *real* sessions/wire data (never invented fixtures) before it counts; lessons land in the experiment’s Conclusions section; proven parts graduate into `app/`. Built in public — day-by-day on X ([@h1902y](https://x.com/h1902y)).
+
+## License & status
+
+Personal project, early and changing daily. Issues/ideas welcome.

package/bin/zuzuu.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// zuzuu — the agent-faculty CLI (formerly zuzuu / motors & sensors). Verb-first, entire.io-style; zero deps, no build.
+//
+//   zuzuu status                 detected hosts + recorded sessions
+//   zuzuu capture [--host h]      capture a session → git-native trace + index entry
+//   zuzuu trace [--last | FILE]   print a captured trace's span tree
+//   zuzuu doctor                  environment + session health
+//   zuzuu version | help
+//
+// Phase 1: post-hoc transcript capture. Phase 2 (planned): `zuzuu enable` installs
+// background hooks for invisible live capture across the agent session lifecycle.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { init } from '../zuzuu/commands/init.mjs';
+import { status } from '../zuzuu/commands/status.mjs';
+import { capture } from '../zuzuu/commands/capture.mjs';
+import { trace } from '../zuzuu/commands/trace.mjs';
+import { doctor } from '../zuzuu/commands/doctor.mjs';
+import { enable, disable } from '../zuzuu/commands/enable.mjs';
+import { runHook } from '../zuzuu/commands/hook.mjs';
+import { remember, recall, knowledge } from '../zuzuu/commands/knowledge.mjs';
+import { review, proposals } from '../zuzuu/commands/review.mjs';
+import { distill } from '../zuzuu/commands/distill.mjs';
+import { digest } from '../zuzuu/commands/digest.mjs';
+import { act } from '../zuzuu/commands/act.mjs';
+import { migrate } from '../zuzuu/commands/migrate.mjs';
+import { generation } from '../zuzuu/commands/generation.mjs';
+import { evalCmd } from '../zuzuu/commands/eval.mjs';
+import { code } from '../zuzuu/commands/code.mjs';
+import { explain } from '../zuzuu/commands/explain.mjs';
+import { inbox } from '../zuzuu/commands/inbox.mjs';
+
+function parseArgs(argv) {
+  const a = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--') { a['--'] = argv.slice(i + 1); break; } // everything after `--` is passthrough
+    else if (t === '--last') a.last = true;
+    else if (t.startsWith('--')) {
+      const key = t.slice(2);
+      const val = argv[i + 1]?.startsWith('--') || argv[i + 1] === undefined ? true : argv[++i];
+      a[key] = key in a ? [].concat(a[key], val) : val; // repeated flag → array
+    }
+    else a._.push(t);
+  }
+  return a;
+}
+
+function version() {
+  const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+  console.log(`zuzuu ${pkg.version}`);
+}
+
+function help() {
+  console.log(`zuzuu — evolving faculties for the coding agent you already run
+
+usage: zuzuu <command> [options]
+
+  code [dir]                launch OpenCode as the bundled default host (faculty home + capture + gate + digest)
+  init                      scaffold the faculty home (agent/) — git-style, idempotent
+  status                    detected hosts + recorded sessions
+  capture [--host NAME]     capture a session → agent/.traces + agent/sessions.json
+          [--session ID] [--file PATH]
+  trace [--last | FILE]     print a captured trace's span tree
+  remember "fact" [--type t] [--attr k=v] [--rel type=target]
+                            add a knowledge item (you are the gate)
+  recall "query" [--type t] [--attr k=v] [--related-to id] [--semantic]
+                            search knowledge: lexical · graph · semantic
+  knowledge reindex|audit   rebuild the search index · check registry/items health
+  digest [--json] [--budget N]
+                            print the session-start grounding brief
+  act [list|show <slug>|new <slug>|schema <slug>]
+                            the Actions faculty — runbooks + runnable scripts
+  act <slug> [--args JSON]  run a script action
+  act propose <slug>        scaffold a proposed action → actions/inbox/ (for review)
+  act inbox|approve <slug>|reject <slug>
+                            the actions gate (or use \`zuzuu review\`)
+  distill [--all|--session ID]
+                            mine real sessions → knowledge proposals (default: last)
+  inbox                     what's pending your approval, per faculty
+  review                    walk pending actions + knowledge proposals (y/n/e/s/q)
+  proposals list|show|approve|reject <id>
+                            the same gate, non-interactive
+  generation [list|show <id>|mint|rollback <id>]
+                            pin/list/show/roll back faculty generations (lockfiles)
+  enable                    background hooks: invisible live capture + guardrails gate
+  disable                   remove the background hooks
+  eval [--faculty f]        rank pending proposals by eval score, highest first
+  migrate                   one-time migrator: rewrite legacy candidate/er proposals to new shape
+  doctor                    environment + session health (reconciles lost sessions)
+  explain [topic]           the 5 faculties + how graduation works
+  version                   print version
+  help                      this message
+
+\`zuzuu capture\` works post-hoc on existing transcripts. \`zuzuu enable\` turns on
+live, invisible capture across the session lifecycle — see the README.`);
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+const args = parseArgs(rest);
+
+switch (cmd) {
+  case 'code': process.exit(code(args)); break;
+  case 'init': init(args); break;
+  case 'remember': remember(args); break;
+  case 'recall': await recall(args); break;
+  case 'knowledge': await knowledge(args); break;
+  case 'digest': digest(args); break;
+  case 'act': act(args); break;
+  case 'distill': distill(args); break;
+  case 'inbox': inbox(args); break;
+  case 'review': await review(args); break;
+  case 'proposals': proposals(args); break;
+  case 'status': status(args); break;
+  case 'capture': capture(args); break;
+  case 'trace': trace(args); break;
+  case 'enable': enable(args); break;
+  case 'disable': disable(args); break;
+  case 'hook': runHook(args._[0], { host: args.host, session: args.session }); break;
+  case 'eval': evalCmd(args); break;
+  case 'migrate': migrate(args); break;
+  case 'generation': generation(args); break;
+  case 'doctor': await doctor(); break;
+  case 'explain': explain(args); break;
+  case 'version': case '--version': case '-v': version(); break;
+  case undefined: case 'help': case '--help': case '-h': help(); break;
+  default:
+    console.error(`unknown command: ${cmd}\n`);
+    help();
+    process.exit(1);
+}

package/experiments/experiment-1-trace-capture/adapters/claude-code.mjs

@@ -0,0 +1,220 @@
+// Claude Code adapter — parses ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl.
+//
+// Richest host we have: the transcript carries tool_use blocks (stable `toolu_…`
+// ids) paired to tool_result blocks (`tool_use_id` + `is_error`), each entry
+// timestamped. So we build a full SESSION -> TURN -> TOOL_CALL tree with real
+// durations and OK/ERROR status. No hooks, no live process — pure file parsing.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { event, trace, EventKind, Status } from '../core/event.mjs';
+
+const require = createRequire(import.meta.url);
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+// Claude encodes the project's cwd into the dir name by replacing non-alphanumerics with '-'.
+const encodeCwd = (cwd) => cwd.replace(/[^A-Za-z0-9]/g, '-');
+
+const ms = (iso) => (iso ? Date.parse(iso) : NaN);
+
+function readJsonl(file) {
+  return readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/** Extract plain prompt text from a user message.content (string | block array). */
+function promptText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const txt = content
+      .filter((b) => b.type === 'text')
+      .map((b) => b.text || '')
+      .join(' ');
+    return txt;
+  }
+  return '';
+}
+
+const clean = (s) => s.replace(/\s+/g, ' ').trim();
+const truncate = (s, n) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+
+export const claudeCode = {
+  name: 'claude-code',
+
+  detect() {
+    return existsSync(PROJECTS_DIR);
+  },
+
+  // Cross-host distill: delegate to the canonical Claude signal extractor.
+  // Lazy import avoids an import-time cycle (distill.mjs imports this adapter);
+  // mineTranscript is only called at runtime, so the cycle is harmless.
+  mineSignals(ref) {
+    try {
+      const file = typeof ref === 'string' ? ref : ref.ref;
+      // eslint-disable-next-line global-require
+      const { mineTranscript } = require('../../../zuzuu/knowledge/distill.mjs');
+      const { sessionId, ...sig } = mineTranscript(file);
+      return sig;
+    } catch {
+      return { commands: [], files: [], failures: [], sequences: [], correctionTurns: [], destructiveFailures: [] };
+    }
+  },
+
+  listSessions(opts = {}) {
+    const cwd = opts.cwd || process.cwd();
+    const dirs = opts.project
+      ? [opts.project]
+      : [encodeCwd(cwd)].filter((d) => existsSync(join(PROJECTS_DIR, d)));
+    // Fallback: if this project's dir isn't present, scan every project.
+    const roots = dirs.length ? dirs : (existsSync(PROJECTS_DIR) ? readdirSync(PROJECTS_DIR) : []);
+    const out = [];
+    for (const d of roots) {
+      const dir = join(PROJECTS_DIR, d);
+      if (!existsSync(dir)) continue;
+      for (const f of readdirSync(dir)) {
+        if (!f.endsWith('.jsonl')) continue;
+        const path = join(dir, f);
+        out.push({ sessionId: f.replace(/\.jsonl$/, ''), label: d, ref: path, mtime: statSync(path).mtimeMs });
+      }
+    }
+    return out.sort((a, b) => b.mtime - a.mtime);
+  },
+
+  parse(ref) {
+    const file = typeof ref === 'string' ? ref : ref.ref;
+    const rows = readJsonl(file);
+
+    let sessionId = '';
+    const session = { startMs: Infinity, endMs: -Infinity, model: '', version: '', cwd: '', gitBranch: '' };
+
+    // Pass 1: index tool_result end-times/status/size by tool_use_id.
+    const results = new Map();
+    for (const r of rows) {
+      const c = r.message?.content;
+      if (!Array.isArray(c)) continue;
+      for (const b of c) {
+        if (b.type !== 'tool_result') continue;
+        const body = typeof b.content === 'string' ? b.content : JSON.stringify(b.content ?? '');
+        results.set(b.tool_use_id, { endMs: ms(r.timestamp), isError: !!b.is_error, bytes: body.length });
+      }
+    }
+
+    // Pass 2: walk in order, tracking the current turn; emit turn + tool events.
+    const events = [];
+    const seenTurns = new Set();
+    const turnEnd = new Map(); // turnRefId -> latest child end ms
+    let currentTurn = null;
+
+    for (const r of rows) {
+      if (r.sessionId) sessionId ||= r.sessionId;
+      const t = ms(r.timestamp);
+      if (Number.isFinite(t)) {
+        session.startMs = Math.min(session.startMs, t);
+        session.endMs = Math.max(session.endMs, t);
+      }
+      if (r.cwd) session.cwd ||= r.cwd;
+      if (r.gitBranch) session.gitBranch ||= r.gitBranch;
+      if (r.version) session.version ||= r.version;
+      if (r.message?.model) session.model ||= r.message.model;
+
+      const role = r.message?.role;
+      const content = r.message?.content;
+
+      // A real user turn: role=user, has text/string content (not a tool_result), not meta.
+      if (r.type === 'user' && role === 'user' && !r.isMeta && Number.isFinite(t)) {
+        const isToolResult = Array.isArray(content) && content.some((b) => b.type === 'tool_result');
+        if (!isToolResult) {
+          const refId = r.promptId || r.uuid;
+          if (refId && !seenTurns.has(refId)) {
+            seenTurns.add(refId);
+            const text = clean(promptText(content));
+            currentTurn = refId;
+            events.push(
+              event({
+                kind: EventKind.TURN,
+                refId,
+                parentRefId: sessionId || 'session',
+                name: 'turn: ' + (truncate(text, 60) || '(empty)'),
+                startMs: t,
+                endMs: t,
+                attributes: { 'turn.prompt.bytes': text.length },
+              }),
+            );
+          }
+        }
+      }
+
+      // Tool calls: assistant content with tool_use blocks.
+      if (r.type === 'assistant' && Array.isArray(content)) {
+        for (const b of content) {
+          if (b.type !== 'tool_use') continue;
+          const res = results.get(b.id) || {};
+          const startMs = Number.isFinite(t) ? t : res.endMs ?? session.startMs;
+          const endMs = Number.isFinite(res.endMs) ? res.endMs : startMs;
+          const input = typeof b.input === 'string' ? b.input : JSON.stringify(b.input ?? {});
+          const parent = currentTurn || sessionId || 'session';
+          events.push(
+            event({
+              kind: EventKind.TOOL_CALL,
+              refId: b.id,
+              parentRefId: parent,
+              name: b.name || 'tool',
+              startMs,
+              endMs,
+              status: res.isError ? Status.ERROR : Status.OK,
+              attributes: {
+                'gen_ai.operation.name': 'execute_tool',
+                'gen_ai.tool.name': b.name || '',
+                'host.tool.name': b.name || '',
+                'tool.input.bytes': input.length, // size only — raw input is not put on the trace
+                'tool.result.bytes': res.bytes ?? 0,
+              },
+            }),
+          );
+          turnEnd.set(parent, Math.max(turnEnd.get(parent) ?? 0, endMs));
+        }
+      }
+    }
+
+    sessionId ||= file.split('/').pop().replace(/\.jsonl$/, '');
+    if (!Number.isFinite(session.startMs)) session.startMs = 0;
+    if (!Number.isFinite(session.endMs)) session.endMs = session.startMs;
+
+    // Extend each turn to cover its tool children.
+    for (const e of events) {
+      if (e.kind === EventKind.TURN && turnEnd.has(e.refId)) e.endMs = Math.max(e.endMs, turnEnd.get(e.refId));
+    }
+
+    // The SESSION root.
+    events.unshift(
+      event({
+        kind: EventKind.SESSION,
+        refId: sessionId,
+        parentRefId: null,
+        name: `session ${sessionId.slice(0, 8)} (claude-code)`,
+        startMs: session.startMs,
+        endMs: session.endMs,
+        attributes: {
+          'host.name': 'claude-code',
+          'host.session.model': session.model,
+          'host.session.version': session.version,
+          'host.cwd': session.cwd,
+          'host.git.branch': session.gitBranch,
+        },
+      }),
+    );
+
+    return trace({ host: 'claude-code', sessionId, title: session.cwd, events });
+  },
+};

package/experiments/experiment-1-trace-capture/adapters/codex.mjs

@@ -0,0 +1,201 @@
+// Codex CLI adapter — parses ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl.
+//
+// Built against REAL wire data (a captured `codex exec` session), not docs —
+// the docs warn the serialization differs from source. Confirmed shapes:
+//   { timestamp, type, payload }  per line
+//   type "session_meta"   → payload { id, cwd, ... }            (the session id)
+//   type "turn_context"   → payload { model, cwd }
+//   type "event_msg"      → payload { type: task_started | user_message | agent_message | token_count | task_complete, message? }
+//   type "response_item"  → payload { type: "message"|"function_call"|"function_call_output", ... }
+//        message          → { role: developer|user|assistant, content:[{type,text}] }
+//        function_call    → { name, call_id, arguments(JSON string) }
+//        function_call_output → { call_id, output }  (linked FLAT by call_id)
+//
+// Turns come from event_msg/user_message (clean prompt text — avoids the injected
+// <environment_context>/developer messages). Tool spans pair function_call ↔
+// function_call_output by call_id, giving real durations. Rich, like Claude.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import { event, trace, EventKind, Status } from '../core/event.mjs';
+import { assembleSignals, emptySignals } from './signals.mjs';
+
+const SESSIONS_DIR = join(homedir(), '.codex', 'sessions');
+
+// Codex shell tool (real-wire): function_call name "exec_command", arguments is a
+// JSON string {cmd:"…"} (older/other builds use "shell" with {command:[…]}). The
+// paired function_call_output carries no error flag — but its text begins with
+// "Process exited with code N", so N≠0 ⇒ failed.
+const CODEX_SHELL = new Set(['exec_command', 'shell', 'local_shell', 'bash']);
+function codexCmdText(args) {
+  const a = typeof args === 'string' ? (() => { try { return JSON.parse(args); } catch { return {}; } })() : args ?? {};
+  if (typeof a.cmd === 'string') return a.cmd;
+  if (typeof a.command === 'string') return a.command;
+  if (Array.isArray(a.command)) return a.command.join(' ');
+  return '';
+}
+const codexFailed = (output) => /Process exited with code\s+([0-9]+)/i.test(String(output || '')) && !/Process exited with code\s+0\b/i.test(String(output || ''));
+const ms = (iso) => (iso ? Date.parse(iso) : NaN);
+const clean = (s) => String(s).replace(/\s+/g, ' ').trim();
+const truncate = (s, n) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+
+function readJsonl(file) {
+  return readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export const codex = {
+  name: 'codex',
+
+  detect() {
+    return existsSync(SESSIONS_DIR);
+  },
+
+  listSessions() {
+    if (!existsSync(SESSIONS_DIR)) return [];
+    return readdirSync(SESSIONS_DIR, { recursive: true })
+      .filter((f) => typeof f === 'string' && /rollout-.*\.jsonl$/.test(f))
+      .map((f) => {
+        const path = join(SESSIONS_DIR, f);
+        const m = f.match(/rollout-.*-([0-9a-f-]{36})\.jsonl$/i);
+        return { sessionId: m ? m[1] : f, ref: path, label: 'codex', mtime: statSync(path).mtimeMs };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+  },
+
+  // Cross-host distill: shell command TEXT + failed flag from the raw rollout.
+  mineSignals(ref) {
+    try {
+      const file = typeof ref === 'string' ? ref : ref.ref;
+      const rows = readJsonl(file);
+      const outputs = new Map(); // call_id -> output text
+      for (const r of rows) {
+        const p = r.payload || {};
+        if (r.type === 'response_item' && p.type === 'function_call_output') outputs.set(p.call_id, p.output);
+      }
+      const shellCalls = [];
+      for (const r of rows) {
+        const p = r.payload || {};
+        if (r.type === 'response_item' && p.type === 'function_call' && CODEX_SHELL.has(p.name)) {
+          const cmd = codexCmdText(p.arguments);
+          if (cmd) shellCalls.push({ cmd, failed: codexFailed(outputs.get(p.call_id)), tool: p.name });
+        }
+      }
+      return assembleSignals(shellCalls);
+    } catch {
+      return emptySignals();
+    }
+  },
+
+  parse(ref) {
+    const file = typeof ref === 'string' ? ref : ref.ref;
+    const rows = readJsonl(file);
+
+    let sessionId = '';
+    const meta = { startMs: Infinity, endMs: -Infinity, model: '', cwd: '' };
+
+    // Pass 1: index function_call_output by call_id (end time + size).
+    const results = new Map();
+    for (const r of rows) {
+      const p = r.payload || {};
+      if (r.type === 'response_item' && p.type === 'function_call_output') {
+        const out = typeof p.output === 'string' ? p.output : JSON.stringify(p.output ?? '');
+        results.set(p.call_id, { endMs: ms(r.timestamp), bytes: out.length });
+      }
+    }
+
+    // Pass 2: walk in order; turns from user_message, tools from function_call.
+    const events = [];
+    const turnEnd = new Map();
+    let currentTurn = null;
+    let turnIdx = 0;
+
+    for (const r of rows) {
+      const p = r.payload || {};
+      const t = ms(r.timestamp);
+      if (Number.isFinite(t)) {
+        meta.startMs = Math.min(meta.startMs, t);
+        meta.endMs = Math.max(meta.endMs, t);
+      }
+      if (r.type === 'session_meta') sessionId ||= p.id || '';
+      if (r.type === 'session_meta' || r.type === 'turn_context') meta.cwd ||= p.cwd || '';
+      if (r.type === 'turn_context') meta.model ||= p.model || '';
+
+      if (r.type === 'event_msg' && p.type === 'user_message') {
+        const text = clean(p.message || '');
+        const refId = `${sessionId || 'codex'}:turn:${turnIdx++}`;
+        currentTurn = refId;
+        events.push(
+          event({
+            kind: EventKind.TURN,
+            refId,
+            parentRefId: sessionId || 'session',
+            name: 'turn: ' + (truncate(text, 60) || '(empty)'),
+            startMs: Number.isFinite(t) ? t : meta.startMs,
+            endMs: Number.isFinite(t) ? t : meta.startMs,
+            attributes: { 'turn.prompt.bytes': text.length },
+          }),
+        );
+      }
+
+      if (r.type === 'response_item' && p.type === 'function_call') {
+        const res = results.get(p.call_id) || {};
+        const startMs = Number.isFinite(t) ? t : meta.startMs;
+        const endMs = Number.isFinite(res.endMs) ? res.endMs : startMs;
+        const args = typeof p.arguments === 'string' ? p.arguments : JSON.stringify(p.arguments ?? {});
+        const parent = currentTurn || sessionId || 'session';
+        events.push(
+          event({
+            kind: EventKind.TOOL_CALL,
+            refId: p.call_id || `${sessionId}:call:${events.length}`,
+            parentRefId: parent,
+            name: p.name || 'tool',
+            startMs,
+            endMs,
+            status: Status.OK, // Codex output carries no explicit error flag (see CONCLUSIONS)
+            attributes: {
+              'gen_ai.operation.name': 'execute_tool',
+              'gen_ai.tool.name': p.name || '',
+              'host.tool.name': p.name || '',
+              'tool.input.bytes': args.length,
+              'tool.result.bytes': res.bytes ?? 0,
+            },
+          }),
+        );
+        turnEnd.set(parent, Math.max(turnEnd.get(parent) ?? 0, endMs));
+      }
+    }
+
+    sessionId ||= (file.match(/([0-9a-f-]{36})\.jsonl$/i) || [])[1] || file.split('/').pop();
+    if (!Number.isFinite(meta.startMs)) meta.startMs = 0;
+    if (!Number.isFinite(meta.endMs)) meta.endMs = meta.startMs;
+
+    for (const e of events) {
+      if (e.kind === EventKind.TURN && turnEnd.has(e.refId)) e.endMs = Math.max(e.endMs, turnEnd.get(e.refId));
+    }
+
+    events.unshift(
+      event({
+        kind: EventKind.SESSION,
+        refId: sessionId,
+        parentRefId: null,
+        name: `session ${String(sessionId).slice(0, 8)} (codex)`,
+        startMs: meta.startMs,
+        endMs: meta.endMs,
+        attributes: { 'host.name': 'codex', 'host.session.model': meta.model, 'host.cwd': meta.cwd },
+      }),
+    );
+
+    return trace({ host: 'codex', sessionId: String(sessionId), title: meta.cwd, events });
+  },
+};