@zuzuucodes/cli 1.0.0

package/zuzuu/live/install.mjs

@@ -0,0 +1,76 @@
+// Pure add/remove of zuzuu's hook block in a Claude Code settings.json object.
+//
+// settings.json is JSON (not line-based), so we can't use supermemory's HTML
+// delimiter blocks. Instead we tag our entries by a stable command SIGNATURE and
+// add/remove only those — never clobbering the user's own hooks. Idempotent.
+
+export const SIGNATURE = 'zuzuu.mjs'; // appears in every zuzuu hook command path, quote-agnostic
+const tagged = (cmd) => String(cmd).includes(SIGNATURE);
+// entire-style: agent can't read its own observability output (feedback loop) —
+// but ONLY that. The faculty home (agent/knowledge etc., served by `zuzuu init`)
+// must stay readable, so the deny is narrowed to .traces/ + .live/.
+const DENY_RULES = ['Read(./agent/.traces/**)', 'Read(./agent/.live/**)'];
+
+// Minimal hook set: lifecycle (Design B re-captures the transcript — no
+// PostToolUse needed) + the PreToolUse Guardrails GATE (the one place we *do*
+// sit on the hot path: it evaluates agent/guardrails/rules.json per tool call,
+// fails open, and stays silent unless a rule matches).
+export const LIFECYCLE_EVENTS = ['SessionStart', 'Stop', 'SessionEnd'];
+export const GATE_EVENTS = ['PreToolUse'];
+const ALL_EVENTS = [...LIFECYCLE_EVENTS, ...GATE_EVENTS];
+
+const clone = (o) => JSON.parse(JSON.stringify(o ?? {}));
+const hasOurs = (matchers) => (matchers || []).some((m) => (m.hooks || []).some((h) => tagged(h.command)));
+
+/** Pure hook add for ANY host's {hooks:{Event:[{hooks:[…]}]}} config. No permissions. */
+export function addHookEntries(settings, commandFor, events) {
+  const s = clone(settings);
+  s.hooks ||= {};
+  for (const ev of events) {
+    s.hooks[ev] ||= [];
+    if (!hasOurs(s.hooks[ev])) s.hooks[ev].push({ hooks: [{ type: 'command', command: commandFor(ev) }] });
+  }
+  return s;
+}
+
+/** Pure hook remove (only zuzuu entries) for ANY host. */
+export function removeHookEntries(settings) {
+  const s = clone(settings);
+  if (s.hooks) {
+    for (const ev of Object.keys(s.hooks)) {
+      s.hooks[ev] = (s.hooks[ev] || []).filter((m) => !(m.hooks || []).some((h) => tagged(h.command)));
+      if (!s.hooks[ev].length) delete s.hooks[ev];
+    }
+    if (!Object.keys(s.hooks).length) delete s.hooks;
+  }
+  return s;
+}
+
+/**
+ * Return a new settings object with zuzuu lifecycle hooks + the deny rule added.
+ * @param {object} settings  existing settings.json contents
+ * @param {(event:string)=>string} commandFor  builds the command string per event
+ */
+export function addHooks(settings, commandFor, events = ALL_EVENTS) {
+  const s = addHookEntries(settings, commandFor, events);
+  s.permissions ||= {};
+  s.permissions.deny ||= [];
+  for (const rule of DENY_RULES) if (!s.permissions.deny.includes(rule)) s.permissions.deny.push(rule);
+  return s;
+}
+
+/** Return a new settings object with only zuzuu's entries removed (others kept). */
+export function removeHooks(settings) {
+  const s = removeHookEntries(settings);
+  if (s.permissions?.deny) {
+    s.permissions.deny = s.permissions.deny.filter((r) => !DENY_RULES.includes(r));
+    if (!s.permissions.deny.length) delete s.permissions.deny;
+    if (s.permissions && !Object.keys(s.permissions).length) delete s.permissions;
+  }
+  return s;
+}
+
+/** True if zuzuu hooks are present for all lifecycle + gate events. */
+export function isInstalled(settings) {
+  return ALL_EVENTS.every((ev) => hasOurs(settings?.hooks?.[ev]));
+}

package/zuzuu/live/live-store.mjs

