@zuzuucodes/cli 1.0.0

package/experiments/experiment-1-trace-capture/core/event.mjs

@@ -0,0 +1,58 @@
+// The normalized Event — the host-agnostic vocabulary of a run.
+//
+// This is the seam entire.io calls "one Event": every HostAdapter normalizes its
+// native log into Events, and the core turns Events into OTel spans. Nothing here
+// knows about Claude Code, Gemini, or OpenTelemetry wire format — swap either side
+// without touching this. The README calls this normalized Event "the basis of our
+// trace-span schema."
+//
+// An Event is a span-precursor. Its tree position is expressed purely by ids:
+//   refId       — stable unique id of THIS event within the trace
+//   parentRefId — refId of its parent, or null for the root
+// The core wires parent_span_id = spanId(parentRefId); adapters never compute spans.
+
+/** Semantic kinds. Adapters express as rich a tree as the host's log allows. */
+export const EventKind = Object.freeze({
+  SESSION: 'session', // the root: one host session
+  TURN: 'turn', // one user-prompt -> response cycle (a Run/Episode boundary)
+  TOOL_CALL: 'tool_call', // one tool invocation
+});
+
+export const Status = Object.freeze({ UNSET: 'unset', OK: 'ok', ERROR: 'error' });
+
+/**
+ * @param {object} e
+ * @param {string} e.kind         one of EventKind
+ * @param {string} e.refId        stable unique id within the trace
+ * @param {string|null} e.parentRefId  parent's refId, or null for root
+ * @param {string} e.name         span name
+ * @param {number} e.startMs      epoch ms (span start)
+ * @param {number} [e.endMs]      epoch ms (span end); defaults to startMs (zero-duration)
+ * @param {string} [e.status]     one of Status; default UNSET
+ * @param {object} [e.attributes] flat key->value (string|number|boolean)
+ */
+export function event({ kind, refId, parentRefId = null, name, startMs, endMs, status = Status.UNSET, attributes = {} }) {
+  if (!refId) throw new Error(`event: refId required (kind=${kind}, name=${name})`);
+  return {
+    kind,
+    refId: String(refId),
+    parentRefId: parentRefId == null ? null : String(parentRefId),
+    name: name ?? kind,
+    startMs: Number(startMs) || 0,
+    endMs: endMs == null ? Number(startMs) || 0 : Number(endMs),
+    status,
+    attributes,
+  };
+}
+
+/**
+ * A normalized trace as produced by an adapter.
+ * @param {object} t
+ * @param {string} t.host       adapter name, e.g. "claude-code"
+ * @param {string} t.sessionId  the host's session identifier
+ * @param {string} [t.title]    human label
+ * @param {Event[]} t.events    exactly one SESSION root + descendants
+ */
+export function trace({ host, sessionId, title = '', events }) {
+  return { host, sessionId: String(sessionId), title, events };
+}

package/experiments/experiment-1-trace-capture/core/ids.mjs

@@ -0,0 +1,32 @@
+// W3C TraceContext id generation — host-agnostic.
+//
+// trace_id = 16 bytes (32 hex), span_id = 8 bytes (16 hex). We derive them
+// DETERMINISTICALLY from stable inputs (host+sessionId, and the event's refId)
+// so that re-capturing the same host log yields the same trace — captures are
+// idempotent, and a span's parent_span_id is just `spanId(parentRefId)` with no
+// lookup table. Determinism is a property of static-log parsing; a live tracer
+// would use crypto.randomBytes instead.
+
+import { createHash } from 'node:crypto';
+
+/** Lowercase hex of the first `bytes` bytes of sha256(parts.join('\0')). */
+function hashHex(bytes, ...parts) {
+  return createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, bytes * 2);
+}
+
+/** 32-hex-char trace id, stable per (host, sessionId). Never all-zero. */
+export function traceId(host, sessionId) {
+  const id = hashHex(16, 'trace', host, sessionId);
+  return id === '0'.repeat(32) ? '0'.repeat(31) + '1' : id;
+}
+
+/** 16-hex-char span id, stable per (traceId, refId). Never all-zero. */
+export function spanId(traceIdHex, refId) {
+  const id = hashHex(8, 'span', traceIdHex, refId);
+  return id === '0'.repeat(16) ? '0'.repeat(15) + '1' : id;
+}
+
+/** W3C `traceparent` header value: version-traceid-spanid-flags (sampled). */
+export function traceparent(traceIdHex, spanIdHex) {
+  return `00-${traceIdHex}-${spanIdHex}-01`;
+}

