@zuzuucodes/cli 1.0.0

package/zuzuu/actions/manifest.mjs

@@ -0,0 +1,72 @@
+// zuzuu/actions/manifest.mjs
+// Reads the Actions faculty off disk: one action per dir under agent/actions/.
+// Two kinds — `script` (has run.mjs + action.json) and `runbook` (SKILL.md prose).
+// Pure-ish: filesystem reads only, no logging, no process control.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+
+// Action slugs: letters/digits start, then letters/digits/-/_. No dots or slashes
+// → cannot escape agent/actions/ via path traversal.
+export const SAFE_SLUG = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export function isSafeSlug(slug) {
+  return typeof slug === 'string' && SAFE_SLUG.test(slug);
+}
+
+export const actionsDir = (agentDir) => join(agentDir, 'actions');
+export const inboxDir = (agentDir) => join(actionsDir(agentDir), 'inbox');
+const actionDir = (agentDir, slug) => join(actionsDir(agentDir), slug);
+
+/** Read action.json for a slug → object, or null if absent/unparseable. */
+export function loadManifest(agentDir, slug) {
+  const path = join(actionDir(agentDir, slug), 'action.json');
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Pull `name` / `description` from a SKILL.md YAML-ish frontmatter (best-effort). */
+function skillFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const fm = {};
+  if (m) {
+    for (const line of m[1].split('\n')) {
+      const kv = line.match(/^(\w+):\s*(.*)$/);
+      if (kv) fm[kv[1]] = kv[2].trim();
+    }
+  }
+  return fm;
+}
+
+/**
+ * List actions in a base dir as {slug, kind, title, promptSnippet}.
+ * `script` = dir has run.mjs; `runbook` = dir has SKILL.md; other entries skipped.
+ * Reads the manifest directly from each entry dir (works for any baseDir, e.g. the inbox).
+ */
+export function listActions(baseDir) {
+  if (!existsSync(baseDir)) return [];
+  const out = [];
+  for (const name of readdirSync(baseDir)) {
+    const d = join(baseDir, name);
+    let isDir = false;
+    try { isDir = statSync(d).isDirectory(); } catch { /* skip */ }
+    if (!isDir) continue; // ignores README.md and any stray files
+    if (existsSync(join(d, 'run.mjs'))) {
+      let man = {};
+      try { man = JSON.parse(readFileSync(join(d, 'action.json'), 'utf8')); } catch { /* slug fallback */ }
+      out.push({ slug: name, kind: 'script', title: man.title ?? name, promptSnippet: man.promptSnippet ?? man.description ?? name });
+    } else if (existsSync(join(d, 'SKILL.md'))) {
+      let fm = {};
+      try { fm = skillFrontmatter(readFileSync(join(d, 'SKILL.md'), 'utf8')); } catch { /* slug fallback */ }
+      out.push({ slug: name, kind: 'runbook', title: fm.name ?? name, promptSnippet: fm.description ?? name });
+    }
+  }
+  return out;
+}
+
+/** Active actions under agent/actions/ (the inbox subdir is excluded). */
+export function allActions(agentDir) {
+  return listActions(actionsDir(agentDir)).filter((a) => a.slug !== 'inbox');
+}

package/zuzuu/actions/marker.mjs

@@ -0,0 +1,4 @@
+// zuzuu/actions/marker.mjs
+// The result-marker sentinel, in its own module so importing it has NO side
+// effects (runner.mjs runs harness logic at top-level and must never be imported).
+export const MARKER = '__ZUZUU_ACT_RESULT__';

package/zuzuu/actions/runner.mjs