@@ -0,0 +1,78 @@
+// Liveness store for in-flight sessions: thin lifecycle records under agent/.live/.
+// Holds NO spans (Design B — spans come from re-parsing the transcript). Just
+// enough to know a session is open and when it was last seen, so a killed
+// terminal (which sends no SessionEnd) can be reconciled later.
+//
+// agent/.live/ is git-ignored (transient machine state, like .git/ session state).
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { paths, liveDir as liveDirOf } from '../store.mjs';
+import { SessionState } from '../session.mjs';
+
+const liveDir = (cwd) => liveDirOf(paths(cwd).dir);
+// Some hosts pass a file PATH as the session id (pi → the session-file path).
+// Sanitize for the record filename (the real id is preserved inside the JSON),
+// or the write fails into a non-existent nested dir. read/write/close all route
+// through here, so the key stays consistent.
+const recFile = (id) => `${String(id ?? 'unknown').replace(/[^A-Za-z0-9._-]/g, '_').slice(-120) || 'unknown'}.json`;
+const recPath = (id, cwd) => join(liveDir(cwd), recFile(id));
+
+function read(id, cwd) {
+  try {
+    return JSON.parse(readFileSync(recPath(id, cwd), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function write(rec, cwd) {
+  mkdirSync(liveDir(cwd), { recursive: true });
+  writeFileSync(recPath(rec.id, cwd), JSON.stringify(rec, null, 2) + '\n');
+  return rec;
+}
+
+/** Open (or refresh) a live session record. `generation` is the active gen id (WS3-T3). */
+export function openLive({ id, host, transcriptPath, startedAt, now, generation = null }, cwd = process.cwd()) {
+  const existing = read(id, cwd);
+  return write(
+    existing
+      ? { ...existing, lastSeen: now, transcriptPath: transcriptPath ?? existing.transcriptPath, generation: existing.generation ?? generation }
+      : { id, host, status: SessionState.ACTIVE, startedAt, lastSeen: now, transcriptPath, generation },
+    cwd,
+  );
+}
+
+/** Bump the heartbeat; create the record if a signal arrives before SessionStart. */
+export function touchLive({ id, host, transcriptPath, now }, cwd = process.cwd()) {
+  const existing = read(id, cwd);
+  if (!existing) return openLive({ id, host, transcriptPath, startedAt: new Date(now).toISOString(), now }, cwd);
+  return write({ ...existing, lastSeen: now, transcriptPath: transcriptPath ?? existing.transcriptPath }, cwd);
+}
+
+/** Remove a live record (its lifecycle has reached a terminal state). */
+export function closeLive(id, cwd = process.cwd()) {
+  try {
+    rmSync(recPath(id, cwd), { force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+export function listLive(cwd = process.cwd()) {
+  const dir = liveDir(cwd);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try {
+        return JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/** A live record is stale if its heartbeat is older than the window. */
+export const isStale = (rec, now, thresholdMs) => now - (rec.lastSeen || 0) > thresholdMs;

package/zuzuu/live/probe.mjs

@@ -0,0 +1,55 @@
+// zuzuu/live/probe.mjs — Phase-0 observation tool (the real-wire-data rule).
+//
+// Records EXACTLY what a host hands a hook so we can wire the real mapping
+// instead of trusting docs. Installed as a throwaway hook command per candidate
+// event; the user runs a real session; we then read the capture file to learn
+// which events fire, how the payload arrives (argv vs stdin), and its shape.
+//
+// Contract: never throws, always exits 0 (must not disturb the host session).
+//
+// usage (as a hook command):
+//   node probe.mjs --host <h> --event <EV> --out <abs path to .jsonl> [host's own args…]
+
+import { appendFileSync, mkdirSync, readFileSync, fstatSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const argOf = (k, d = null) => {
+  const i = process.argv.indexOf(k);
+  return i !== -1 && i + 1 < process.argv.length ? process.argv[i + 1] : d;
+};
+
+const host = argOf('--host', 'unknown');
+const event = argOf('--event', 'unknown');
+const out = argOf('--out', null);
+
+// Read the host's stdin payload — but ONLY when fd 0 is a pipe or file. A blocking
+// readFileSync(0) on an inherited TTY/open fd hangs the hook forever (Gemini closes
+// stdin so it returned; Codex left it open → a 36-min hang). Never block.
+let stdin = null;
+try {
+  const st = fstatSync(0);
+  if (st.isFIFO() || st.isFile()) stdin = readFileSync(0, 'utf8');
+} catch {
+  /* no/closed/unreadable stdin */
+}
+
+const record = {
+  at: new Date().toISOString(),
+  host,
+  event,
+  argv: process.argv.slice(2), // exactly how the host invoked us
+  stdin: stdin && stdin.length ? stdin : null,
+  cwd: process.cwd(),
+  env: { GEMINI_SESSION: process.env.GEMINI_SESSION_ID ?? null, CODEX: process.env.CODEX_SESSION_ID ?? null },
+};
+
+try {
+  if (out) {
+    mkdirSync(dirname(out), { recursive: true });
+    appendFileSync(out, JSON.stringify(record) + '\n');
+  }
+} catch {
+  /* observation must never break the host */
+}
+
+process.exit(0);

package/zuzuu/live/reconcile.mjs

@@ -0,0 +1,33 @@
+// Reconcile lost sessions. A killed terminal sends no SessionEnd, so an `active`
+// live record just stops getting heartbeats. We detect that lazily (on `zuzuu
+// doctor`/`status`), and — because the transcript is still on disk — do a FULL,
+// correct capture of the abandoned session before closing it. Nothing is lost.
+
+import { listLive, isStale, closeLive } from './live-store.mjs';
+import { byName } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { captureTrace } from '../capture-core.mjs';
+import { SessionState } from '../session.mjs';
+
+export const DEFAULT_STALE_MS = 15 * 60 * 1000; // 15 min without a heartbeat → abandoned
+
+/**
+ * Close out stale live sessions as `abandoned` (full transcript capture).
+ * @returns {Array<{id, host, action}>} what was reconciled
+ */
+export function reconcile({ now = Date.now(), thresholdMs = DEFAULT_STALE_MS, cwd = process.cwd() } = {}) {
+  const actions = [];
+  for (const rec of listLive(cwd)) {
+    if (!isStale(rec, now, thresholdMs)) continue;
+    const adapter = byName(rec.host);
+    if (adapter && rec.transcriptPath) {
+      try {
+        captureTrace({ adapter, ref: rec.transcriptPath, status: SessionState.ABANDONED, cwd });
+      } catch {
+        /* transcript gone/unreadable — still close the record below */
+      }
+    }
+    closeLive(rec.id, cwd);
+    actions.push({ id: rec.id, host: rec.host, action: 'abandoned' });
+  }
+  return actions;
+}

package/zuzuu/memory/adapter.mjs

@@ -0,0 +1,121 @@
+// zuzuu/memory/adapter.mjs
+// The Memory faculty adapter (WS2-T4). Wraps episode proposals behind the
+// faculty-spine adapter contract — { name, ingest, validate, apply, render } —
+// so `zuzuu review` can surface and approve memory entries uniformly.
+//
+// A memory proposal payload is an episode record matching the WS1 Memory schema:
+//   { id, date, title, provenance, body }
+//   id format: mem-<YYYY-MM-DD>-<slug>
+//
+// apply: writes agent/memory/entries/<id>.md with YAML frontmatter (status: curated)
+//        and the body sections (Attempted / Resulted / Remember next time).
+//
+// Registers itself on import.
+
+import { join } from 'node:path';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import * as registry from '../faculty/registry.mjs';
+
+const name = 'memory';
+
+// mem-<YYYY-MM-DD>-<slug>: the id must START with "mem-"
+const MEM_ID_RE = /^mem-/;
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function entriesDir(agentDir) {
+  return join(agentDir, 'memory', 'entries');
+}
+
+function entryPath(agentDir, id) {
+  return join(entriesDir(agentDir), `${id}.md`);
+}
+
+/** Render YAML frontmatter block from the payload fields. */
+function renderFrontmatter(payload) {
+  const lines = ['---'];
+  lines.push(`id: ${payload.id}`);
+  if (payload.date) lines.push(`date: ${payload.date}`);
+  if (payload.title) lines.push(`title: ${payload.title}`);
+  if (payload.provenance) {
+    lines.push('provenance:');
+    const p = payload.provenance;
+    if (Array.isArray(p.sessions)) lines.push(`  sessions: [${p.sessions.join(', ')}]`);
+    if (Array.isArray(p.hosts)) lines.push(`  hosts: [${p.hosts.join(', ')}]`);
+  }
+  if (Array.isArray(payload.tags) && payload.tags.length) {
+    lines.push(`tags: [${payload.tags.join(', ')}]`);
+  }
+  lines.push('status: curated');
+  lines.push('---');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// adapter contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Ingest a raw episode. Pass-through: the payload IS the episode.
+ */
+function ingest(_agentDir, raw) {
+  const payload = raw?.payload ?? raw ?? {};
+  return { payload, analysis: {}, dedupeKey: payload.id };
+}
+
+/**
+ * Validate an episode payload.
+ * @returns {{ok:boolean, errors:string[], warnings:string[]}}
+ */
+function validate(_agentDir, payload) {
+  const errors = [];
+  if (!payload?.id || typeof payload.id !== 'string') {
+    errors.push('id is required');
+  } else if (!MEM_ID_RE.test(payload.id)) {
+    errors.push(`id must match mem-<YYYY-MM-DD>-<slug> format (got '${payload.id}')`);
+  }
+  if (!payload?.title || !String(payload.title).trim()) {
+    errors.push('title is required');
+  }
+  return { ok: errors.length === 0, errors, warnings: [] };
+}
+
+/**
+ * Apply an approved episode proposal: write the entry Markdown file.
+ * @returns {{ok:boolean, action:string, itemIds:string[]}}
+ */
+function apply(agentDir, proposal) {
+  const payload = proposal?.payload ?? {};
+  const id = payload.id;
+
+  mkdirSync(entriesDir(agentDir), { recursive: true });
+
+  const frontmatter = renderFrontmatter(payload);
+  const body = payload.body ?? '';
+  const content = frontmatter + '\n' + body + (body.endsWith('\n') ? '' : '\n');
+
+  writeFileSync(entryPath(agentDir, id), content);
+
+  return { ok: true, action: `wrote memory ${id}`, itemIds: [id] };
+}
+
+/**
+ * Render an episode proposal for the human gate.
+ * @returns {{line:string, card:string}}
+ */
+function render(proposal) {
+  const p = proposal?.payload ?? {};
+  const title = p.title ?? '';
+  const date = p.date ?? '';
+  const id = p.id ?? '';
+  return {
+    line: `${id}  [episode]  ${title} (${date})`,
+    card: `${title}\n  id: ${id}  date: ${date}`,
+  };
+}
+
+export const adapter = { name, ingest, validate, apply, render };
+
+registry.register(adapter);

package/zuzuu/miners/actions.mjs

@@ -0,0 +1,118 @@
+// zuzuu/miners/actions.mjs
+// Actions miner (WS5-T2) — detect recurring Bash 2-gram sequences across
+// sessions and scaffold runbook proposals into actions/inbox/<slug>/.
+//
+// Shape: { faculty:'actions', aggregate(sessions, opts), propose(agentDir, aggregated) }
+// Self-registers on import.
+
+import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { slugify } from '../knowledge/items.mjs';
+import { isSafeSlug, actionsDir, inboxDir } from '../actions/manifest.mjs';
+import { register } from './registry.mjs';
+
+// Must match the constant in knowledge/distill.mjs (adjacent Bash separator).
+const SEQ_SEP = ' && ';
+
+/**
+ * Derive a safe slug from a raw sequence string (bounded, safe chars only).
+ * e.g. "npm ci && npm test" → "npm-ci-npm-test" (max 50 chars).
+ */
+function slugFromSequence(seq) {
+  const raw = slugify(seq.replace(/ && /g, ' '), 50);
+  // slugify already returns safe chars [a-z0-9-]; isSafeSlug allows upper too,
+  // but we keep lower for readability. Force-safe just in case.
+  return raw || 'action-sequence';
+}
+
+/**
+ * Aggregate recurring Bash 2-gram sequences from mined sessions.
+ *
+ * @param {Array<{sessionId:string, sequences:string[]}>} sessions
+ *   The per-session mineTranscript output array.
+ * @param {object} opts
+ * @param {number} [opts.minSeqCount=3]    min total occurrences across all sessions
+ * @param {number} [opts.minSeqSessions=2] min distinct sessions the sequence appears in
+ * @returns {Array<{payload:{slug,title,steps,promptSnippet,sequence}, evidence:{occurrences,sessions,sequence}}>}
+ */
+export function aggregate(sessions, { minSeqCount = 3, minSeqSessions = 2 } = {}) {
+  // Count occurrences per sequence string, tracking distinct session ids.
+  const stats = new Map(); // rawSeq → { count, sessions: Set<sessionId> }
+  for (const s of sessions) {
+    if (!Array.isArray(s.sequences)) continue;
+    for (const seq of s.sequences) {
+      const st = stats.get(seq) ?? { count: 0, sessions: new Set() };
+      st.count++;
+      st.sessions.add(s.sessionId);
+      stats.set(seq, st);
+    }
+  }
+
+  const candidates = [];
+  for (const [seq, st] of stats) {
+    if (st.count < minSeqCount || st.sessions.size < minSeqSessions) continue;
+    const steps = seq.split(SEQ_SEP);
+    const slug = slugFromSequence(seq);
+    // Make sure the slug is safe; if not, skip rather than emit a bad slug.
+    if (!isSafeSlug(slug)) continue;
+    const title = `Run sequence: ${steps.join(' → ')}`;
+    const promptSnippet = `Runs: ${steps.join(' then ')}`;
+    candidates.push({
+      payload: { slug, title, steps, promptSnippet, sequence: seq },
+      evidence: { occurrences: st.count, sessions: st.sessions.size, sequence: seq },
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Write a runbook action proposal into actions/inbox/<slug>/ for each candidate.
+ * Idempotent: skips if inbox/<slug>/ OR active actions/<slug>/ already exists.
+ *
+ * @param {string} agentDir
+ * @param {ReturnType<typeof aggregate>} aggregated
+ * @returns {number} count of new proposals written
+ */
+export function propose(agentDir, aggregated) {
+  const actDir = actionsDir(agentDir);
+  const ibDir = inboxDir(agentDir);
+  let count = 0;
+  for (const c of aggregated) {
+    const { slug, title, steps, promptSnippet } = c.payload;
+    const inboxSlug = join(ibDir, slug);
+    const activeSlug = join(actDir, slug);
+    // Idempotent: skip if already proposed or already active.
+    if (existsSync(inboxSlug) || existsSync(activeSlug)) continue;
+
+    mkdirSync(inboxSlug, { recursive: true });
+
+    // action.json — minimal manifest (no run.mjs; this is a runbook action).
+    const manifest = {
+      slug,
+      title,
+      description: `Recurring command sequence detected from session traces: ${steps.join(' → ')}.`,
+      promptSnippet,
+    };
+    writeFileSync(join(inboxSlug, 'action.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+    // SKILL.md — numbered runbook steps.
+    const stepsBlock = steps.map((cmd, i) => `${i + 1}. \`${cmd}\``).join('\n');
+    const skillMd = `---
+name: ${title}
+description: ${manifest.description}
+---
+
+## Steps
+
+${stepsBlock}
+`;
+    writeFileSync(join(inboxSlug, 'SKILL.md'), skillMd);
+
+    count++;
+  }
+  return count;
+}
+
+export const miner = { faculty: 'actions', aggregate, propose };
+
+register(miner);

package/zuzuu/miners/guardrails.mjs

@@ -0,0 +1,174 @@
+// zuzuu/miners/guardrails.mjs
+// Guardrails miner (WS5-T3) — detect repeated destructive-command failures
+// across sessions and propose ask-only guardrail rules.
+//
+// MANDATORY SAFETY PROPERTIES (enforced in aggregate):
+//   1. action is ALWAYS 'ask' — never 'deny'. Auto-proposed rules only escalate
+//      to the human prompt, they never hard-block.
+//   2. Patterns are LITERAL-ESCAPED from the observed command — never a broad/
+//      free regex.  escapeRegex() handles this.
+//   3. Cross-session corroboration required — a destructive command must fail
+//      ≥minFailures (default 3) times across ≥minSessions (default 2) DISTINCT
+//      sessions.  A single session — no matter how many failures — produces
+//      NOTHING.
+//
+// Shape: { faculty:'guardrails', aggregate(sessions, opts), propose(agentDir, aggregated) }
+// Self-registers on import.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { slugify } from '../knowledge/items.mjs';
+import { makeProposal, writeProposal, listProposals } from '../faculty/proposal.mjs';
+import { register } from './registry.mjs';
+
+// ---------------------------------------------------------------------------
+// escapeRegex — the ONLY safe way to build a pattern from a literal command.
+// Escapes all RegExp metacharacters so the pattern matches the exact string.
+
+/**
+ * Escape all regex metacharacters in `s` so that `new RegExp(escapeRegex(s))`
+ * matches exactly the string `s` and nothing broader.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function escapeRegex(s) {
+  // Standard set of regex metacharacters that need escaping.
+  return String(s).replace(/[.*+?^${}()|[\]\\\/\-]/g, '\\$&');
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+
+/** Normalise a command string (trim + collapse whitespace). */
+const norm = (cmd) => String(cmd).trim().replace(/\s+/g, ' ').slice(0, 200);
+
+/** Derive a guardrails-miner id for a command. */
+function guardId(cmd) {
+  return 'guard-' + slugify(cmd, 50);
+}
+
+/** Load rules.json; returns { version, rules:[] } if absent/unreadable. */
+function loadRules(agentDir) {
+  const path = join(agentDir, 'guardrails', 'rules.json');
+  if (!existsSync(path)) return { version: 1, rules: [] };
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return { version: 1, rules: [] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// aggregate
+
+/**
+ * Group destructiveFailures by normalised command; emit a candidate ONLY when
+ * both the occurrence count and distinct-session count meet their thresholds.
+ *
+ * SAFETY: a single-session cluster, no matter how large, produces NOTHING.
+ *
+ * @param {Array<{sessionId:string, destructiveFailures:{cmd:string,tool:string}[]}>} sessions
+ * @param {object} opts
+ * @param {number} [opts.minFailures=3]   min total failures across all sessions
+ * @param {number} [opts.minSessions=2]  min distinct sessions with ≥1 failure each
+ * @returns {Array<{payload:{id,action,tool,pattern,reason}, evidence:{occurrences,sessions}}>}
+ */
+export function aggregate(sessions, { minFailures = 3, minSessions = 2 } = {}) {
+  // cmd (normalized) → { count: number, sessions: Set<sessionId>, tool: string }
+  const stats = new Map();
+
+  for (const s of sessions) {
+    if (!Array.isArray(s.destructiveFailures)) continue;
+    for (const { cmd, tool } of s.destructiveFailures) {
+      const key = norm(cmd);
+      const st = stats.get(key) ?? { count: 0, sessions: new Set(), tool: tool ?? 'Bash' };
+      st.count++;
+      st.sessions.add(s.sessionId);
+      // Keep first observed tool name (they should all be 'Bash' for destructive cmds).
+      stats.set(key, st);
+    }
+  }
+
+  const candidates = [];
+  for (const [cmd, st] of stats) {
+    // SAFETY: enforce BOTH thresholds — cross-session gate is the key one.
+    if (st.count < minFailures) continue;
+    if (st.sessions.size < minSessions) continue; // ← single-session always rejected here
+
+    const id = guardId(cmd);
+    const pattern = escapeRegex(cmd);
+    const tool = st.tool ?? 'Bash';
+
+    candidates.push({
+      payload: {
+        id,
+        // SAFETY: ALWAYS 'ask', never 'deny'.
+        action: 'ask',
+        tool,
+        pattern,
+        reason: `auto-proposed: '${cmd}' failed repeatedly across sessions — confirm before running`,
+      },
+      evidence: {
+        occurrences: st.count,
+        sessions: st.sessions.size,
+      },
+    });
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// propose
+
+/**
+ * Write a guardrails proposal into agent/guardrails/proposals/ for each candidate.
+ * Idempotent:
+ *   - skips if a guardrails proposal with the same payload.id already exists
+ *   - skips if rules.json already has a rule with that id
+ *
+ * The proposals flow through `zuzuu review` → guardrails adapter on approval.
+ *
+ * @param {string} agentDir
+ * @param {ReturnType<typeof aggregate>} aggregated
+ * @returns {number} count of new proposals written
+ */
+export function propose(agentDir, aggregated) {
+  // Load existing proposals (ids already pending).
+  const existing = listProposals(agentDir, 'guardrails');
+  const existingIds = new Set(existing.map((p) => p.payload?.id).filter(Boolean));
+
+  // Load existing rules (ids already applied).
+  const rulesData = loadRules(agentDir);
+  const rulesIds = new Set((rulesData.rules ?? []).map((r) => r.id).filter(Boolean));
+
+  let count = 0;
+  for (const c of aggregated) {
+    const { payload, evidence } = c;
+
+    // Idempotent: skip if already proposed or already a live rule.
+    if (existingIds.has(payload.id)) continue;
+    if (rulesIds.has(payload.id)) continue;
+
+    const proposal = makeProposal({
+      faculty: 'guardrails',
+      kind: 'rule',
+      source: 'distill',
+      payload,
+      evidence,
+    });
+
+    writeProposal(agentDir, proposal);
+    count++;
+  }
+
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// self-register
+
+export const miner = { faculty: 'guardrails', aggregate, propose };
+
+register(miner);