package/experiments/experiment-1-trace-capture/core/otlp.mjs

@@ -0,0 +1,54 @@
+// Spans -> OTLP/JSON ExportTraceServiceRequest, and NDJSON writer.
+//
+// Output format: one COMPLETE OTLP/JSON request per line
+//   { "resourceSpans": [ { "resource": {...}, "scopeSpans": [ { "scope": {...}, "spans": [...] } ] } ] }
+// This is exactly what the OpenTelemetry Collector `otlpjsonfilereceiver` ingests
+// (newline-delimited ExportTraceServiceRequest objects) — so a trace we write
+// locally today is replayable into any OTel backend later, no converter.
+//
+// NOTE: verify the precise nesting against the receiver spec before claiming
+// drop-in interop for an external consumer (tracked in the experiment README’s Conclusions).
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const SCOPE = { name: 'zuzuu/trace-capture', version: '0.1.0' };
+
+function strAttr(key, value) {
+  return { key, value: { stringValue: String(value) } };
+}
+
+/**
+ * Wrap spans into one ExportTraceServiceRequest.
+ * @param {{traceId:string, spans:object[]}} built  from eventsToSpans()
+ * @param {{host:string, sessionId:string}} meta
+ */
+export function toExportRequest(built, meta) {
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            strAttr('service.name', 'zuzuu'),
+            strAttr('service.version', '0.1.0'),
+            strAttr('host.name', meta.host), // which host CLI this trace was observed from
+            strAttr('session.id', meta.sessionId),
+          ],
+        },
+        scopeSpans: [{ scope: SCOPE, spans: built.spans }],
+      },
+    ],
+  };
+}
+
+/** Serialize one or more export requests as NDJSON (one request per line). */
+export function toNdjson(requests) {
+  return requests.map((r) => JSON.stringify(r)).join('\n') + '\n';
+}
+
+/** Write NDJSON to disk, creating parent dirs. Returns the path. */
+export function writeNdjson(path, requests) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, toNdjson(requests));
+  return path;
+}

package/experiments/experiment-1-trace-capture/core/render.mjs