@@ -0,0 +1,37 @@
+// zuzuu/actions/runner.mjs
+// The child harness spawned by dispatch.runAction. NOT imported by anything —
+// it's executed: `node runner.mjs <payloadJson>`. It runs the action in its own
+// process (isolating process.exit/throw), then prints exactly one result marker.
+//
+// payload = { runPath, inputs, outputs, default_args, args }
+// stdout: the action's own logs, then a final line `__ZUZUU_ACT_RESULT__<json>`.
+
+import { pathToFileURL } from 'node:url';
+import { validateInputs, validateOutputs } from './schema.mjs';
+import { MARKER } from './marker.mjs';
+
+function emit(obj) {
+  process.stdout.write('\n' + MARKER + JSON.stringify(obj) + '\n');
+}
+
+const payload = JSON.parse(process.argv[2] || '{}');
+try {
+  const mod = await import(pathToFileURL(payload.runPath).href);
+  if (typeof mod.main !== 'function') {
+    emit({ ok: false, error: 'not_runnable', detail: 'run.mjs must export an async main(args)' });
+  } else {
+    let merged = { ...(payload.default_args ?? {}), ...(payload.args ?? {}) };
+    if (typeof mod.prepareArguments === 'function') merged = mod.prepareArguments(merged);
+    const vi = validateInputs(payload.inputs, {}, merged);
+    if (!vi.ok) {
+      emit({ ok: false, error: 'invalid_input', detail: vi.error });
+    } else {
+      const result = await mod.main(vi.args);
+      const vo = validateOutputs(payload.outputs, result);
+      if (!vo.ok) emit({ ok: false, error: 'invalid_output', detail: vo.error });
+      else emit({ ok: true, value: vo.value });
+    }
+  }
+} catch (e) {
+  emit({ ok: false, error: 'script_error', detail: String((e && e.message) || e) });
+}

package/zuzuu/actions/schema.mjs

