@zuzuucodes/cli 1.0.0

package/zuzuu/miners/instructions.mjs

@@ -0,0 +1,152 @@
+// zuzuu/miners/instructions.mjs
+// Instructions miner (WS5-T4) — detect recurring corrective user turns across
+// sessions and propose steering-amendment blocks for the Instructions faculty.
+//
+// Corrective turns are captured by mineTranscript as:
+//   correctionTurns: [{ text }]  — user turns following an assistant tool action
+//   that contain corrective lexicon (e.g. "always", "never", "don't", etc.)
+//
+// Shape: { faculty:'instructions', aggregate(sessions, opts), propose(agentDir, aggregated) }
+// Self-registers on import.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { makeProposal, writeProposal, listProposals } from '../faculty/proposal.mjs';
+import { register } from './registry.mjs';
+
+// ---------------------------------------------------------------------------
+// helpers
+
+/**
+ * Normalise a correction text for grouping:
+ * lowercase, collapse whitespace, truncate to 200 chars.
+ *
+ * v1 grouping: near-identical normalised text (exact key match). Simple and
+ * deterministic; a fuzzy grouper can be earned later.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function normText(text) {
+  return String(text).toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+
+/**
+ * Derive a proposal id fragment from a normalised text key.
+ * Keep it stable, short, and filesystem-safe.
+ */
+function instrId(normKey) {
+  // Use a slugified version of the first 60 chars of the normalised text,
+  // prefixed to make collisions with other faculties impossible.
+  const slug = normKey.slice(0, 60).replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50) || 'instr';
+  return 'instr-' + slug;
+}
+
+// ---------------------------------------------------------------------------
+// aggregate
+
+/**
+ * Group correctionTurns from mined sessions; propose when a similar correction
+ * recurs across ≥minSessions (default 2) distinct sessions.
+ *
+ * @param {Array<{sessionId:string, correctionTurns:{text:string}[]}>} sessions
+ * @param {object} opts
+ * @param {number} [opts.minSessions=2] min distinct sessions with the same normalised correction
+ * @returns {Array<{payload:{text:string}, evidence:{occurrences:number, sessions:number}}>}
+ */
+export function aggregate(sessions, { minSessions = 2 } = {}) {
+  // normalised text → { count, sessions: Set<sessionId>, rawText: string }
+  const stats = new Map();
+
+  for (const s of sessions) {
+    if (!Array.isArray(s.correctionTurns)) continue;
+    // Track distinct normalised texts per session to avoid double-counting
+    // the same session for the same correction text.
+    const seenInSession = new Set();
+    for (const { text } of s.correctionTurns) {
+      const key = normText(text);
+      if (!key) continue;
+      const st = stats.get(key) ?? { count: 0, sessions: new Set(), rawText: text };
+      st.count++;
+      st.sessions.add(s.sessionId);
+      seenInSession.add(key);
+      stats.set(key, st);
+    }
+  }
+
+  const candidates = [];
+  for (const [, st] of stats) {
+    if (st.sessions.size < minSessions) continue;
+
+    // Phrase the raw correction as an instruction for the steering amendment.
+    // The corrective turn text already reads like user guidance; use it directly
+    // (trimmed to 500 chars to match mineTranscript's cap).
+    const amendmentText = st.rawText.slice(0, 500).trim();
+    const id = instrId(normText(amendmentText));
+
+    candidates.push({
+      payload: { id, text: amendmentText },
+      evidence: { occurrences: st.count, sessions: st.sessions.size },
+    });
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// propose
+
+/**
+ * Write an instructions proposal into agent/instructions/proposals/ for each
+ * candidate.
+ *
+ * Idempotent:
+ *   - skips if an instructions proposal with the same derived id already exists
+ *   - skips if the text is already present in project.md
+ *
+ * @param {string} agentDir
+ * @param {ReturnType<typeof aggregate>} aggregated
+ * @returns {number} count of new proposals written
+ */
+export function propose(agentDir, aggregated) {
+  // Collect ids of existing pending proposals for this faculty.
+  const existing = listProposals(agentDir, 'instructions');
+  const existingIds = new Set(existing.map((p) => p.payload?.id).filter(Boolean));
+
+  // Read project.md to skip amendments already applied.
+  const projectMdPath = join(agentDir, 'instructions', 'project.md');
+  const projectMdContent = existsSync(projectMdPath)
+    ? readFileSync(projectMdPath, 'utf8')
+    : '';
+
+  let count = 0;
+  for (const c of aggregated) {
+    const { payload, evidence } = c;
+
+    // Idempotent: skip if already proposed.
+    if (existingIds.has(payload.id)) continue;
+
+    // Idempotent: skip if text already present in project.md.
+    if (projectMdContent.includes(payload.text)) continue;
+
+    const proposal = makeProposal({
+      faculty: 'instructions',
+      kind: 'block',
+      source: 'distill',
+      payload,
+      evidence,
+    });
+
+    writeProposal(agentDir, proposal);
+    count++;
+  }
+
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// self-register
+
+export const miner = { faculty: 'instructions', aggregate, propose };
+
+register(miner);

package/zuzuu/miners/knowledge.mjs

@@ -0,0 +1,22 @@
+// Knowledge miner (WS5-T1) — the existing source-A distill path, wrapped as a
+// registry miner. NO behavior change: `aggregate` is the same function the
+// golden distill test asserts on; `propose` mirrors `distillSessions` (one
+// `createProposal` per aggregated candidate). Self-registers on import.
+
+import { aggregate } from '../knowledge/distill.mjs';
+import { createProposal } from '../knowledge/proposals.mjs';
+import { register } from './registry.mjs';
+
+/** File one knowledge proposal per aggregated candidate; return the count. */
+export function propose(agentDir, aggregated) {
+  for (const c of aggregated) {
+    createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence });
+  }
+  return aggregated.length;
+}
+
+export const miner = { faculty: 'knowledge', aggregate, propose };
+
+register(miner);
+
+export { aggregate };

package/zuzuu/miners/memory.mjs

@@ -0,0 +1,27 @@
+// zuzuu/miners/memory.mjs
+// Memory miner STUB (WS5-T4) — registered no-op; deferred this pass.
+//
+// WHAT IT WOULD MINE (when implemented):
+//   Completed-session episodes — a Run that reached `completed` status in
+//   agent/sessions.json — would be distilled into curated episode entries at
+//   agent/memory/entries/<id>.md. Each entry captures: what was attempted,
+//   key decisions made, outcome, and a set of durable learnings. The miner
+//   would emit `memory` proposals of kind 'episode' into
+//   agent/memory/proposals/ for human review via `zuzuu review`. Deferred until
+//   the Memory substrate (off-edge Postgres/Neon or local Markdown) is
+//   established and the session lifecycle state machine is stable enough to
+//   reliably produce `completed` runs with rich enough trace data to distill.
+//
+// Shape: { faculty:'memory', aggregate, propose, stub:true }
+// Self-registers on import (no-op).
+
+import { register } from './registry.mjs';
+
+export const miner = {
+  faculty: 'memory',
+  stub: true,
+  aggregate: () => [],
+  propose: () => 0,
+};
+
+register(miner);

package/zuzuu/miners/registry.mjs

@@ -0,0 +1,31 @@
+// Miner registry (WS5-T1) — the faculty-mining plugin table.
+//
+// Each miner is `{ faculty, aggregate(sessions, opts) -> candidates,
+// propose(agentDir, candidates) -> count }`. The `--all-faculties` distill driver
+// mines every transcript once into a shared `sessions` array, then runs each
+// registered miner's aggregate + propose. Miners self-register on import.
+
+const miners = [];
+
+/** Register a miner. Re-registering the same faculty replaces it (idempotent import). */
+export function register(miner) {
+  const i = miners.findIndex((m) => m.faculty === miner.faculty);
+  if (i >= 0) miners[i] = miner;
+  else miners.push(miner);
+  return miner;
+}
+
+/** All registered miners. */
+export function all() {
+  return miners.slice();
+}
+
+/** The miner for a faculty, or undefined. */
+export function get(faculty) {
+  return miners.find((m) => m.faculty === faculty);
+}
+
+/** Clear the registry — tests only. */
+export function reset() {
+  miners.length = 0;
+}

package/zuzuu/scaffold.mjs

@@ -0,0 +1,213 @@
+// The faculty-home scaffold — the layout contract for `zuzuu init`.
+//
+// Git-init discipline: idempotent and never destructive. plan() inspects what
+// exists; apply() creates ONLY what's missing — it never overwrites a file, so
+// user edits to any seeded file always survive a re-init.
+//
+// Layout = the five faculties (docs/DESIGN.md §3①, the 5+3 anatomy):
+//   agent/agent.json + knowledge/ memory/ actions/ instructions/ guardrails/
+// Guardrails became first-class (enforced via the PreToolUse gate) on 2026-06-10;
+// the old instructions/guardrails.md advisory seed left the layout (existing
+// projects keep theirs — no-clobber — but new scaffolds get the real faculty).
+
+import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { SEED_TYPES, SEED_ATTRIBUTES, SEED_RELATIONS } from './knowledge/registry.mjs';
+
+export const MANIFEST_VERSION = 3;
+
+const AGENT_README = `# agent/ — your coding agent's home, in the open
+
+This directory is your agent's evolving brain. Five **faculties** grow from how you
+actually work — and **nothing changes without your approval**.
+
+## The five faculties
+- **knowledge/** — what's TRUE (facts about this project)
+- **memory/** — what HAPPENED (curated episodes from past sessions)
+- **actions/** — how to DO things (runbooks the agent can call)
+- **instructions/** — who to BE (steering / project conventions)
+- **guardrails/** — what NOT to do (enforced rules, checked on every tool call)
+
+## How things graduate (you're in the loop)
+    a session runs  →  zuzuu mines candidates  →  inbox/  →  proposals/
+                                                              │  you decide
+                                                    zuzuu review  (y / n / edit)
+                                                              ▼
+                                          approved → the faculty + a new *generation*
+A **generation** is a pinned checkpoint of every faculty. Approving proposals mints
+one; \`zuzuu generation rollback <id>\` restores any earlier checkpoint.
+
+## Get in the loop
+- \`zuzuu inbox\`            — what's waiting for your approval
+- \`zuzuu review\`          — approve / reject, one at a time
+- \`zuzuu generation list\` — your checkpoints (· = active)
+- \`zuzuu explain\`         — this model, any time
+
+## What to ignore
+\`.traces/\`, \`.live/\`, and \`knowledge/.index.db\` are machine internals (git-ignored).
+Everything else here is yours to read, edit, and version in git.
+`;
+
+const KNOWLEDGE_README = `# knowledge/ — the Knowledge faculty (what's TRUE)
+
+Items in \`items/\` — one fact/entity per file: prose body + typed attributes +
+typed relations (registry-governed: \`registry/\`) + provenance. The derived
+search index (\`.index.db\`, git-ignored) gives lexical/graph/semantic recall:
+\`zuzuu recall\`. Candidates arrive in \`inbox/\` (from agents or \`zuzuu distill\`),
+become \`proposals/\`, and a human approves via \`zuzuu review\` — never silently.
+\`zuzuu remember\` writes directly (the human IS the gate). \`zuzuu knowledge audit\`
+checks health.
+`;
+
+const MEMORY_README = `# memory/ — episodic faculty (what HAPPENED)
+
+Curated recollections of past sessions, distilled from the observability traces (\`agent/.traces/\`).
+- **Who writes:** zuzuu (distillation — *not built yet*), human (curation). Raw traces stay in traces/ — this is the *curated* layer.
+- **Where:** one Markdown file per entry under \`entries/\`, named \`<id>.md\`.
+
+## Record schema (Markdown + YAML frontmatter)
+\`\`\`markdown
+---
+id: mem-2026-06-11-flaky-ci-retry      # mem-<YYYY-MM-DD>-<slug>, stable
+date: 2026-06-11                        # ISO date the episode occurred
+title: Flaky CI fixed by pinning node 22
+provenance:                            # links back to observability
+  sessions: [ses_abc123]               # ids that exist in agent/sessions.json
+  hosts: [claude-code]
+tags: [ci, flaky-test]                 # optional
+status: curated                        # curated (human) | proposed (reserved — future distiller)
+---
+## Attempted
+What was tried.
+## Resulted
+What happened (outcome / error / fix).
+## Remember next time
+The durable lesson.
+\`\`\`
+\`status: proposed\` and the distiller→review pipeline are **reserved** (not built this pass).
+`;
+
+const ACTIONS_README = `# actions/ — procedural faculty (how to DO things)
+
+Named, reusable procedures/skills for this project (scripts, runbooks, tool recipes).
+- **Who writes:** the human; later, zuzuu proposes crystallized actions mined from traces (human-approved).
+- **Contract:** one action per file; state what it does, inputs, and how to invoke it.
+- **Propose a reusable action**: \`zuzuu act propose <slug>\` scaffolds into \`actions/inbox/\` for review. A human approves via \`zuzuu review\` (or \`zuzuu act approve <slug>\`). Never write active actions directly from an agent.
+`;
+
+const INSTRUCTIONS_README = `# instructions/ — the Instructions faculty (directive: who the agent is)
+
+Cognition steering: identity, conventions, priorities — the project-level seed of
+the pinned system prompt. The host agent reads and follows this.
+- \`project.md\` — project-specific steering (what this is, conventions, priorities).
+- Hard *enforced* rules live in \`../guardrails/\` (a separate faculty), not here.
+`;
+
+const PROJECT_SEED = `# Project steering
+
+<!-- Fill in: what this project is, conventions, priorities. The host agent reads this. -->
+`;
+
+const GUARDRAILS_README = `# guardrails/ — the Guardrails faculty (enforced, not advisory)
+
+Declarative rules in \`rules.json\`, evaluated on every tool call by the zuzuu
+PreToolUse gate (installed by \`zuzuu enable\`). Severity wins: deny > ask > allow;
+no match → the host's normal permission flow. The engine FAILS OPEN — a
+guardrail bug can block nothing — and matched decisions are logged for the trace.
+
+Rule shape: \`{ id, action: deny|ask|allow, tool: "Bash"|"*", pattern: <regex
+over the tool input>, reason }\`. Edit, commit, done — rules are definitions,
+versioned in git like everything else.
+`;
+
+const RULES_SEED =
+  JSON.stringify(
+    {
+      version: 1,
+      rules: [
+        { id: 'no-root-wipe', action: 'deny', tool: 'Bash', pattern: 'rm\\s+-[a-z]*r[a-z]*\\s+/(\\s|$)', reason: 'destructive delete at filesystem root' },
+        { id: 'no-secret-reads', action: 'deny', tool: '*', pattern: '\\.env(\\.|\\b)|id_rsa|\\.pem\\b', reason: 'secret material should not enter the context' },
+        // \b.*\bpush, not push adjacent to git: a real session bypassed the
+        // adjacent form with `git -C /path push --force-with-lease` (exp-8).
+        { id: 'confirm-force-push', action: 'ask', tool: 'Bash', pattern: 'git\\b.*\\bpush\\b.*--force', reason: 'force-push rewrites shared history' },
+      ],
+    },
+    null,
+    2,
+  ) + '\n';
+
+/** The layout contract: dirs + seed files (relative to the project root). */
+export const LAYOUT = {
+  dirs: ['agent', 'agent/knowledge', 'agent/knowledge/registry', 'agent/knowledge/items', 'agent/knowledge/inbox', 'agent/knowledge/proposals', 'agent/memory', 'agent/memory/entries', 'agent/memory/inbox', 'agent/memory/proposals', 'agent/actions', 'agent/actions/inbox', 'agent/instructions', 'agent/instructions/inbox', 'agent/instructions/proposals', 'agent/guardrails', 'agent/guardrails/inbox', 'agent/guardrails/proposals', 'agent/generations', 'agent/generations/snapshots'],
+  files: {
+    'agent/README.md': AGENT_README,
+    'agent/knowledge/README.md': KNOWLEDGE_README,
+    'agent/memory/README.md': MEMORY_README,
+    'agent/actions/README.md': ACTIONS_README,
+    'agent/instructions/README.md': INSTRUCTIONS_README,
+    'agent/instructions/project.md': PROJECT_SEED,
+    'agent/guardrails/README.md': GUARDRAILS_README,
+    'agent/guardrails/rules.json': RULES_SEED,
+    'agent/knowledge/registry/types.json': JSON.stringify(SEED_TYPES, null, 2) + '\n',
+    'agent/knowledge/registry/attributes.json': JSON.stringify(SEED_ATTRIBUTES, null, 2) + '\n',
+    'agent/knowledge/registry/relations.json': JSON.stringify(SEED_RELATIONS, null, 2) + '\n',
+  },
+};
+
+/** Gitignore lines the project needs (trace blobs + liveness state stay local). */
+export const IGNORE_LINES = ['agent/.traces/', 'agent/.live/', 'agent/knowledge/.index.db', '.gemini/settings.json', '.codex/hooks.json', '.pi/extensions/zuzuu.ts'];
+
+export function manifest(initializedAt) {
+  return {
+    version: MANIFEST_VERSION,
+    initializedAt,
+    layout: ['knowledge', 'memory', 'actions', 'instructions', 'guardrails'],
+  };
+}
+
+/**
+ * Inspect the project: which layout pieces are missing?
+ * @returns {{dirs: string[], files: string[], manifestMissing: boolean}}
+ */
+export function planScaffold(cwd) {
+  const dirs = LAYOUT.dirs.filter((d) => !existsSync(join(cwd, d)));
+  const files = Object.keys(LAYOUT.files).filter((f) => !existsSync(join(cwd, f)));
+  const manifestMissing = !existsSync(join(cwd, 'agent', 'agent.json'));
+  return { dirs, files, manifestMissing };
+}
+
+/**
+ * Create ONLY the missing pieces (no-clobber). Returns what was created.
+ * @param {string} cwd
+ * @param {{now?: number}} opts  injectable clock for tests
+ */
+export function applyScaffold(cwd, { now = Date.now() } = {}) {
+  const plan = planScaffold(cwd);
+  for (const d of plan.dirs) mkdirSync(join(cwd, d), { recursive: true });
+  for (const f of plan.files) writeFileSync(join(cwd, f), LAYOUT.files[f]);
+  if (plan.manifestMissing) {
+    mkdirSync(join(cwd, 'agent'), { recursive: true });
+    writeFileSync(join(cwd, 'agent', 'agent.json'), JSON.stringify(manifest(new Date(now).toISOString()), null, 2) + '\n');
+  }
+  return plan;
+}
+
+/**
+ * Ensure the project .gitignore carries our ignore lines (append-only; creates
+ * the file if absent). Returns the lines actually added.
+ */
+export function ensureGitignore(cwd) {
+  const path = join(cwd, '.gitignore');
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const have = new Set(existing.split('\n').map((l) => l.trim()));
+  const missing = IGNORE_LINES.filter((l) => !have.has(l));
+  if (!missing.length) return [];
+  const block = (existing && !existing.endsWith('\n') ? '\n' : '') + '\n# zuzuu: local-only observability data\n' + missing.join('\n') + '\n';
+  writeFileSync(path, existing + block);
+  return missing;
+}
+
+/** Is there a zuzuu home here already? (the git-detect question) */
+export function homeExists(cwd) {
+  return existsSync(join(cwd, 'agent'));
+}

package/zuzuu/session.mjs

@@ -0,0 +1,72 @@
+// The Session primitive — the lifecycle model for an agent coding session.
+//
+// A Session is the unit motors&sensors tracks: it OPENS when an agent session
+// starts and CLOSES when it ends — cleanly (completed), or by being lost/killed
+// (abandoned/crashed, reconciled after the fact since a killed terminal sends no
+// signal). The state machine below is the contract for that lifecycle.
+//
+// Phase 1 (post-hoc transcript capture) records sessions as `captured` — a
+// lifecycle-unknown snapshot. Phase 2 (live hooks) drives the real transitions:
+// opening → active → completed | abandoned | crashed. The full machine is defined
+// now so the primitive is stable before live wiring lands.
+
+export const SessionState = Object.freeze({
+  OPENING: 'opening', // hook fired session-start; root span opened
+  ACTIVE: 'active', // turns/tools flowing
+  COMPLETED: 'completed', // clean end (Stop / explicit close)
+  ABANDONED: 'abandoned', // no activity past the liveness window; reconciled
+  CRASHED: 'crashed', // process/terminal died mid-session; reconciled
+  CAPTURED: 'captured', // Phase 1 post-hoc snapshot; lifecycle not tracked live
+});
+
+const TERMINAL = new Set([
+  SessionState.COMPLETED,
+  SessionState.ABANDONED,
+  SessionState.CRASHED,
+  SessionState.CAPTURED,
+]);
+
+// Legal live transitions (Phase 2 enforces these). CAPTURED is post-hoc, off-machine.
+const TRANSITIONS = {
+  [SessionState.OPENING]: [SessionState.ACTIVE, SessionState.CRASHED, SessionState.ABANDONED],
+  [SessionState.ACTIVE]: [SessionState.COMPLETED, SessionState.ABANDONED, SessionState.CRASHED],
+  [SessionState.COMPLETED]: [],
+  [SessionState.ABANDONED]: [],
+  [SessionState.CRASHED]: [],
+  [SessionState.CAPTURED]: [],
+};
+
+export const isTerminal = (state) => TERMINAL.has(state);
+export const canTransition = (from, to) => (TRANSITIONS[from] || []).includes(to);
+
+/** Apply a lifecycle transition, throwing on an illegal one. Returns a new record. */
+export function transition(session, to, at = session.endedAt) {
+  if (!canTransition(session.status, to)) {
+    throw new Error(`illegal session transition: ${session.status} -> ${to}`);
+  }
+  const endedAt = isTerminal(to) ? at : session.endedAt;
+  const durationMs = endedAt && session.startedAt ? Date.parse(endedAt) - Date.parse(session.startedAt) : session.durationMs;
+  return { ...session, status: to, endedAt, durationMs };
+}
+
+/**
+ * Build a Session record (the git-native index entry).
+ * @param {object} s
+ * @param {string} s.id            host session id
+ * @param {string} s.host          adapter name
+ * @param {string} [s.status]      SessionState; default CAPTURED (Phase 1)
+ * @param {string} s.startedAt     ISO
+ * @param {string} s.endedAt       ISO
+ * @param {string} s.traceId
+ * @param {string} s.traceRef      path to the OTLP blob (gitignored)
+ * @param {{commit:string|null,branch:string|null}} [s.git]
+ * @param {{turns:number,tools:number,errors:number}} [s.counts]
+ * @param {string|null} [s.generation]  active generation id at session open (WS3-T3)
+ */
+export function makeSession({ id, host, status = SessionState.CAPTURED, startedAt, endedAt, traceId, traceRef, git = { commit: null, branch: null }, counts = { turns: 0, tools: 0, errors: 0 }, generation = null }) {
+  if (!id) throw new Error('makeSession: id required');
+  if (!host) throw new Error('makeSession: host required');
+  if (!Object.values(SessionState).includes(status)) throw new Error(`makeSession: unknown status ${status}`);
+  const durationMs = startedAt && endedAt ? Date.parse(endedAt) - Date.parse(startedAt) : 0;
+  return { id: String(id), host, status, startedAt, endedAt, durationMs, traceId, traceRef, git, counts, generation };
+}

package/zuzuu/store.mjs

@@ -0,0 +1,104 @@
+// The git-native agent/ store (the visible faculty home).
+//
+// Layout (entire.io-style split — linkage in git, blobs out of the diff):
+//   agent/sessions.json          tracked   — the session index (small, diff-friendly,
+//                                            each entry links to a git commit)
+//   agent/.traces/<host>-<id>.otlp.jsonl   gitignored — the bulky OTLP blobs (dot-prefixed)
+//
+// Trace blobs are git-ignored in Phase 1; Phase 2 moves them to an orphan branch.
+
+import { join, relative, resolve, isAbsolute } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { writeNdjson } from '../experiments/experiment-1-trace-capture/core/otlp.mjs';
+
+const INDEX_VERSION = 1;
+
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/** Repo root via git, falling back to cwd. */
+export function repoRoot(cwd = process.cwd()) {
+  return git(['rev-parse', '--show-toplevel'], cwd) || cwd;
+}
+
+/** Resolve the faculty home: the visible `agent/`. The single chokepoint for the
+ *  whole CLI. */
+export function homeDir(root = repoRoot()) {
+  return join(root, 'agent');
+}
+
+/** Internal liveness dir (git-ignored, dot-prefixed) under the home. */
+export const liveDir = (agentDir) => join(agentDir, '.live');
+
+export function paths(cwd = process.cwd()) {
+  const root = repoRoot(cwd);
+  const dir = homeDir(root);
+  return { root, dir, index: join(dir, 'sessions.json'), tracesDir: join(dir, '.traces') };
+}
+
+/** Current commit + branch, or nulls if not a git repo. */
+export function gitInfo(cwd = process.cwd()) {
+  return { commit: git(['rev-parse', 'HEAD'], cwd), branch: git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd) };
+}
+
+export function readIndex(cwd = process.cwd()) {
+  const { index } = paths(cwd);
+  if (!existsSync(index)) return { version: INDEX_VERSION, sessions: [] };
+  try {
+    const data = JSON.parse(readFileSync(index, 'utf8'));
+    return { version: data.version ?? INDEX_VERSION, sessions: Array.isArray(data.sessions) ? data.sessions : [] };
+  } catch {
+    return { version: INDEX_VERSION, sessions: [] };
+  }
+}
+
+function writeIndex(idx, cwd = process.cwd()) {
+  const { dir, index } = paths(cwd);
+  mkdirSync(dir, { recursive: true });
+  // stable order: newest first by startedAt
+  const sessions = [...idx.sessions].sort((a, b) => Date.parse(b.startedAt || 0) - Date.parse(a.startedAt || 0));
+  // Atomic write (tmp + rename) so a concurrent reader never sees a half-written
+  // file (which readIndex would silently treat as empty). NOTE: this prevents
+  // *corruption*, not the lost-update race when two sessions in the same repo
+  // upsert concurrently — Phase 3 should move to per-session record files (no
+  // shared index) or file locking. Trace blobs are per-session, so unaffected.
+  const tmp = `${index}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: INDEX_VERSION, sessions }, null, 2) + '\n');
+  renameSync(tmp, index);
+}
+
+/** Write an OTLP request array as a trace blob; returns the repo-relative ref. */
+export function writeTrace(host, sessionId, requests, cwd = process.cwd()) {
+  const { tracesDir, root } = paths(cwd);
+  const file = join(tracesDir, `${host}-${sessionId}.otlp.jsonl`);
+  writeNdjson(file, requests);
+  return relative(root, file);
+}
+
+/** Insert-or-replace a session record by id, persist the index. */
+export function upsertSession(record, cwd = process.cwd()) {
+  const idx = readIndex(cwd);
+  const sessions = idx.sessions.filter((s) => !(s.id === record.id && s.host === record.host));
+  sessions.push(record);
+  writeIndex({ ...idx, sessions }, cwd);
+  return record;
+}
+
+/** Resolve a possibly-relative traceRef against the repo root. */
+export function resolveTrace(ref, cwd = process.cwd()) {
+  return isAbsolute(ref) ? ref : resolve(repoRoot(cwd), ref);
+}
+
+/** Most-recently-modified trace blob, or null. */
+export function lastTrace(cwd = process.cwd()) {
+  const { tracesDir } = paths(cwd);
+  if (!existsSync(tracesDir)) return null;
+  const files = readdirSync(tracesDir)
+    .filter((f) => f.endsWith('.otlp.jsonl'))
+    .map((f) => ({ f: join(tracesDir, f), m: statSync(join(tracesDir, f)).mtimeMs }))
+    .sort((a, b) => b.m - a.m);
+  return files.length ? files[0].f : null;
+}