@@ -0,0 +1,63 @@
+// Render an OTLP/JSON trace file as a span tree. Shared by the experiment's
+// inspect-trace CLI and the app-level `mns trace` command.
+
+import { readFileSync } from 'node:fs';
+
+const MARK = { 0: '•', 1: '•', 2: '✗' };
+
+/** Load all spans (+ first resource attrs) from an OTLP/JSON NDJSON file. */
+export function loadSpans(file) {
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const spans = [];
+  const resources = [];
+  for (const line of lines) {
+    const req = JSON.parse(line);
+    for (const rs of req.resourceSpans || []) {
+      resources.push(Object.fromEntries((rs.resource?.attributes || []).map((a) => [a.key, a.value?.stringValue])));
+      for (const ss of rs.scopeSpans || []) for (const s of ss.spans || []) spans.push(s);
+    }
+  }
+  return { spans, resource: resources[0] || {} };
+}
+
+// nanosecond strings exceed Number.MAX_SAFE_INTEGER — use BigInt for durations.
+const durMs = (s) => Number((BigInt(s.endTimeUnixNano) - BigInt(s.startTimeUnixNano)) / 1_000_000n);
+
+function fmtDur(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}
+
+/** Build a printable span-tree string from { spans, resource }. */
+export function renderTree({ spans, resource = {} }) {
+  if (!spans.length) return '(no spans)';
+
+  const byId = new Map(spans.map((s) => [s.spanId, s]));
+  const children = new Map();
+  const roots = [];
+  for (const s of spans) {
+    const parent = s.parentSpanId && byId.has(s.parentSpanId) ? s.parentSpanId : null;
+    if (parent) {
+      if (!children.has(parent)) children.set(parent, []);
+      children.get(parent).push(s);
+    } else roots.push(s);
+  }
+  const sortByStart = (a, b) => (BigInt(a.startTimeUnixNano) < BigInt(b.startTimeUnixNano) ? -1 : 1);
+
+  const lines = [];
+  lines.push(`host=${resource['host.name'] || '?'}  session=${resource['session.id'] || '?'}  trace=${spans[0].traceId}`);
+  lines.push(`spans=${spans.length}\n`);
+
+  function walk(s, depth) {
+    const pad = '  '.repeat(depth);
+    const err = s.status?.code === 2 ? '  [ERROR]' : '';
+    lines.push(`${pad}${MARK[s.status?.code || 0]} ${s.name}  ${fmtDur(durMs(s))}${err}`);
+    (children.get(s.spanId) || []).sort(sortByStart).forEach((c) => walk(c, depth + 1));
+  }
+  roots.sort(sortByStart).forEach((r) => walk(r, 0));
+
+  const errors = spans.filter((s) => s.status?.code === 2).length;
+  lines.push(`\n${spans.length} spans, ${errors} error(s)`);
+  return lines.join('\n');
+}

package/experiments/experiment-1-trace-capture/core/spans.mjs

@@ -0,0 +1,43 @@
+// Event[] -> OpenTelemetry spans (data model). Host-agnostic: pure id-wiring.
+
+import { traceId, spanId } from './ids.mjs';
+import { Status } from './event.mjs';
+
+// OTLP status codes: 0 UNSET, 1 OK, 2 ERROR.
+const STATUS_CODE = { [Status.UNSET]: 0, [Status.OK]: 1, [Status.ERROR]: 2 };
+// SpanKind 1 = INTERNAL (we observe, we don't classify client/server here).
+const SPAN_KIND_INTERNAL = 1;
+
+const msToUnixNano = (ms) => String(Math.round(ms) * 1_000_000);
+
+/** Encode a JS value as an OTLP/JSON AnyValue-wrapped attribute. */
+function attr(key, value) {
+  let v;
+  if (typeof value === 'boolean') v = { boolValue: value };
+  else if (typeof value === 'number') v = Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  else v = { stringValue: String(value) };
+  return { key, value: v };
+}
+
+/**
+ * @param {import('./event.mjs').trace} t  normalized trace from an adapter
+ * @returns {{ traceId: string, spans: object[] }} OTLP/JSON span objects
+ */
+export function eventsToSpans(t) {
+  const tid = traceId(t.host, t.sessionId);
+  const spans = t.events.map((e) => {
+    const span = {
+      traceId: tid,
+      spanId: spanId(tid, e.refId),
+      name: e.name,
+      kind: SPAN_KIND_INTERNAL,
+      startTimeUnixNano: msToUnixNano(e.startMs),
+      endTimeUnixNano: msToUnixNano(e.endMs),
+      attributes: Object.entries(e.attributes).map(([k, v]) => attr(k, v)),
+      status: { code: STATUS_CODE[e.status] ?? 0 },
+    };
+    if (e.parentRefId != null) span.parentSpanId = spanId(tid, e.parentRefId);
+    return span;
+  });
+  return { traceId: tid, spans };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@zuzuucodes/cli",
+  "version": "1.0.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Give the coding agent you already run (Claude Code, Codex, Gemini CLI, OpenCode) evolving faculties — knowledge, memory, actions, instructions, guardrails — with host-agnostic OpenTelemetry session tracing. Zero dependencies.",
+  "keywords": [
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "opencode",
+    "opentelemetry",
+    "observability",
+    "tracing",
+    "guardrails",
+    "agent-memory",
+    "cli"
+  ],
+  "homepage": "https://github.com/h1902y/zuzuu#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h1902y/zuzuu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/h1902y/zuzuu/issues"
+  },
+  "license": "MIT",
+  "author": "Harshit Krishna Choudhary (https://x.com/h1902y)",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "zz": "bin/zuzuu.mjs",
+    "zuzuu": "bin/zuzuu.mjs"
+  },
+  "files": [
+    "bin/",
+    "zuzuu/",
+    "experiments/experiment-1-trace-capture/core/",
+    "experiments/experiment-1-trace-capture/adapters/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "zuzuu": "node bin/zuzuu.mjs",
+    "capture": "node experiments/experiment-1-trace-capture/bin/capture.mjs",
+    "inspect": "node experiments/experiment-1-trace-capture/bin/inspect-trace.mjs",
+    "test": "node --test 'tests/**/*.test.mjs'",
+    "playground": "node tests/playground/run.mjs",
+    "prepublishOnly": "npm test"
+  }
+}