@@ -0,0 +1,73 @@
+// zuzuu/actions/schema.mjs
+// A hand-rolled JSON-Schema *subset* validator — zero-dep (no Ajv), matching the
+// project's node-builtins-only policy. Supports: object (properties, required),
+// array (items), string/number/integer/boolean scalars, enum, and basic length/
+// range constraints. Returns an array of error strings ([] = valid). No coercion:
+// values are expected to already carry real JSON types.
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** @returns {string[]} error messages; empty array = valid */
+export function validate(schema, value, path = '$') {
+  const errors = [];
+  if (!schema || typeof schema !== 'object') return errors; // no schema → accept
+  const type = schema.type;
+
+  if (type === 'object') {
+    if (!isPlainObject(value)) return [`${path}: expected object`];
+    for (const req of schema.required ?? []) {
+      if (!(req in value)) errors.push(`${path}.${req}: required`);
+    }
+    for (const [k, sub] of Object.entries(schema.properties ?? {})) {
+      if (k in value) errors.push(...validate(sub, value[k], `${path}.${k}`));
+    }
+    return errors;
+  }
+
+  if (type === 'array') {
+    if (!Array.isArray(value)) return [`${path}: expected array`];
+    if (schema.items) value.forEach((v, i) => errors.push(...validate(schema.items, v, `${path}[${i}]`)));
+    return errors;
+  }
+
+  if (type === 'string' && typeof value !== 'string') errors.push(`${path}: expected string`);
+  else if (type === 'number' && (typeof value !== 'number' || Number.isNaN(value))) errors.push(`${path}: expected number`);
+  else if (type === 'integer' && !Number.isInteger(value)) errors.push(`${path}: expected integer`);
+  else if (type === 'boolean' && typeof value !== 'boolean') errors.push(`${path}: expected boolean`);
+
+  if (schema.enum && errors.length === 0 && !schema.enum.includes(value)) errors.push(`${path}: must be one of ${schema.enum.join(', ')}`);
+  if (typeof value === 'string') {
+    if (schema.minLength != null && value.length < schema.minLength) errors.push(`${path}: shorter than minLength ${schema.minLength}`);
+    if (schema.maxLength != null && value.length > schema.maxLength) errors.push(`${path}: longer than maxLength ${schema.maxLength}`);
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum != null && value < schema.minimum) errors.push(`${path}: below minimum ${schema.minimum}`);
+    if (schema.maximum != null && value > schema.maximum) errors.push(`${path}: above maximum ${schema.maximum}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Validate caller inputs against the manifest `inputs` schema.
+ * Merges default_args then caller args (caller wins).
+ * @returns {{ok:true,args:object} | {ok:false,error:string,errors:string[]}}
+ */
+export function validateInputs(schema, defaults = {}, caller = {}) {
+  const args = { ...(defaults ?? {}), ...(caller ?? {}) };
+  const errors = validate(schema ?? { type: 'object' }, args);
+  return errors.length ? { ok: false, error: errors[0], errors } : { ok: true, args };
+}
+
+/**
+ * Validate an action's return value against the manifest `outputs` schema.
+ * Enforces the main(args) → object contract first.
+ * @returns {{ok:true,value:object} | {ok:false,error:string,errors?:string[]}}
+ */
+export function validateOutputs(schema, value) {
+  if (!isPlainObject(value)) return { ok: false, error: 'action output must be a JSON object' };
+  const errors = validate(schema ?? { type: 'object' }, value);
+  return errors.length ? { ok: false, error: errors[0], errors } : { ok: true, value };
+}

package/zuzuu/actions/trail.mjs

@@ -0,0 +1,22 @@
+// zuzuu/actions/trail.mjs
+// The actions observability trail (A7): every `zuzuu act` run appends an outcome
+// record to agent/.live/actions.jsonl. This is the "details" side of the result —
+// the agent sees the marker value; the trace keeps the metadata. Fail-soft: a
+// logging failure must never affect the action (mirrors the guardrails decision log).
+
+import { join } from 'node:path';
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { liveDir } from '../store.mjs';
+
+/** Append a fail-soft outcome record. Never throws. */
+export function recordOutcome(agentDir, { slug, ok, error } = {}) {
+  try {
+    const dir = liveDir(agentDir);
+    mkdirSync(dir, { recursive: true });
+    const rec = { at: new Date().toISOString(), slug, ok: !!ok };
+    if (error) rec.error = error;
+    appendFileSync(join(dir, 'actions.jsonl'), JSON.stringify(rec) + '\n');
+  } catch {
+    /* logging must never affect the action */
+  }
+}

package/zuzuu/capture-core.mjs

@@ -0,0 +1,49 @@
+// Shared capture: transcript -> OTLP trace blob + git-native session record.
+// Used by `zuzuu capture` (post-hoc, status `captured`) and the live lifecycle
+// (`hook`/`reconcile`, statuses active/completed/abandoned). One proven path —
+// Design B: the hook never builds spans, it re-runs THIS.
+
+import { eventsToSpans } from '../experiments/experiment-1-trace-capture/core/spans.mjs';
+import { toExportRequest } from '../experiments/experiment-1-trace-capture/core/otlp.mjs';
+import { EventKind, Status } from '../experiments/experiment-1-trace-capture/core/event.mjs';
+import { makeSession, SessionState } from './session.mjs';
+import { writeTrace, upsertSession, gitInfo } from './store.mjs';
+
+export function countsOf(trace) {
+  return {
+    turns: trace.events.filter((e) => e.kind === EventKind.TURN).length,
+    tools: trace.events.filter((e) => e.kind === EventKind.TOOL_CALL).length,
+    errors: trace.events.filter((e) => e.kind === EventKind.TOOL_CALL && e.status === Status.ERROR).length,
+  };
+}
+
+/**
+ * Parse a transcript via `adapter`, write the OTLP blob, upsert the index record.
+ * Idempotent (deterministic ids) — safe to re-run on every lifecycle signal.
+ * @param {string|null} [generation]  active generation id — threads from the OPEN
+ *   hook so every session carries its Run linkage (WS3-T3). Null-safe.
+ * @returns {{trace, traceId, spans, traceRef, record, counts}}
+ */
+export function captureTrace({ adapter, ref, status = SessionState.CAPTURED, cwd = process.cwd(), generation = null }) {
+  const trace = adapter.parse(ref);
+  const { traceId, spans } = eventsToSpans(trace);
+  const request = toExportRequest({ traceId, spans }, { host: trace.host, sessionId: trace.sessionId });
+  const traceRef = writeTrace(trace.host, trace.sessionId, [request], cwd);
+
+  const root = trace.events.find((e) => e.kind === EventKind.SESSION) || trace.events[0];
+  const counts = countsOf(trace);
+  const record = makeSession({
+    id: trace.sessionId,
+    host: trace.host,
+    status,
+    startedAt: new Date(root.startMs).toISOString(),
+    endedAt: new Date(root.endMs).toISOString(),
+    traceId,
+    traceRef,
+    git: gitInfo(cwd),
+    counts,
+    generation,
+  });
+  upsertSession(record, cwd);
+  return { trace, traceId, spans, traceRef, record, counts };
+}

package/zuzuu/commands/act-author.mjs

@@ -0,0 +1,72 @@
+// zuzuu/commands/act-author.mjs
+// `zuzuu act new <slug>` — scaffold a script action (idempotent, no-clobber).
+// `zuzuu act schema <slug> [--mcp|--openai|--anthropic]` — convert the manifest.
+
+import { mkdirSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { actionsDir, inboxDir, loadManifest, isSafeSlug } from '../actions/manifest.mjs';
+import { toMcpTool, toOpenAITool, toAnthropicTool } from '../actions/convert.mjs';
+
+function manifestStub(slug) {
+  return JSON.stringify({
+    slug,
+    title: slug,
+    description: 'what this action does',
+    promptSnippet: `one line the digest shows for ${slug}`,
+    inputs: { type: 'object', properties: {}, required: [] },
+    outputs: { type: 'object', properties: {} },
+    default_args: {},
+    requires: [],
+  }, null, 2) + '\n';
+}
+
+const RUN_TEMPLATE = `// run.mjs — implement the action. Export async main(args) → a JSON object.
+// Optional: export prepareArguments(args) to fold legacy args before validation.
+
+// export function prepareArguments(args) { return args; }
+
+export async function main(args) {
+  // args is validated against action.json "inputs"; return must match "outputs".
+  return { ok: true };
+}
+`;
+
+/** Scaffold an action dir under `baseDir/<slug>/`. No-clobber. */
+function scaffoldInto(baseDir, slug) {
+  if (!isSafeSlug(slug)) throw new Error(`invalid slug '${slug}' — letters, digits, - and _ only`);
+  const dir = join(baseDir, slug);
+  mkdirSync(dir, { recursive: true });
+  const created = [];
+  const write = (name, body) => {
+    const p = join(dir, name);
+    if (!existsSync(p)) { writeFileSync(p, body); created.push(name); }
+  };
+  write('action.json', manifestStub(slug));
+  write('run.mjs', RUN_TEMPLATE);
+  return { created };
+}
+
+/** Scaffold a live action (agent/actions/<slug>/). Humans author here directly. */
+export function scaffoldAction(agentDir, slug) {
+  return scaffoldInto(actionsDir(agentDir), slug);
+}
+
+/** Scaffold a PROPOSED action (agent/actions/inbox/<slug>/) — agents propose here. */
+export function proposeAction(agentDir, slug) {
+  return scaffoldInto(inboxDir(agentDir), slug);
+}
+
+export function newAction(agentDir, slug) {
+  if (!slug) { console.error('usage: zuzuu act new <slug>'); process.exit(1); }
+  const { created } = scaffoldAction(agentDir, slug);
+  if (created.length) console.log(`scaffolded action '${slug}' → ${created.join(', ')} in agent/actions/${slug}/`);
+  else console.log(`action '${slug}' already complete — nothing to do`);
+}
+
+export function schema(agentDir, slug, args = {}) {
+  if (!slug) { console.error('usage: zuzuu act schema <slug> [--mcp|--openai|--anthropic]'); process.exit(1); }
+  const man = loadManifest(agentDir, slug);
+  if (!man) { console.error(`no action '${slug}' (missing action.json)`); process.exit(1); }
+  const def = args.openai ? toOpenAITool(man) : args.anthropic ? toAnthropicTool(man) : toMcpTool(man);
+  console.log(JSON.stringify(def, null, 2));
+}

package/zuzuu/commands/act.mjs

@@ -0,0 +1,101 @@
+// zuzuu/commands/act.mjs
+// `zuzuu act` — the Actions faculty CLI. The host's Bash invokes this, so each run
+// is an observable span already covered by the guardrails gate. Subcommands:
+//   zuzuu act [list]            the index (slug · kind · snippet)
+//   zuzuu act show <slug>       full manifest (script) or SKILL.md (runbook)
+//   zuzuu act <slug> [--args J] run a script action
+//   zuzuu act new <slug>        scaffold (Task 8)
+//   zuzuu act schema <slug>     convert to a tool definition (Task 8)
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from '../store.mjs';
+import { allActions, loadManifest, actionsDir, isSafeSlug } from '../actions/manifest.mjs';
+import { runAction } from '../actions/dispatch.mjs';
+import { MARKER } from '../actions/marker.mjs';
+import { newAction, schema as schemaCmd, proposeAction } from './act-author.mjs';
+import { listProposedActions, activateAction, rejectAction } from '../actions/inbox.mjs';
+import { recordOutcome } from '../actions/trail.mjs';
+
+const RESERVED = new Set(['list', 'show', 'new', 'schema', 'propose', 'inbox', 'approve', 'reject']);
+
+function requireSlug(slug, usage) {
+  if (!slug) { console.error(usage); process.exit(1); }
+  if (!isSafeSlug(slug)) { console.error(`invalid slug '${slug}' — letters, digits, - and _ only`); process.exit(1); }
+  return slug;
+}
+
+function list(agentDir) {
+  const actions = allActions(agentDir);
+  if (!actions.length) return console.log('no actions yet — scaffold one with `zuzuu act new <slug>`');
+  for (const a of actions.sort((x, y) => x.slug.localeCompare(y.slug))) {
+    console.log(`  ${a.slug}  [${a.kind}]  ${a.promptSnippet}`);
+  }
+}
+
+function show(agentDir, slug) {
+  if (!slug) { console.error('usage: zuzuu act show <slug>'); process.exit(1); }
+  const man = loadManifest(agentDir, slug);
+  if (man) return console.log(JSON.stringify(man, null, 2));
+  const skill = join(actionsDir(agentDir), slug, 'SKILL.md');
+  if (existsSync(skill)) return process.stdout.write(readFileSync(skill, 'utf8'));
+  console.error(`no action '${slug}'`);
+  process.exit(1);
+}
+
+function run(agentDir, slug, args) {
+  let callerArgs = {};
+  if (args.args) {
+    try { callerArgs = JSON.parse(args.args); }
+    catch { console.error('--args must be valid JSON'); process.exit(1); }
+  }
+  const r = runAction(agentDir, slug, callerArgs);
+  recordOutcome(agentDir, { slug, ok: r.ok, error: r.ok ? undefined : r.error });
+  if (r.logs) process.stdout.write(r.logs + '\n');
+  console.log(MARKER + JSON.stringify(r.ok ? { ok: true, value: r.value } : { ok: false, error: r.error, detail: r.detail }));
+  if (r.ok) console.log(`✓ ${slug} ok`);
+  else console.error(`✗ ${slug}: ${r.error}${r.detail ? ` — ${r.detail}` : ''}`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+function propose(agentDir, slug) {
+  const { created } = proposeAction(agentDir, slug);
+  if (created.length) console.log(`proposed action '${slug}' → ${created.join(', ')} in agent/actions/inbox/${slug}/ (review with \`zuzuu review\`)`);
+  else console.log(`proposed action '${slug}' already complete — nothing to do`);
+}
+
+function inbox(agentDir) {
+  const pending = listProposedActions(agentDir);
+  if (!pending.length) return console.log('no proposed actions — inbox empty');
+  for (const a of pending.sort((x, y) => x.slug.localeCompare(y.slug))) {
+    console.log(`  ${a.slug}  [${a.kind}]  ${a.promptSnippet}`);
+  }
+}
+
+function approve(agentDir, slug) {
+  const r = activateAction(agentDir, slug);
+  console.log(r.ok ? `✓ activated '${slug}'` : `✗ ${r.error}`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+function reject(agentDir, slug) {
+  const r = rejectAction(agentDir, slug);
+  console.log(r.ok ? `✓ rejected '${slug}'` : `✗ ${r.error}`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+export function act(args) {
+  const agentDir = paths().dir;
+  const sub = args._[0];
+  if (!sub || sub === 'list') return list(agentDir);
+  if (sub === 'show') return show(agentDir, requireSlug(args._[1], 'usage: zuzuu act show <slug>'));
+  if (sub === 'new') return newAction(agentDir, requireSlug(args._[1], 'usage: zuzuu act new <slug>'));
+  if (sub === 'schema') return schemaCmd(agentDir, requireSlug(args._[1], 'usage: zuzuu act schema <slug> [--openai|--anthropic]'), args);
+  if (sub === 'propose') return propose(agentDir, requireSlug(args._[1], 'usage: zuzuu act propose <slug>'));
+  if (sub === 'inbox') return inbox(agentDir);
+  if (sub === 'approve') return approve(agentDir, requireSlug(args._[1], 'usage: zuzuu act approve <slug>'));
+  if (sub === 'reject') return reject(agentDir, requireSlug(args._[1], 'usage: zuzuu act reject <slug>'));
+  // future-reserved guard: extend RESERVED + add a handler above in tandem
+  if (RESERVED.has(sub)) { console.error(`unknown: zuzuu act ${sub}`); process.exit(1); }
+  return run(agentDir, requireSlug(sub, 'usage: zuzuu act <slug> [--args JSON]'), args);
+}

package/zuzuu/commands/capture.mjs

@@ -0,0 +1,32 @@
+// `zuzuu capture` — post-hoc: parse a host transcript into a git-native trace + record.
+
+import { ADAPTERS, byName, detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { captureTrace } from '../capture-core.mjs';
+import { paths } from '../store.mjs';
+
+function chooseRef(adapter, args) {
+  if (args.file) return args.file;
+  const sessions = adapter.listSessions({ cwd: process.cwd(), project: args.project });
+  let pool = sessions;
+  if (args.session) pool = pool.filter((s) => s.sessionId === args.session || s.sessionId.includes(args.session));
+  if (!pool.length) throw new Error(`no matching session for ${adapter.name} (found ${sessions.length})`);
+  return pool[0].ref;
+}
+
+export function capture(args) {
+  const adapter = args.host ? byName(args.host) : detected()[0];
+  if (!adapter) {
+    console.error(args.host ? `unknown host: ${args.host} (known: ${ADAPTERS.map((a) => a.name).join(', ')})` : 'no host detected — run `zuzuu status`');
+    process.exit(1);
+  }
+
+  const { record, spans, traceRef, counts } = captureTrace({ adapter, ref: chooseRef(adapter, args) });
+  const { index } = paths();
+  console.log(`captured ${record.host} session ${record.id}`);
+  console.log(`  status   : ${record.status}`);
+  console.log(`  spans    : ${spans.length}  (turns:${counts.turns}, tools:${counts.tools}, errors:${counts.errors})`);
+  console.log(`  git      : ${record.git.commit ? record.git.commit.slice(0, 8) : '(no repo)'} ${record.git.branch || ''}`);
+  console.log(`  trace    : ${traceRef}  (git-ignored)`);
+  console.log(`  indexed  : ${index}  (tracked)`);
+  console.log(`  inspect  : zuzuu trace --last`);
+}

package/zuzuu/commands/code.mjs

@@ -0,0 +1,84 @@
+// `zuzuu code` — launch OpenCode as the bundled default host, pre-wired with the
+// faculty home + the zuzuu plugin (capture + gate + digest). We CONFIGURE + LAUNCH
+// the real `opencode` binary; we never fork it and never drive it headlessly
+// (the observe model; interactive-first). Stage 2 of the product sequence.
+//
+// Zero-dep: OpenCode is a runtime PEER — detected, and installed on demand if
+// missing — never an npm dependency.
+
+import { existsSync, readSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { init } from './init.mjs';
+import { enable } from './enable.mjs';
+import { repoRoot } from '../store.mjs';
+import { homeExists } from '../scaffold.mjs';
+
+// Run a command inside `dir` without permanently changing the process cwd —
+// init/enable resolve their target from process.cwd(), so we chdir around them.
+function inDir(dir, fn) {
+  const prev = process.cwd();
+  try { process.chdir(dir); return fn(); } finally { process.chdir(prev); }
+}
+
+// --- default (real) deps; tests inject fakes for everything external ---
+const realDetect = () => { try { return spawnSync('opencode', ['--version'], { stdio: 'ignore' }).status === 0; } catch { return false; } };
+const realInstall = () => { try { return spawnSync('npm', ['install', '-g', 'opencode-ai'], { stdio: 'inherit' }).status === 0; } catch { return false; } };
+const realLaunch = ({ cwd, model, passthrough }) => {
+  const a = [...(model ? ['-m', model] : []), ...(passthrough || [])];
+  const r = spawnSync('opencode', a, { cwd, stdio: 'inherit' });
+  return r.status ?? 0;
+};
+// Synchronous y/n. Only reached when opencode is missing AND not --yes; the deps
+// seam means tests never call this. Default to 'y' if stdin can't be read.
+function realPrompt(q) {
+  process.stdout.write(`${q} `);
+  try { const b = Buffer.alloc(8); const n = readSync(0, b, 0, 8, null); return b.toString('utf8', 0, n).trim().toLowerCase().startsWith('n') ? 'n' : 'y'; }
+  catch { return 'y'; }
+}
+
+/**
+ * `zuzuu code [dir] [--model M] [--yes] [-- …opencode args]`
+ * @returns process exit code (number) — bin calls process.exit(code(args)).
+ */
+export function code(args = {}, deps = {}) {
+  const d = {
+    detect: realDetect,
+    install: realInstall,
+    launch: realLaunch,
+    prompt: realPrompt,
+    runInit: (dir) => inDir(dir, () => init({ _: [] })),
+    runEnable: (dir) => inDir(dir, () => enable({ host: 'opencode', quiet: true })),
+    log: (...m) => console.log(...m),
+    ...deps,
+  };
+
+  // 1. resolve the project dir
+  const dir = args._?.[0] ? resolve(String(args._[0])) : process.cwd();
+  if (!existsSync(dir)) { d.log(`zuzuu code: no such directory: ${dir}`); return 1; }
+
+  // 2. ensure the faculty home (only when absent — keeps output clean; init is idempotent)
+  if (!homeExists(repoRoot(dir))) d.runInit(dir);
+
+  // 3. ensure OpenCode (detect + install-on-demand)
+  if (!d.detect()) {
+    d.log("OpenCode isn't installed.");
+    const consent = args.yes || args.y || d.prompt('Install it now? (npm i -g opencode-ai) [Y/n]') !== 'n';
+    if (!consent || !d.install() || !d.detect()) {
+      d.log('Install it with:  npm i -g opencode-ai');
+      return 1;
+    }
+  }
+
+  // 4. ensure the zuzuu plugin (capture + gate + digest) — FAIL-OPEN: never block the launch
+  let wired = true;
+  try { d.runEnable(dir); } catch (e) { wired = false; d.log(`zuzuu code: could not wire the zuzuu plugin (${e?.message || e}) — launching unwired.`); }
+
+  // a clean one-screen summary of what the newcomer just got (vs. the verbose enable output)
+  d.log('zuzuu code → OpenCode, faculty-equipped');
+  d.log(`  ✓ faculty home (agent/)   ${wired ? '✓ capture + guardrails gate   ✓ session grounding' : '⚠ plugin not wired (degraded)'}`);
+  d.log(`  → launching OpenCode in ${dir} …`);
+
+  // 5. launch the real OpenCode (configure + launch, never drive)
+  return d.launch({ cwd: dir, model: args.model || null, passthrough: args['--'] || [] });
+}

package/zuzuu/commands/digest.mjs

@@ -0,0 +1,23 @@
+// zuzuu/commands/digest.mjs
+// `zuzuu digest [--json] [--budget N]` — print the grounding brief a session
+// start would inject. Lets a human (or a hookless host) see exactly what the
+// agent sees.
+
+import { paths } from '../store.mjs';
+import { computeDigest } from '../digest.mjs';
+
+/** Pure: the digest payload — the zuzuu-web /digest source (the daemon also reads agent/.live/digest.md directly). */
+export function digestData(agentDir, opts = {}) {
+  const d = computeDigest(agentDir, opts);
+  return { text: d.text ?? '' };
+}
+
+export function digest(args) {
+  const agentDir = paths().dir;
+  const opts = {};
+  // guard `--budget` with no value (parseArgs → true → Number(true)===1 → near-empty digest)
+  if (args.budget && args.budget !== true) opts.budget = Number(args.budget);
+  const d = computeDigest(agentDir, opts);
+  if (args.json) console.log(JSON.stringify(d, null, 2));
+  else process.stdout.write(d.text);
+}

package/zuzuu/commands/distill.mjs

@@ -0,0 +1,46 @@
+// `zuzuu distill` — mine real sessions into proposals (source A).
+//
+// Default: knowledge only (back-compat, via distillSessions). With
+// `--all-faculties`: mine each transcript ONCE into a superset, then run every
+// registered faculty miner (knowledge today; actions/guardrails/instructions/
+// memory land in later WS5 tasks) over the shared sessions array.
+
+import { paths } from '../store.mjs';
+import { distillSessions, transcriptsFor, mineHostSession } from '../knowledge/distill.mjs';
+import * as registry from '../miners/registry.mjs';
+// Import miner modules so they self-register.
+import '../miners/knowledge.mjs';
+import '../miners/actions.mjs';
+import '../miners/guardrails.mjs';
+import '../miners/instructions.mjs';
+import '../miners/memory.mjs';
+
+export function distill(args) {
+  const scope = args.all ? 'all' : args.session ? null : 'last';
+  const pairs = transcriptsFor({ scope: scope ?? 'all', session: args.session || null, cwd: process.cwd() });
+  if (!pairs.length) {
+    console.error('no sessions found to distill (no detected-host transcripts for this project)');
+    process.exit(2);
+  }
+  const agentDir = paths().dir;
+
+  if (args['all-faculties'] || args.allFaculties) {
+    const sessions = pairs.map(mineHostSession).filter(Boolean);
+    const hosts = new Set(sessions.map((s) => s.host));
+    console.log(`distilled ${sessions.length} session(s) across ${hosts.size} host(s) and ${registry.all().length} faculty miner(s):`);
+    let total = 0;
+    for (const miner of registry.all()) {
+      const cand = miner.aggregate(sessions, {});
+      const n = miner.propose(agentDir, cand);
+      total += n;
+      console.log(`  ${miner.faculty.padEnd(12)} ${n} proposal(s)`);
+    }
+    if (total) console.log('next: zuzuu review');
+    return;
+  }
+
+  const r = distillSessions(agentDir, pairs);
+  console.log(`distilled ${r.sessionsMined} session(s) → ${r.proposals.length} proposal(s)${r.registryProposals.length ? ` (+${r.registryProposals.length} registry)` : ''}`);
+  for (const p of r.proposals) console.log(`  ${p.er.verdict.padEnd(9)} ${p.id}`);
+  if (r.proposals.length) console.log('next: zuzuu review');
+}