package/zuzuu/actions/adapter.mjs

@@ -0,0 +1,130 @@
+// zuzuu/actions/adapter.mjs
+// The Actions faculty adapter (WS2-T3). Wraps the EXISTING Actions inbox gate
+// (proposed dirs under agent/actions/inbox/<slug>/) behind the faculty-spine
+// adapter contract — { name, ingest, validate, apply, render } — so the generic
+// `zuzuu review` gate can drive Actions the same way it drives Knowledge.
+//
+// Actions payloads are DIRECTORIES (run.mjs/SKILL.md + action.json), not JSON.
+// Strategy (lowest-risk): the inbox stays a dir; this adapter emits/reads a
+// spine-shaped proposal RECORD that REFERENCES the dir
+// (payload = { slug, kind, dir:'inbox/<slug>' }). The gate resolves a single
+// record via `getProposal`, lists pending via `listProposals`, and — because
+// the payload is dir-shaped — archives rejections via `rejectDir` (a dir move
+// into actions/proposals/archive/, not a JSON archive).
+//
+// Registers itself on import.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { listActions, inboxDir, isSafeSlug } from './manifest.mjs';
+import { activateAction, rejectAction } from './inbox.mjs';
+import { validateInputs } from './schema.mjs';
+import * as registry from '../faculty/registry.mjs';
+
+const name = 'actions';
+
+/** Build a spine-shaped proposal record for one proposed action. */
+function recordFor(a) {
+  return {
+    id: a.slug,
+    faculty: name,
+    kind: 'action',
+    status: 'pending',
+    source: 'agent',
+    payload: { slug: a.slug, kind: a.kind, dir: `inbox/${a.slug}` },
+    // carry render hints alongside the payload (cheap, dir read already done)
+    title: a.title,
+    promptSnippet: a.promptSnippet,
+    analysis: {},
+    evidence: {},
+    provenance: [],
+  };
+}
+
+/**
+ * Pending action proposals (dirs in agent/actions/inbox/), surfaced as
+ * spine-shaped records so the gate can render/approve/reject them uniformly.
+ */
+function listProposals(agentDir) {
+  return listActions(inboxDir(agentDir)).map(recordFor);
+}
+
+/** Resolve a single proposed action by slug → spine-shaped record, or null. */
+function getProposal(agentDir, slug) {
+  if (!isSafeSlug(slug)) return null;
+  return listProposals(agentDir).find((p) => p.id === slug) ?? null;
+}
+
+/**
+ * Ingest is a pass-through for Actions: proposing scaffolds a dir
+ * (zuzuu act propose / act-author). Kept for adapter-contract symmetry.
+ */
+function ingest(_agentDir, raw) {
+  return { payload: raw?.payload ?? raw ?? {}, analysis: {} };
+}
+
+/**
+ * Validate a proposed action's manifest against the schema subset and confirm
+ * the manifest slug matches the dir. Missing manifest → accept (slug fallback).
+ * @returns {{ok:boolean, errors:string[], warnings:string[]}}
+ */
+function validate(agentDir, payload) {
+  const slug = payload?.slug;
+  if (!isSafeSlug(slug)) return { ok: false, errors: [`invalid slug '${slug}'`], warnings: [] };
+  const manPath = join(inboxDir(agentDir), slug, 'action.json');
+  if (!existsSync(manPath)) return { ok: true, errors: [], warnings: [] };
+  let man;
+  try { man = JSON.parse(readFileSync(manPath, 'utf8')); }
+  catch { return { ok: false, errors: ['manifest is not valid JSON'], warnings: [] }; }
+  if (man.slug && man.slug !== slug) return { ok: false, errors: [`manifest slug '${man.slug}' ≠ dir '${slug}'`], warnings: [] };
+  const errors = [];
+  // the manifest schema is itself JSON-Schema-subset shaped; sanity-check both ends
+  if (man.inputs) {
+    const vi = validateInputs(man.inputs, man.default_args, {});
+    // inputs schema is for caller args, not the manifest — only flag a structurally
+    // broken schema (validateInputs is permissive on empty args), so this is a no-op
+    // for well-formed manifests. Kept for symmetry with the knowledge adapter.
+    if (vi.ok === false && !/required/i.test(vi.error ?? '')) errors.push(vi.error);
+  }
+  if (man.outputs && typeof man.outputs !== 'object') errors.push('outputs schema must be an object');
+  return { ok: errors.length === 0, errors, warnings: [] };
+}
+
+/**
+ * Apply an approved action proposal: activate it (move inbox/<slug> → <slug>).
+ * Preserves the "already exists" guard from activateAction.
+ * @returns {{ok:boolean, action:string, itemIds:string[], warnings:string[]}}
+ */
+function apply(agentDir, proposal) {
+  const slug = proposal?.payload?.slug ?? proposal?.id;
+  const r = activateAction(agentDir, slug);
+  if (!r.ok) return { ok: false, action: r.error, itemIds: [], warnings: [] };
+  return { ok: true, action: `activated ${slug}`, itemIds: [slug], warnings: [] };
+}
+
+/**
+ * Reject path: dir-shaped, so the gate calls this instead of the JSON archive.
+ * Moves inbox/<slug> → actions/proposals/archive/<slug> (archive, not delete).
+ */
+function rejectDir(agentDir, slug, _reason = '') {
+  return rejectAction(agentDir, slug);
+}
+
+/**
+ * Render a proposed action for the human gate. `card` mirrors the current review
+ * card (slug ── kind, then the prompt snippet); `line` is the one-line list form.
+ * @returns {{line:string, card:string}}
+ */
+function render(proposal) {
+  const slug = proposal?.id ?? proposal?.payload?.slug ?? '';
+  const kind = proposal?.payload?.kind ?? proposal?.kind ?? 'action';
+  const snippet = proposal?.promptSnippet ?? '';
+  return {
+    line: `${slug}  [${kind}]  ${snippet}`,
+    card: `${slug} ── ${kind}\n  ${snippet}`,
+  };
+}
+
+export const adapter = { name, ingest, validate, apply, render, listProposals, getProposal, rejectDir };
+
+registry.register(adapter);

package/zuzuu/actions/convert.mjs

@@ -0,0 +1,27 @@
+// zuzuu/actions/convert.mjs
+// Pure manifest → tool-definition converters (the _labs tool-definition pattern).
+// The manifest's `inputs` JSON Schema is already the right shape for each format,
+// so conversion is a thin re-wrap.
+//
+// STATUS (2026-06-11): used today only by `zuzuu act schema <slug> [--mcp|--openai|
+// --anthropic]` for inspection. There is NO runtime MCP/native-tool *serving* yet —
+// actions are invoked via `zuzuu act <slug>` from the host shell and surfaced to the
+// agent in the digest. Live "Actions over MCP" serving is DEFERRED (DESIGN §6 /
+// Stage 2 / OpenCode bundle); these converters are the seam for it, not the thing.
+
+const desc = (m) => m.description ?? m.title ?? m.slug;
+const inputs = (m) => m.inputs ?? { type: 'object' };
+
+export function toMcpTool(m) {
+  const t = { name: m.slug, description: desc(m), inputSchema: inputs(m) };
+  if (m.outputs) t.outputSchema = m.outputs;
+  return t;
+}
+
+export function toOpenAITool(m) {
+  return { type: 'function', function: { name: m.slug, description: desc(m), parameters: inputs(m) } };
+}
+
+export function toAnthropicTool(m) {
+  return { name: m.slug, description: desc(m), input_schema: inputs(m) };
+}

package/zuzuu/actions/dispatch.mjs

@@ -0,0 +1,87 @@
+// zuzuu/actions/dispatch.mjs
+// runAction spawns the runner harness (a fresh node process — isolation + the
+// _labs marker pattern), extracts the single result marker from stdout, and
+// returns { ok, value|error, detail?, logs }. zuzuu act is itself spawned by the
+// host's Bash, so this is observe-not-drive: a CLI the agent calls, never a loop.
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadManifest, actionsDir } from './manifest.mjs';
+import { MARKER } from './marker.mjs';
+
+const MAX_DEPTH = 8;
+const MAX_BYTES = 50_000;
+const MAX_LINES = 2000;
+const ACTION_TIMEOUT_MS = 60_000;
+const runnerPath = join(dirname(fileURLToPath(import.meta.url)), 'runner.mjs');
+
+function truncate(s) {
+  let out = s;
+  if (out.length > MAX_BYTES) out = out.slice(0, MAX_BYTES) + '\n…[truncated]';
+  const lines = out.split('\n');
+  if (lines.length > MAX_LINES) out = lines.slice(0, MAX_LINES).join('\n') + '\n…[truncated]';
+  return out;
+}
+
+function parseOutput(stdout) {
+  const lines = stdout.split('\n');
+  let parsed = null;
+  const logLines = [];
+  for (const line of lines) {
+    if (line.startsWith(MARKER)) {
+      try { parsed = JSON.parse(line.slice(MARKER.length)); } catch { /* keep last good */ }
+    } else {
+      logLines.push(line);
+    }
+  }
+  return { parsed, logs: logLines.join('\n').trim() };
+}
+
+/**
+ * Run an action by slug. Returns:
+ *   { ok:true, value, logs } | { ok:false, error, detail?, logs }
+ * error ∈ depth_exceeded | not_found | not_runnable | invalid_input |
+ *         invalid_output | script_error | no_result | timeout | spawn_error | killed
+ */
+// Synchronous (spawnSync). Returns the result object directly.
+export function runAction(agentDir, slug, callerArgs = {}, { timeoutMs = ACTION_TIMEOUT_MS } = {}) {
+  const depth = Number(process.env.ZUZUU_ACT_DEPTH || 0);
+  if (depth >= MAX_DEPTH) return { ok: false, error: 'depth_exceeded', detail: `depth ${depth} ≥ ${MAX_DEPTH}`, logs: '' };
+
+  const manifest = loadManifest(agentDir, slug);
+  if (!manifest) return { ok: false, error: 'not_found', detail: `no action '${slug}' (missing action.json)`, logs: '' };
+
+  const runPath = join(actionsDir(agentDir), slug, 'run.mjs');
+  if (!existsSync(runPath)) return { ok: false, error: 'not_runnable', detail: `'${slug}' has no run.mjs`, logs: '' };
+
+  const payload = JSON.stringify({
+    runPath,
+    inputs: manifest.inputs ?? { type: 'object' },
+    outputs: manifest.outputs ?? { type: 'object' },
+    default_args: manifest.default_args ?? {},
+    args: callerArgs ?? {},
+  });
+
+  const res = spawnSync(process.execPath, [runnerPath, payload], {
+    cwd: agentDir,
+    encoding: 'utf8',
+    env: { ...process.env, ZUZUU_ACT_DEPTH: String(depth + 1) },
+    maxBuffer: 64 * 1024 * 1024,
+    timeout: timeoutMs,
+    killSignal: 'SIGTERM',
+  });
+
+  if (res.error) {
+    const timedOut = res.error.code === 'ETIMEDOUT';
+    return { ok: false, error: timedOut ? 'timeout' : 'spawn_error', detail: timedOut ? `action exceeded ${timeoutMs}ms` : res.error.message, logs: '' };
+  }
+  if (res.signal) return { ok: false, error: 'killed', detail: `child killed by ${res.signal}`, logs: '' };
+
+  const { parsed, logs: outLogs } = parseOutput(res.stdout || '');
+  const errText = (res.stderr || '').trim();
+  const logs = truncate([outLogs, errText].filter(Boolean).join('\n'));
+  if (!parsed) return { ok: false, error: 'no_result', detail: 'action emitted no result marker', logs };
+  return { ...parsed, logs };
+}

package/zuzuu/actions/inbox.mjs

@@ -0,0 +1,56 @@
+// zuzuu/actions/inbox.mjs
+// The Actions crystallization gate (the same governed pipeline as Knowledge
+// promotion, kept out of the knowledge ER/registry machinery). A proposed action
+// is a real dir under agent/actions/inbox/<slug>/. A human activates it (move to
+// agent/actions/<slug>/) or rejects it (remove). Never auto-activates.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, renameSync, mkdirSync, rmSync } from 'node:fs';
+import { actionsDir, inboxDir, listActions, isSafeSlug } from './manifest.mjs';
+
+/** Archive dir for rejected action proposals: agent/actions/proposals/archive/. */
+const archiveBaseDir = (agentDir) => join(actionsDir(agentDir), 'proposals', 'archive');
+
+/** Proposed actions awaiting review (in agent/actions/inbox/). */
+export function listProposedActions(agentDir) {
+  return listActions(inboxDir(agentDir));
+}
+
+/**
+ * Activate a proposed action: validate, then move inbox/<slug> → actions/<slug>.
+ * @returns {{ok:true} | {ok:false, error:string}}
+ */
+export function activateAction(agentDir, slug) {
+  if (!isSafeSlug(slug)) return { ok: false, error: `invalid slug '${slug}'` };
+  const from = join(inboxDir(agentDir), slug);
+  const to = join(actionsDir(agentDir), slug);
+  if (!existsSync(from)) return { ok: false, error: `no proposed action '${slug}'` };
+  if (existsSync(to)) return { ok: false, error: `an active action '${slug}' already exists — reject or rename first` };
+  const manPath = join(from, 'action.json');
+  if (existsSync(manPath)) {
+    let man;
+    try { man = JSON.parse(readFileSync(manPath, 'utf8')); }
+    catch { return { ok: false, error: `manifest is not valid JSON` }; }
+    if (man.slug && man.slug !== slug) return { ok: false, error: `manifest slug '${man.slug}' ≠ dir '${slug}'` };
+  }
+  renameSync(from, to);
+  return { ok: true };
+}
+
+/**
+ * Reject a proposed action: ARCHIVE its dir (move inbox/<slug> →
+ * actions/proposals/archive/<slug>), never destroy it (WS2-T3). An auditable
+ * history mirrors the Knowledge gate's archive-on-reject.
+ */
+export function rejectAction(agentDir, slug) {
+  if (!isSafeSlug(slug)) return { ok: false, error: `invalid slug '${slug}'` };
+  const from = join(inboxDir(agentDir), slug);
+  if (!existsSync(from)) return { ok: false, error: `no proposed action '${slug}'` };
+  const archBase = archiveBaseDir(agentDir);
+  mkdirSync(archBase, { recursive: true });
+  const to = join(archBase, slug);
+  // if a prior rejection of the same slug exists, clear it so the move succeeds
+  if (existsSync(to)) rmSync(to, { recursive: true, force: true });
+  renameSync(from, to);
+  return { ok: true };
+}