feat: opt-in local audit log (AUDIT_ENABLED) — domain-owned adapters

The audit log in trunk, in the adapter shape: src/audit/ is a domain-free
leaf (canonical event schema, single emit seam with the one opt-in check,
append-only NDJSON day-file store, reader, retention prune, redactor, and
registerAuditHook post-write hooks for in-process exporters). What gets
audited lives in domain-owned *.audit.ts adapters beside the code they
observe — dispatch middleware, requestApproval decorator, approval-resolved
observer, OneCLI credential wrappers, permissions card decisions, ungated
create-agent — each composed at its module edge in one line on the seam
contracts from the previous commit. Business logic contains zero audit
calls: grep emitAuditEvent outside src/audit/ + *.audit.ts is empty, and
the audit module imports nothing from src/cli/ or src/modules/.

Off by default: nothing is persisted until AUDIT_ENABLED=true; a disabled
box answers ncl audit list with a clear error. Enabled boxes refuse to
boot if data/audit/ isn't writable, appends are fail-open + loud, and
AUDIT_RETENTION_DAYS (default 90, 0 = forever) hard-deletes day-files at
boot + once daily in the host sweep. Exporters/forwarders stay out of
core — they plug into registerAuditHook (skill territory), fired only
after a successful local append.

Zero new dependencies. 664 tests pass (595 base + 69 audit, including an
AST wiring test for the two boot-path integration points).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

@@ -71,7 +71,7 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
 | `src/command-gate.ts` | Router-side admin command gate — queries `user_roles` directly (no env var, no container-side check) |
 | `src/modules/approvals/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |
 | `src/modules/permissions/user-dm.ts` | Cold-DM resolution + `user_dms` cache |
-| `src/audit/` | Opt-in local audit log (`AUDIT_ENABLED=true`): single emit seam + wrappers composed at module edges (dispatch middleware, `requestApproval` decorator, approval-resolved observer, permissions/OneCLI/create-agent seams), append-only NDJSON day-files under `data/audit/`, retention prune, `ncl audit` reader, and `registerAuditHook` — post-write hooks for in-process exporters (fire only after a successful local append). See the "Local Audit Log" section in [docs/SECURITY.md](docs/SECURITY.md) |
+| `src/audit/` | Opt-in local audit log (`AUDIT_ENABLED=true`): a domain-free leaf — emit seam, append-only NDJSON day-files under `data/audit/`, retention prune, `ncl audit` reader, and `registerAuditHook` post-write hooks for in-process exporters (fire only after a successful local append). What gets audited lives in domain-owned `*.audit.ts` adapters beside the code they observe (dispatch middleware, `requestApproval` decorator, approval-resolved observer, permissions/OneCLI/create-agent seams), each composed at its module edge in one line. See the "Local Audit Log" section in [docs/SECURITY.md](docs/SECURITY.md) |
 | `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |
 | `src/db/container-configs.ts` | CRUD for `container_configs` table (per-group container runtime config) |
 | `src/backfill-container-configs.ts` | Migrates legacy `container.json` files into the DB on startup |

src/audit-wiring.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Wiring test for the audit log's two boot-path integration points.
+ *
+ * One colocated block lives in src/index.ts (dynamic import of
+ * the self-registering approvals observer + `initAuditLog()`), and one in
+ * src/host-sweep.ts (`maintainAudit()` inside the sweep, fail-isolated). A
+ * behavioral test can't see whether those edits are present and correctly
+ * placed — booting the real host is too heavy — so this asserts them
+ * structurally, via the TypeScript AST:
+ *   - the observer module is dynamically imported by its correct path and
+ *     initAuditLog() runs after it (registration before enablement),
+ *   - both are DIRECT statements of main()'s body, after DB init and before
+ *     the boot-complete log,
+ *   - maintainAudit() is called inside sweep() before the reschedule.
+ *
+ * Delete or misplace a block and this goes red. The seam wrappers themselves
+ * are covered behaviorally (dispatch.audit.test.ts and friends).
+ */
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+
+function bodyOf(file: string, fnName: string): { stmts: ts.NodeArray<ts.Statement>; sf: ts.SourceFile } {
+  const source = fs.readFileSync(path.resolve(process.cwd(), file), 'utf8');
+  const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+  let body: ts.NodeArray<ts.Statement> | undefined;
+  sf.forEachChild((n) => {
+    if (ts.isFunctionDeclaration(n) && n.name?.text === fnName && n.body) {
+      body = n.body.statements;
+    }
+  });
+  if (!body) throw new Error(`${fnName}() not found in ${file}`);
+  return { stmts: body, sf };
+}
+
+/** `await import('<path>')` as a bare expression statement. */
+function isAwaitedImportStatement(s: ts.Statement, importPath: string): boolean {
+  return (
+    ts.isExpressionStatement(s) &&
+    ts.isAwaitExpression(s.expression) &&
+    ts.isCallExpression(s.expression.expression) &&
+    s.expression.expression.expression.kind === ts.SyntaxKind.ImportKeyword &&
+    ts.isStringLiteral(s.expression.expression.arguments[0]!) &&
+    (s.expression.expression.arguments[0] as ts.StringLiteral).text === importPath
+  );
+}
+
+/** `const { ... } = await import('<path>')` as a statement. */
+function isDynamicImportBinding(s: ts.Statement, importPath: string): boolean {
+  if (!ts.isVariableStatement(s)) return false;
+  const init = s.declarationList.declarations[0]?.initializer;
+  if (!init || !ts.isAwaitExpression(init) || !ts.isCallExpression(init.expression)) return false;
+  const call = init.expression;
+  if (call.expression.kind !== ts.SyntaxKind.ImportKeyword) return false;
+  const arg = call.arguments[0];
+  return !!arg && ts.isStringLiteral(arg) && arg.text === importPath;
+}
+
+function isBareCall(s: ts.Statement, callee: string): boolean {
+  return (
+    ts.isExpressionStatement(s) &&
+    ts.isCallExpression(s.expression) &&
+    ts.isIdentifier(s.expression.expression) &&
+    s.expression.expression.text === callee
+  );
+}
+
+describe('audit wiring in src/index.ts', () => {
+  it('imports the self-registering observer, then initAuditLog(), colocated in main() after DB init and before the boot-complete log', () => {
+    const { stmts, sf } = bodyOf('src/index.ts', 'main');
+    const observerIdx = stmts.findIndex((s) =>
+      isAwaitedImportStatement(s, './modules/approvals/approvals-observer.audit.js'),
+    );
+    const importIdx = stmts.findIndex((s) => isDynamicImportBinding(s, './audit/index.js'));
+    const callIdx = stmts.findIndex((s) => isBareCall(s, 'initAuditLog'));
+    const migrateIdx = stmts.findIndex((s) => s.getText(sf).includes('runMigrations('));
+    const runningIdx = stmts.findIndex((s) => s.getText(sf).includes("log.info('NanoClaw running')"));
+
+    expect(observerIdx, 'the observer must be dynamically imported in main()').toBeGreaterThanOrEqual(0);
+    expect(importIdx, "dynamic import('./audit/index.js') must be a statement of main()").toBeGreaterThanOrEqual(0);
+    expect(callIdx, 'initAuditLog() must be a statement of main()').toBeGreaterThanOrEqual(0);
+    expect(migrateIdx, 'runMigrations() anchor not found').toBeGreaterThanOrEqual(0);
+    expect(runningIdx, 'boot-complete log anchor not found').toBeGreaterThanOrEqual(0);
+    expect(observerIdx, 'the observer import must come after DB init').toBeGreaterThan(migrateIdx);
+    expect(importIdx, 'the audit import must come after the observer import').toBeGreaterThan(observerIdx);
+    expect(callIdx, 'initAuditLog() must come after its import (colocated)').toBeGreaterThan(importIdx);
+    expect(callIdx, 'initAuditLog() must run before the boot-complete log').toBeLessThan(runningIdx);
+  });
+});
+
+describe('audit wiring in src/host-sweep.ts', () => {
+  it('calls maintainAudit() inside sweep(), fail-isolated, before the reschedule', () => {
+    const { stmts, sf } = bodyOf('src/host-sweep.ts', 'sweep');
+    const auditIdx = stmts.findIndex((s) => ts.isTryStatement(s) && s.getText(sf).includes('maintainAudit()'));
+    const rescheduleIdx = stmts.findIndex((s) => s.getText(sf).includes('setTimeout(sweep'));
+
+    expect(auditIdx, 'a try-wrapped maintainAudit() must be a statement of sweep()').toBeGreaterThanOrEqual(0);
+    expect(rescheduleIdx, 'setTimeout(sweep) anchor not found').toBeGreaterThanOrEqual(0);
+    expect(auditIdx, 'maintainAudit() must run before the sweep reschedules itself').toBeLessThan(rescheduleIdx);
+  });
+});

src/audit/emit.ts

@@ -1,9 +1,9 @@
 /**
  * emitAuditEvent — the single opt-in check and the single append point.
  *
- * Only src/audit/ may call this (wrappers compose it at module edges;
- * business logic never does): `grep emitAuditEvent src/` outside this
- * directory must stay empty.
+ * Only src/audit/ and the domain-owned `*.audit.ts` adapter files may call
+ * this (adapters compose it at their module's edge; business logic never
+ * does): `grep emitAuditEvent src/` outside those files must stay empty.
  */
 import { randomUUID } from 'crypto';
 

src/audit/index.ts

@@ -1,13 +1,17 @@
 /**
  * Opt-in local audit log (docs/SECURITY.md, "Local Audit Log").
  *
- * Everything composes through the wrappers exported here — business logic
- * contains zero audit calls. emitAuditEvent is deliberately NOT re-exported:
- * only src/audit/ internals may call it.
+ * This directory is a domain-free leaf: the event schema, the emit seam, the
+ * store, the reader, post-write hooks, and shared vocabulary. What gets
+ * audited — and how each domain describes itself — lives in the domain-owned
+ * `*.audit.ts` adapter files next to the code they observe. Business logic
+ * contains zero audit calls.
+ *
+ * emitAuditEvent is deliberately NOT re-exported here: adapters import it
+ * from './emit.js' directly, and only src/audit/ + `*.audit.ts` may call it.
  */
 export * from './types.js';
 export { redactDetails } from './redact.js';
 export { AUDIT_DIR } from './store.js';
 export { initAuditLog, maintainAudit } from './init.js';
 export { type AuditHook, registerAuditHook } from './hooks.js';
-export { runApprovedHandler, withAudit } from './wrappers.js';

src/audit/init.ts

@@ -1,9 +1,9 @@
 /**
- * Boot-time audit wiring — one composition line in src/index.ts.
+ * Boot-time audit wiring — composed in src/index.ts alongside the import of
+ * the domain observer (`approvals-observer.audit.ts`, which self-registers).
  *
- * The decision observer registers unconditionally (its emits no-op when
- * disabled). When enabled: assert data/audit/ is writable (refusing to start
- * beats running with a silent audit gap), run the boot prune, and start the
+ * When enabled: assert data/audit/ is writable (refusing to start beats
+ * running with a silent audit gap), run the boot prune, and start the
  * registered post-write hooks' lifecycle (init here, maintain via the host
  * sweep, shutdown via the host's graceful-shutdown registry).
  */
@@ -11,11 +11,9 @@ import { AUDIT_ENABLED, AUDIT_RETENTION_DAYS } from '../config.js';
 import { log } from '../log.js';
 import { onShutdown } from '../response-registry.js';
 import { initAuditHooks, maintainAuditHooks, shutdownAuditHooks } from './hooks.js';
-import { registerAuditObserver } from './observer.js';
 import { assertAuditWritable, AUDIT_DIR, markPrunedToday, pruneAuditLog, pruneAuditLogIfDue } from './store.js';
 
 export function initAuditLog(): void {
-  registerAuditObserver();
   if (!AUDIT_ENABLED) return;
   try {
     assertAuditWritable();

src/audit/mapping.ts

@@ -1,285 +0,0 @@
-/**
- * Event assembly — actors, origins, action names, resources, and the
- * per-surface details rules (including shape-only for message-bearing
- * payloads). Pure derivation; nothing here writes the log.
- */
-import os from 'os';
-
-import { getResource } from '../cli/crud.js';
-import type { CallerContext, RequestFrame } from '../cli/frame.js';
-import { type CommandDef, lookup } from '../cli/registry.js';
-import { getMessagingGroup } from '../db/messaging-groups.js';
-import type { Session } from '../types.js';
-import { type AuditActor, type AuditEventInput, type AuditOrigin, type AuditResource, SYSTEM_ACTOR } from './types.js';
-
-// ── Actors ──
-
-function hostUser(): string {
-  try {
-    return os.userInfo().username;
-    // eslint-disable-next-line no-catch-all/no-catch-all -- os.userInfo throws on exotic hosts; a fallback actor id beats no audit event
-  } catch {
-    return process.env.USER || 'unknown';
-  }
-}
-
-/**
- * Host callers stamp `host:<install user>` daemon-side: the ncl socket is
- * 0600 and owned by the install user, so the identity is accurate by
- * construction without peer credentials.
- */
-export function actorForCaller(ctx: CallerContext): AuditActor {
-  return ctx.caller === 'host' ? { type: 'human', id: `host:${hostUser()}` } : { type: 'agent', id: ctx.agentGroupId };
-}
-
-/** Empty resolver id (sweep/timer paths) → the system actor. */
-export function humanOrSystemActor(namespacedUserId: string): AuditActor {
-  return namespacedUserId ? { type: 'human', id: namespacedUserId } : SYSTEM_ACTOR;
-}
-
-// ── Origins ──
-
-export function originForCaller(ctx: CallerContext): AuditOrigin {
-  if (ctx.caller === 'host') return { transport: 'socket' };
-  return containerOrigin(ctx.sessionId, ctx.messagingGroupId || null);
-}
-
-export function originForSession(session: Session): AuditOrigin {
-  return containerOrigin(session.id, session.messaging_group_id);
-}
-
-function containerOrigin(sessionId: string, messagingGroupId: string | null): AuditOrigin {
-  const origin: AuditOrigin = { transport: 'container', session_id: sessionId };
-  if (messagingGroupId) {
-    origin.messaging_group_id = messagingGroupId;
-    const channel = getMessagingGroup(messagingGroupId)?.channel_type;
-    if (channel) origin.channel = channel;
-  }
-  return origin;
-}
-
-/** Approval decisions arrive as card clicks on a chat platform. */
-export function channelOriginForUser(namespacedUserId: string): AuditOrigin {
-  const idx = namespacedUserId.indexOf(':');
-  const channel = idx > 0 ? namespacedUserId.slice(0, idx) : undefined;
-  return channel ? { transport: 'channel', channel } : { transport: 'channel' };
-}
-
-// ── CLI resources ──
-
-/**
- * Frame-level args use `--hyphen-keys`; recorded details use the same
- * underscore form the parsed handlers see. Mirrors crud's normalizeArgs
- * (kept local so audit doesn't depend on a module tests commonly mock).
- */
-export function normalizeArgKeys(raw: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(raw)) {
-    out[k.replace(/-/g, '_')] = v;
-  }
-  return out;
-}
-
-/** CLI resource plural → audit resource type, where the singular isn't it. */
-const RESOURCE_TYPE_OVERRIDES: Record<string, string> = {
-  groups: 'agent_group',
-  'messaging-groups': 'messaging_group',
-  'dropped-messages': 'dropped_message',
-  'user-dms': 'user_dm',
-};
-
-/**
- * Derive touched/attempted resources from a command's effective args. Generic
- * by design: `id` → the command's own resource, group/user args → their
- * types, and a bare `{type}` entry when nothing else is known (a denied
- * `users list` still names what was attempted).
- */
-export function resourcesForCli(cmd: CommandDef, args: Record<string, unknown>): AuditResource[] {
-  if (!cmd.resource) return [];
-  const type = RESOURCE_TYPE_OVERRIDES[cmd.resource] ?? getResource(cmd.resource)?.name ?? cmd.resource;
-
-  const out: AuditResource[] = [];
-  const push = (t: string, id: unknown): void => {
-    if (typeof id !== 'string' || !id) return;
-    if (!out.some((r) => r.type === t && r.id === id)) out.push({ type: t, id });
-  };
-  push(type, args.id);
-  push('agent_group', args.agent_group_id ?? args.group);
-  push('user', args.user);
-  if (out.length === 0) out.push({ type });
-  return out;
-}
-
-// ── Approval-gated actions ──
-
-/** Dotted audit action per approval type; cli_command derives from its frame. */
-export const APPROVAL_AUDIT_ACTIONS: Record<string, string> = {
-  install_packages: 'self-mod.install-packages',
-  add_mcp_server: 'self-mod.add-mcp-server',
-  create_agent: 'agents.create',
-  a2a_message_gate: 'messages.a2a-gate',
-  onecli_credential: 'onecli.credential.use',
-};
-
-export function auditActionForApproval(approvalAction: string, payload: Record<string, unknown>): string {
-  if (approvalAction === 'cli_command') {
-    const frame = payload.frame as RequestFrame | undefined;
-    return (frame && lookup(frame.command)?.action) ?? 'cli.unknown-command';
-  }
-  return APPROVAL_AUDIT_ACTIONS[approvalAction] ?? approvalAction.replace(/_/g, '.');
-}
-
-/**
- * details for an approval's pending/terminal events. Message-bearing payloads
- * (a2a gate) record shape only — body_chars and attachment names, never
- * content; the emit-seam redactor is defense-in-depth, not the mechanism.
- */
-export function detailsForApprovalPayload(
-  approvalAction: string,
-  payload: Record<string, unknown>,
-): Record<string, unknown> {
-  switch (approvalAction) {
-    case 'cli_command': {
-      const frame = payload.frame as RequestFrame | undefined;
-      return { ...(frame?.args ?? {}) };
-    }
-    case 'create_agent': {
-      const instructions = typeof payload.instructions === 'string' ? payload.instructions : null;
-      return { name: payload.name, instructions_chars: instructions ? instructions.length : 0 };
-    }
-    case 'a2a_message_gate': {
-      const { text, files } = messageShape(payload.content);
-      return { to: payload.platform_id, body_chars: text.length, attachments: files };
-    }
-    default:
-      // install_packages, add_mcp_server, and future types: metadata payloads
-      // pass through as-is — the emit-seam redactor masks sensitive keys.
-      return { ...payload };
-  }
-}
-
-export function resourcesForApproval(
-  approvalAction: string,
-  payload: Record<string, unknown>,
-  session: Session,
-): AuditResource[] {
-  const base: AuditResource[] = [{ type: 'agent_group', id: session.agent_group_id }];
-  if (approvalAction === 'cli_command') {
-    const frame = payload.frame as RequestFrame | undefined;
-    const cmd = frame && lookup(frame.command);
-    if (cmd && frame) {
-      const cliResources = resourcesForCli(cmd, frame.args);
-      for (const r of cliResources) {
-        if (!base.some((b) => b.type === r.type && b.id === r.id)) base.push(r);
-      }
-    }
-  }
-  if (approvalAction === 'a2a_message_gate' && typeof payload.platform_id === 'string' && payload.platform_id) {
-    if (payload.platform_id !== session.agent_group_id) {
-      base.push({ type: 'agent_group', id: payload.platform_id });
-    }
-  }
-  return base;
-}
-
-// ── OneCLI credential approvals ──
-
-/** = APPROVAL_AUDIT_ACTIONS.onecli_credential; named for the OneCLI wrappers. */
-export const ONECLI_AUDIT_ACTION = 'onecli.credential.use';
-
-interface OneCliRowShape {
-  approval_id: string;
-  agent_group_id?: string | null;
-  payload: string;
-}
-
-interface OneCliPayload {
-  oneCliRequestId?: string;
-  method?: string;
-  host?: string;
-  path?: string;
-  bodyPreview?: string;
-  agent?: { externalId?: string | null; name?: string };
-  approver?: string;
-}
-
-function oneCliPayload(row: OneCliRowShape): OneCliPayload {
-  try {
-    const parsed: unknown = JSON.parse(row.payload);
-    return parsed && typeof parsed === 'object' ? (parsed as OneCliPayload) : {};
-    // eslint-disable-next-line no-catch-all/no-catch-all -- stored payloads are untrusted; a malformed one must not break event assembly
-  } catch {
-    return {};
-  }
-}
-
-/** Shape-only: the request body's presence is auditable, its content never is. */
-function oneCliDetails(p: OneCliPayload): Record<string, unknown> {
-  return {
-    method: p.method,
-    host: p.host,
-    path: p.path,
-    one_cli_request_id: p.oneCliRequestId,
-    body_preview_chars: typeof p.bodyPreview === 'string' ? p.bodyPreview.length : 0,
-  };
-}
-
-function oneCliResources(row: OneCliRowShape): AuditResource[] {
-  const out: AuditResource[] = [];
-  if (row.agent_group_id) out.push({ type: 'agent_group', id: row.agent_group_id });
-  out.push({ type: 'approval', id: row.approval_id });
-  return out;
-}
-
-/** Pending event for a OneCLI credential hold, derived from its row. */
-export function oneCliHoldEvent(row: OneCliRowShape): AuditEventInput {
-  const p = oneCliPayload(row);
-  const resources = oneCliResources(row);
-  if (p.approver) resources.push({ type: 'user', id: p.approver });
-  return {
-    actor: { type: 'agent', id: row.agent_group_id ?? p.agent?.externalId ?? p.agent?.name ?? 'unknown' },
-    // OneCLI requests come from inside an agent container but carry no session.
-    origin: { transport: 'container' },
-    action: ONECLI_AUDIT_ACTION,
-    resources,
-    outcome: 'pending',
-    correlationId: row.approval_id,
-    details: oneCliDetails(p),
-  };
-}
-
-/** approvals.decide for a OneCLI resolution (click, expiry, or startup sweep). */
-export function oneCliDecideEvent(
-  row: OneCliRowShape & { channel_type?: string | null },
-  args: { actor: AuditActor; origin: AuditOrigin; outcome: 'approved' | 'rejected'; reason?: string },
-): AuditEventInput {
-  const details: Record<string, unknown> = {
-    gated_action: ONECLI_AUDIT_ACTION,
-    ...oneCliDetails(oneCliPayload(row)),
-  };
-  if (args.reason) details.reason = args.reason;
-  return {
-    actor: args.actor,
-    origin: args.origin,
-    action: 'approvals.decide',
-    resources: oneCliResources(row),
-    outcome: args.outcome,
-    correlationId: row.approval_id,
-    details,
-  };
-}
-
-/** Mirror of agent-route's message-content parse — shape extraction only. */
-function messageShape(content: unknown): { text: string; files: string[] } {
-  if (typeof content !== 'string') return { text: '', files: [] };
-  try {
-    const parsed = JSON.parse(content) as { text?: unknown; files?: unknown };
-    return {
-      text: typeof parsed.text === 'string' ? parsed.text : '',
-      files: Array.isArray(parsed.files) ? parsed.files.filter((f): f is string => typeof f === 'string') : [],
-    };
-    // eslint-disable-next-line no-catch-all/no-catch-all -- non-JSON content is the raw body; shape extraction must not throw
-  } catch {
-    return { text: content, files: [] };
-  }
-}

src/audit/vocab.ts

@@ -0,0 +1,55 @@
+/**
+ * Domain-free event vocabulary — actor and origin constructors shared by the
+ * domain-owned `*.audit.ts` adapters. Pure derivation; nothing here writes
+ * the log.
+ *
+ * Leaf rule: this module (like the rest of src/audit/) may depend on node,
+ * config/log, shared types, and the db read layer — never on src/cli/* or
+ * src/modules/*. Domain-specific mapping (CLI resources, approval payloads,
+ * OneCLI rows) lives in the adapter file of the domain that owns it.
+ */
+import os from 'os';
+
+import { getMessagingGroup } from '../db/messaging-groups.js';
+import type { Session } from '../types.js';
+import { type AuditActor, type AuditOrigin, SYSTEM_ACTOR } from './types.js';
+
+/**
+ * Host callers stamp `host:<install user>` daemon-side: the ncl socket is
+ * 0600 and owned by the install user, so the identity is accurate by
+ * construction without peer credentials.
+ */
+export function hostUser(): string {
+  try {
+    return os.userInfo().username;
+    // eslint-disable-next-line no-catch-all/no-catch-all -- os.userInfo throws on exotic hosts; a fallback actor id beats no audit event
+  } catch {
+    return process.env.USER || 'unknown';
+  }
+}
+
+/** Empty resolver id (sweep/timer paths) → the system actor. */
+export function humanOrSystemActor(namespacedUserId: string): AuditActor {
+  return namespacedUserId ? { type: 'human', id: namespacedUserId } : SYSTEM_ACTOR;
+}
+
+export function originForSession(session: Session): AuditOrigin {
+  return containerOrigin(session.id, session.messaging_group_id);
+}
+
+export function containerOrigin(sessionId: string, messagingGroupId: string | null): AuditOrigin {
+  const origin: AuditOrigin = { transport: 'container', session_id: sessionId };
+  if (messagingGroupId) {
+    origin.messaging_group_id = messagingGroupId;
+    const channel = getMessagingGroup(messagingGroupId)?.channel_type;
+    if (channel) origin.channel = channel;
+  }
+  return origin;
+}
+
+/** Approval decisions arrive as card clicks on a chat platform. */
+export function channelOriginForUser(namespacedUserId: string): AuditOrigin {
+  const idx = namespacedUserId.indexOf(':');
+  const channel = idx > 0 ? namespacedUserId.slice(0, idx) : undefined;
+  return channel ? { transport: 'channel', channel } : { transport: 'channel' };
+}

src/audit/wrappers.test.ts

@@ -1,287 +0,0 @@
-/**
- * Out-of-band seam wrappers: permissions card decisions, the ungated
- * create-agent door, and the four OneCLI paths. Inners are stubs — each
- * wrapper's contract is "call through, emit the right event (or none)".
- */
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-const appended = vi.hoisted(() => ({ lines: [] as string[] }));
-const db = vi.hoisted(() => ({ row: undefined as Record<string, unknown> | undefined }));
-
-vi.mock('../config.js', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../config.js')>();
-  return { ...actual, AUDIT_ENABLED: true };
-});
-
-vi.mock('./store.js', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('./store.js')>();
-  return {
-    ...actual,
-    appendAuditLine: (line: string) => {
-      appended.lines.push(line);
-    },
-  };
-});
-
-vi.mock('../log.js', () => ({
-  log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
-}));
-
-vi.mock('../db/sessions.js', () => ({
-  getPendingApproval: () => db.row,
-}));
-
-vi.mock('../db/messaging-groups.js', () => ({
-  getMessagingGroup: () => undefined,
-}));
-
-import type { Session } from '../types.js';
-import {
-  auditChannelDecision,
-  auditChannelNameInterceptor,
-  auditCreateAgentDirect,
-  auditOneCliDecision,
-  auditOneCliExpiry,
-  auditOneCliHold,
-  auditOneCliSweep,
-  auditSenderDecision,
-} from './wrappers.js';
-
-const PAYLOAD = {
-  questionId: 'q1',
-  value: 'approve',
-  userId: 'U1',
-  channelType: 'slack',
-  platformId: 'p',
-  threadId: null,
-};
-
-const SESSION: Session = {
-  id: 'sess-1',
-  agent_group_id: 'ag-parent',
-  messaging_group_id: null,
-  thread_id: null,
-  agent_provider: null,
-  status: 'active',
-  container_status: 'stopped',
-  last_active: null,
-  created_at: '2026-01-01T00:00:00.000Z',
-};
-
-const ONECLI_ROW = {
-  approval_id: 'oa-abc123',
-  agent_group_id: 'ag-1',
-  channel_type: 'telegram',
-  payload: JSON.stringify({
-    oneCliRequestId: 'uuid-1',
-    method: 'POST',
-    host: 'api.notion.com',
-    path: '/v1/pages',
-    bodyPreview: 'SECRET BODY CONTENT',
-    agent: { externalId: 'ag-1', name: 'Agent' },
-    approver: 'slack:U0ADMIN',
-  }),
-};
-
-function events(): Array<Record<string, any>> {
-  return appended.lines.map((l) => JSON.parse(l));
-}
-
-beforeEach(() => {
-  appended.lines.length = 0;
-  db.row = undefined;
-});
-
-describe('auditSenderDecision', () => {
-  const decision = {
-    approved: true,
-    senderIdentity: 'slack:U0NEW',
-    agentGroupId: 'ag-1',
-    messagingGroupId: 'mg-1',
-    approverId: 'slack:U0ADMIN',
-    channelType: 'slack',
-  };
-
-  it('emits senders.allow success on approve and coerces claimed', async () => {
-    const wrapped = auditSenderDecision(async () => ({ claimed: true, decision }));
-    expect(await wrapped(PAYLOAD)).toBe(true);
-    const [event] = events();
-    expect(event).toMatchObject({
-      actor: { type: 'human', id: 'slack:U0ADMIN' },
-      origin: { transport: 'channel', channel: 'slack' },
-      action: 'senders.allow',
-      outcome: 'success',
-      correlation_id: null,
-      details: {},
-    });
-    expect(event.resources).toEqual([
-      { type: 'user', id: 'slack:U0NEW' },
-      { type: 'agent_group', id: 'ag-1' },
-      { type: 'messaging_group', id: 'mg-1' },
-    ]);
-  });
-
-  it('emits rejected on deny', async () => {
-    const wrapped = auditSenderDecision(async () => ({ claimed: true, decision: { ...decision, approved: false } }));
-    await wrapped(PAYLOAD);
-    expect(events()[0].outcome).toBe('rejected');
-  });
-
-  it('emits nothing without a decision (unclaimed or unauthorized click)', async () => {
-    const unclaimed = auditSenderDecision(async () => ({ claimed: false }));
-    const unauthorized = auditSenderDecision(async () => ({ claimed: true }));
-    expect(await unclaimed(PAYLOAD)).toBe(false);
-    expect(await unauthorized(PAYLOAD)).toBe(true);
-    expect(appended.lines).toHaveLength(0);
-  });
-});
-
-describe('auditChannelDecision / auditChannelNameInterceptor', () => {
-  const base = { messagingGroupId: 'mg-1', approverId: 'slack:U0ADMIN', channelType: 'slack' };
-
-  it('maps connected → success with the wired agent group', async () => {
-    const wrapped = auditChannelDecision(async () => ({
-      claimed: true,
-      decision: { kind: 'connected' as const, agentGroupId: 'ag-1', createdAgentGroup: false, ...base },
-    }));
-    await wrapped(PAYLOAD);
-    const [event] = events();
-    expect(event).toMatchObject({
-      action: 'channels.register',
-      outcome: 'success',
-      details: { created_agent_group: false },
-    });
-    expect(event.resources).toEqual([
-      { type: 'messaging_group', id: 'mg-1' },
-      { type: 'agent_group', id: 'ag-1' },
-    ]);
-  });
-
-  it('maps rejected and failed outcomes', async () => {
-    await auditChannelDecision(async () => ({ claimed: true, decision: { kind: 'rejected' as const, ...base } }))(
-      PAYLOAD,
-    );
-    await auditChannelDecision(async () => ({
-      claimed: true,
-      decision: { kind: 'failed' as const, reason: 'target agent group no longer exists', ...base },
-    }))(PAYLOAD);
-    const all = events();
-    expect(all[0]).toMatchObject({ action: 'channels.register', outcome: 'rejected' });
-    expect(all[1]).toMatchObject({ action: 'channels.register', outcome: 'failure' });
-    expect(all[1].details.reason).toContain('no longer exists');
-  });
-
-  it('records the interceptor-created agent group — the third creation door', async () => {
-    const wrapped = auditChannelNameInterceptor(async () => ({
-      claimed: true,
-      decision: {
-        kind: 'connected' as const,
-        agentGroupId: 'ag-new',
-        createdAgentGroup: true,
-        agentName: 'Scout',
-        ...base,
-      },
-    }));
-    expect(await wrapped({} as never)).toBe(true);
-    const [event] = events();
-    expect(event.details).toMatchObject({ created_agent_group: true, agent_name: 'Scout' });
-    expect(event.resources).toContainEqual({ type: 'agent_group', id: 'ag-new' });
-  });
-});
-
-describe('auditCreateAgentDirect', () => {
-  it('emits agents.create success naming parent and child', async () => {
-    const wrapped = auditCreateAgentDirect(async () => ({
-      ok: true,
-      agentGroupId: 'ag-child',
-      name: 'Scout',
-      localName: 'scout',
-      folder: 'scout',
-    }));
-    const result = await wrapped('Scout', 'be helpful', SESSION, { id: 'ag-parent' } as never, () => {});
-    expect(result.ok).toBe(true);
-    const [event] = events();
-    expect(event).toMatchObject({
-      actor: { type: 'agent', id: 'ag-parent' },
-      action: 'agents.create',
-      outcome: 'success',
-      correlation_id: null,
-      details: { name: 'Scout', parent: 'ag-parent', folder: 'scout', instructions_chars: 10 },
-    });
-    expect(event.resources).toEqual([
-      { type: 'agent_group', id: 'ag-parent' },
-      { type: 'agent_group', id: 'ag-child' },
-    ]);
-  });
-
-  it('emits failure with the reason when creation is refused', async () => {
-    const wrapped = auditCreateAgentDirect(async () => ({ ok: false, reason: 'destination name collision' }));
-    await wrapped('Scout', null, SESSION, { id: 'ag-parent' } as never, () => {});
-    const [event] = events();
-    expect(event).toMatchObject({ outcome: 'failure', details: { reason: 'destination name collision' } });
-  });
-});
-
-describe('OneCLI wrappers', () => {
-  it('hold: emits pending from the row — shape only, never the body preview', () => {
-    const inner = vi.fn();
-    auditOneCliHold(inner)(ONECLI_ROW);
-    expect(inner).toHaveBeenCalledOnce();
-    const [event] = events();
-    expect(event).toMatchObject({
-      actor: { type: 'agent', id: 'ag-1' },
-      origin: { transport: 'container' },
-      action: 'onecli.credential.use',
-      outcome: 'pending',
-      correlation_id: 'oa-abc123',
-      details: { method: 'POST', host: 'api.notion.com', path: '/v1/pages', body_preview_chars: 19 },
-    });
-    expect(event.resources).toContainEqual({ type: 'user', id: 'slack:U0ADMIN' });
-    expect(JSON.stringify(event)).not.toContain('SECRET BODY CONTENT');
-  });
-
-  it('decision: emits approvals.decide with the clicking human when resolved', () => {
-    db.row = ONECLI_ROW;
-    const wrapped = auditOneCliDecision(() => true);
-    expect(wrapped('oa-abc123', 'approve', 'slack:U0ADMIN')).toBe(true);
-    const [event] = events();
-    expect(event).toMatchObject({
-      actor: { type: 'human', id: 'slack:U0ADMIN' },
-      origin: { transport: 'channel', channel: 'slack' },
-      action: 'approvals.decide',
-      outcome: 'approved',
-      correlation_id: 'oa-abc123',
-      details: { gated_action: 'onecli.credential.use' },
-    });
-  });
-
-  it('decision: emits nothing when the resolver is gone (inner returns false)', () => {
-    db.row = ONECLI_ROW;
-    expect(auditOneCliDecision(() => false)('oa-abc123', 'approve', 'slack:U0ADMIN')).toBe(false);
-    expect(appended.lines).toHaveLength(0);
-  });
-
-  it('expiry: the system actor rejects with the reason', async () => {
-    db.row = ONECLI_ROW;
-    await auditOneCliExpiry(async () => {})('oa-abc123', 'no response');
-    const [event] = events();
-    expect(event).toMatchObject({
-      actor: { type: 'system', id: 'host' },
-      origin: { transport: 'channel', channel: 'telegram' },
-      outcome: 'rejected',
-      details: { reason: 'expired: no response' },
-    });
-  });
-
-  it('sweep: one system rejection per orphaned row', async () => {
-    const rows = [ONECLI_ROW, { ...ONECLI_ROW, approval_id: 'oa-second' }];
-    await auditOneCliSweep(
-      async () => {},
-      () => rows as never,
-    )();
-    const all = events();
-    expect(all).toHaveLength(2);
-    expect(all.map((e) => e.correlation_id)).toEqual(['oa-abc123', 'oa-second']);
-    expect(all.every((e) => e.actor.type === 'system' && e.details.reason === 'host restarted')).toBe(true);
-  });
-});

src/audit/wrappers.ts

@@ -1,365 +0,0 @@
-/**
- * Audit wrapper factories — the only way audit events get emitted. Each
- * instrumented seam composes one of these at its module edge; business logic
- * stays free of audit calls.
- */
-import type { InboundEvent } from '../channels/adapter.js';
-import type { CallerContext, RequestFrame, ResponseFrame } from '../cli/frame.js';
-import type { DispatchOptions, DispatchTrace } from '../cli/dispatch.js';
-import { getPendingApproval } from '../db/sessions.js';
-// Type-only imports from the approvals module — erased at runtime, so
-// primitive.ts importing this file back is not a cycle.
-import type {
-  ApprovalHandler,
-  ApprovalHandlerContext,
-  ApprovalHold,
-  RequestApprovalOptions,
-} from '../modules/approvals/primitive.js';
-import type { CreateAgentResult } from '../modules/agent-to-agent/create-agent.js';
-import type { ResponsePayload } from '../response-registry.js';
-import type { AgentGroup, PendingApproval, Session } from '../types.js';
-import { emitAuditEvent } from './emit.js';
-import {
-  actorForCaller,
-  auditActionForApproval,
-  channelOriginForUser,
-  detailsForApprovalPayload,
-  humanOrSystemActor,
-  normalizeArgKeys,
-  oneCliDecideEvent,
-  oneCliHoldEvent,
-  originForCaller,
-  originForSession,
-  resourcesForApproval,
-  resourcesForCli,
-} from './mapping.js';
-import { type AuditOutcome, type AuditResource, SYSTEM_ACTOR } from './types.js';
-
-type DispatchInner = (req: RequestFrame, ctx: CallerContext, opts?: DispatchOptions) => Promise<ResponseFrame>;
-
-/**
- * Dispatch middleware — the exported `dispatch` is the wrapped function, so
- * the socket server, the container delivery-action, and the approved replay
- * are all covered without changing a call site.
- *
- * Outcome derives from the response frame: ok → success, forbidden → denied
- * (captures pre-handler scope denials), anything else → failure.
- * approval-pending responses are skipped — the requestApproval decorator owns
- * every pending event. On replays, opts.approvalId becomes the terminal
- * event's correlation_id.
- */
-export function withAudit(inner: DispatchInner): DispatchInner {
-  return async (req, ctx, opts = {}) => {
-    // Trace out-param: dispatch reassigns `req` internally (dash-id fallback,
-    // group auto-fill), so the resolved command + effective args surface here.
-    const trace: DispatchTrace = {};
-    const res = await inner(req, ctx, { ...opts, trace });
-
-    if (!res.ok && res.error.code === 'approval-pending') return res;
-
-    emitAuditEvent(() => {
-      const cmd = trace.cmd;
-      const args = normalizeArgKeys(trace.args ?? req.args);
-      const outcome: AuditOutcome = res.ok ? 'success' : res.error.code === 'forbidden' ? 'denied' : 'failure';
-      const details: Record<string, unknown> = { ...args };
-      if (!res.ok) {
-        details.error = res.error.code;
-        details.reason = res.error.message;
-      }
-      if (!cmd) details.command = trace.command ?? req.command;
-      return {
-        actor: actorForCaller(ctx),
-        origin: originForCaller(ctx),
-        action: cmd ? cmd.action : 'cli.unknown-command',
-        resources: cmd ? resourcesForCli(cmd, args) : [],
-        outcome,
-        correlationId: opts.approvalId ?? null,
-        details,
-      };
-    });
-    return res;
-  };
-}
-
-type RequestApprovalInner = (opts: RequestApprovalOptions) => Promise<ApprovalHold | null>;
-
-/**
- * requestApproval decorator — owns every pending event, for all gated
- * surfaces at once: only this seam holds the action, payload, minted approval
- * id, and the approver the card actually went to. No hold (no approver, no DM
- * target, delivery failure) → no event.
- */
-export function auditRequestApproval(inner: RequestApprovalInner): (opts: RequestApprovalOptions) => Promise<void> {
-  return async (opts) => {
-    const hold = await inner(opts);
-    if (!hold) return;
-    emitAuditEvent(() => ({
-      actor: { type: 'agent', id: opts.session.agent_group_id },
-      origin: originForSession(opts.session),
-      action: auditActionForApproval(opts.action, opts.payload),
-      resources: [
-        ...resourcesForApproval(opts.action, opts.payload, opts.session),
-        { type: 'approval', id: hold.approvalId },
-        // Who was asked: the picked approver is part of the record.
-        { type: 'user', id: hold.approverUserId },
-      ],
-      outcome: 'pending',
-      correlationId: hold.approvalId,
-      details: detailsForApprovalPayload(opts.action, opts.payload),
-    }));
-  };
-}
-
-/**
- * Post-approve handler runner — emits the terminal event of a gated chain
- * (success/failure from whether the handler threw), correlated by the
- * approval id. cli_command is skipped: its replay goes back through the
- * dispatch middleware, which alone sees the real response frame. Rethrows so
- * the response handler's own catch/notify behavior is unchanged.
- */
-export async function runApprovedHandler(
-  handler: ApprovalHandler,
-  ctx: ApprovalHandlerContext,
-  approval: PendingApproval,
-  session: Session,
-): Promise<void> {
-  const skip = approval.action === 'cli_command';
-  const terminal = (outcome: AuditOutcome, error?: string): void => {
-    if (skip) return;
-    emitAuditEvent(() => ({
-      actor: { type: 'agent', id: session.agent_group_id },
-      origin: originForSession(session),
-      action: auditActionForApproval(approval.action, ctx.payload),
-      resources: [
-        ...resourcesForApproval(approval.action, ctx.payload, session),
-        { type: 'approval', id: approval.approval_id },
-      ],
-      outcome,
-      correlationId: approval.approval_id,
-      details: error
-        ? { ...detailsForApprovalPayload(approval.action, ctx.payload), error }
-        : detailsForApprovalPayload(approval.action, ctx.payload),
-    }));
-  };
-
-  try {
-    await handler(ctx);
-  } catch (err) {
-    terminal('failure', err instanceof Error ? err.message : String(err));
-    throw err;
-  }
-  terminal('success');
-}
-
-// ── Permissions card handlers (senders.allow / channels.register) ──
-// The inner handlers return domain descriptors; these adapters emit the event
-// and coerce back to the boolean the response registry / router expect.
-
-export interface SenderDecision {
-  approved: boolean;
-  senderIdentity: string;
-  agentGroupId: string;
-  messagingGroupId: string;
-  approverId: string;
-  channelType: string;
-}
-export type SenderApprovalResult = { claimed: boolean; decision?: SenderDecision };
-
-export function auditSenderDecision(
-  inner: (payload: ResponsePayload) => Promise<SenderApprovalResult>,
-): (payload: ResponsePayload) => Promise<boolean> {
-  return async (payload) => {
-    const result = await inner(payload);
-    const d = result.decision;
-    if (d) {
-      emitAuditEvent(() => ({
-        actor: { type: 'human', id: d.approverId },
-        origin: { transport: 'channel', channel: d.channelType || undefined },
-        action: 'senders.allow',
-        resources: [
-          { type: 'user', id: d.senderIdentity },
-          { type: 'agent_group', id: d.agentGroupId },
-          { type: 'messaging_group', id: d.messagingGroupId },
-        ],
-        outcome: d.approved ? 'success' : 'rejected',
-        // The withheld message is never read here — ids only.
-        details: {},
-      }));
-    }
-    return result.claimed;
-  };
-}
-
-export interface ChannelDecision {
-  kind: 'connected' | 'rejected' | 'failed';
-  messagingGroupId: string;
-  approverId: string;
-  channelType?: string;
-  agentGroupId?: string;
-  createdAgentGroup?: boolean;
-  agentName?: string;
-  reason?: string;
-}
-export type ChannelApprovalResult = { claimed: boolean; decision?: ChannelDecision };
-
-function emitChannelDecision(d: ChannelDecision): void {
-  emitAuditEvent(() => {
-    const resources: AuditResource[] = [{ type: 'messaging_group', id: d.messagingGroupId }];
-    if (d.agentGroupId) resources.push({ type: 'agent_group', id: d.agentGroupId });
-    const details: Record<string, unknown> = {};
-    if (d.createdAgentGroup !== undefined) details.created_agent_group = d.createdAgentGroup;
-    if (d.agentName) details.agent_name = d.agentName;
-    if (d.reason) details.reason = d.reason;
-    return {
-      actor: { type: 'human', id: d.approverId },
-      origin: { transport: 'channel', channel: d.channelType || undefined },
-      action: 'channels.register',
-      resources,
-      outcome: d.kind === 'connected' ? 'success' : d.kind === 'rejected' ? 'rejected' : 'failure',
-      details,
-    };
-  });
-}
-
-export function auditChannelDecision(
-  inner: (payload: ResponsePayload) => Promise<ChannelApprovalResult>,
-): (payload: ResponsePayload) => Promise<boolean> {
-  return async (payload) => {
-    const result = await inner(payload);
-    if (result.decision) emitChannelDecision(result.decision);
-    return result.claimed;
-  };
-}
-
-/** The free-text name reply — the third agent-creation door (new group + wiring). */
-export function auditChannelNameInterceptor(
-  inner: (event: InboundEvent) => Promise<ChannelApprovalResult>,
-): (event: InboundEvent) => Promise<boolean> {
-  return async (event) => {
-    const result = await inner(event);
-    if (result.decision) emitChannelDecision(result.decision);
-    return result.claimed;
-  };
-}
-
-// ── agents.create — the ungated door ──
-
-type PerformCreateAgentFn = (
-  name: string,
-  instructions: string | null,
-  session: Session,
-  sourceGroup: AgentGroup,
-  notify: (text: string) => void,
-) => Promise<CreateAgentResult>;
-
-/**
- * Wraps ONLY the global-scope direct call. The approval-gated path is covered
- * by the pending/decide/terminal chain (runApprovedHandler wraps
- * applyCreateAgent's run) — wrapping the shared body would double-emit.
- */
-export function auditCreateAgentDirect(inner: PerformCreateAgentFn): PerformCreateAgentFn {
-  return async (name, instructions, session, sourceGroup, notify) => {
-    const result = await inner(name, instructions, session, sourceGroup, notify);
-    emitAuditEvent(() => {
-      const resources: AuditResource[] = [{ type: 'agent_group', id: sourceGroup.id }];
-      const details: Record<string, unknown> = {
-        name,
-        parent: sourceGroup.id,
-        instructions_chars: instructions ? instructions.length : 0,
-      };
-      if (result.ok) {
-        resources.push({ type: 'agent_group', id: result.agentGroupId });
-        details.folder = result.folder;
-      } else {
-        details.reason = result.reason;
-      }
-      return {
-        actor: { type: 'agent', id: session.agent_group_id },
-        origin: originForSession(session),
-        action: 'agents.create',
-        resources,
-        outcome: result.ok ? 'success' : 'failure',
-        details,
-      };
-    });
-    return result;
-  };
-}
-
-// ── OneCLI credential approvals (hold + three resolution paths) ──
-
-interface OneCliHoldRow {
-  approval_id: string;
-  agent_group_id?: string | null;
-  payload: string;
-}
-
-/** Wraps the hold's row insert — emits the pending event derived from the row. */
-export function auditOneCliHold<T extends OneCliHoldRow>(inner: (row: T) => void): (row: T) => void {
-  return (row) => {
-    inner(row);
-    emitAuditEvent(() => oneCliHoldEvent(row));
-  };
-}
-
-/**
- * Wraps the card-click resolver. The resolving human's id arrives here (the
- * inner resolver has no use for it); the row is pre-read because the inner
- * deletes it on resolution.
- */
-export function auditOneCliDecision(
-  inner: (approvalId: string, selectedOption: string) => boolean,
-): (approvalId: string, selectedOption: string, userId: string) => boolean {
-  return (approvalId, selectedOption, userId) => {
-    const row = getPendingApproval(approvalId);
-    const resolved = inner(approvalId, selectedOption);
-    if (resolved && row) {
-      emitAuditEvent(() =>
-        oneCliDecideEvent(row, {
-          actor: humanOrSystemActor(userId),
-          origin: channelOriginForUser(userId),
-          outcome: selectedOption === 'approve' ? 'approved' : 'rejected',
-        }),
-      );
-    }
-    return resolved;
-  };
-}
-
-/** Wraps the expiry timer's finalizer — the system actor rejects. */
-export function auditOneCliExpiry(
-  inner: (approvalId: string, reason: string) => Promise<void>,
-): (approvalId: string, reason: string) => Promise<void> {
-  return async (approvalId, reason) => {
-    const row = getPendingApproval(approvalId);
-    await inner(approvalId, reason);
-    if (row) {
-      emitAuditEvent(() =>
-        oneCliDecideEvent(row, {
-          actor: SYSTEM_ACTOR,
-          origin: { transport: 'channel', channel: row.channel_type ?? undefined },
-          outcome: 'rejected',
-          reason: `expired: ${reason}`,
-        }),
-      );
-    }
-  };
-}
-
-/** Wraps the startup sweep — one system rejection per orphaned row. */
-export function auditOneCliSweep(inner: () => Promise<void>, listRows: () => PendingApproval[]): () => Promise<void> {
-  return async () => {
-    const rows = listRows();
-    await inner();
-    for (const row of rows) {
-      emitAuditEvent(() =>
-        oneCliDecideEvent(row, {
-          actor: SYSTEM_ACTOR,
-          origin: { transport: 'channel', channel: row.channel_type ?? undefined },
-          outcome: 'rejected',
-          reason: 'host restarted',
-        }),
-      );
-    }
-  };
-}

src/cli/dispatch.audit.ts

@@ -0,0 +1,123 @@
+/**
+ * CLI audit adapter — owns how the dispatcher
+ * describes itself to the audit log: the dispatch middleware plus the
+ * CLI-specific actor/origin/resource mapping. Composed in dispatch.ts as
+ * `export const dispatch = withAudit(dispatchInner)`; business logic there
+ * contains zero audit calls.
+ */
+import { emitAuditEvent } from '../audit/emit.js';
+import { hostUser } from '../audit/vocab.js';
+import { containerOrigin } from '../audit/vocab.js';
+import { type AuditActor, type AuditOrigin, type AuditOutcome, type AuditResource } from '../audit/types.js';
+import { getResource } from './crud.js';
+import type { CallerContext, RequestFrame, ResponseFrame } from './frame.js';
+import type { CommandDef } from './registry.js';
+// Type-only import from the module this adapter wraps — erased at runtime,
+// so dispatch.ts importing this file back is not a cycle.
+import type { DispatchOptions, DispatchTrace } from './dispatch.js';
+
+// ── CLI mapping ──
+
+/**
+ * Host callers stamp `host:<install user>` daemon-side (the ncl socket is
+ * 0600 and owned by the install user); container callers are their agent group.
+ */
+export function actorForCaller(ctx: CallerContext): AuditActor {
+  return ctx.caller === 'host' ? { type: 'human', id: `host:${hostUser()}` } : { type: 'agent', id: ctx.agentGroupId };
+}
+
+export function originForCaller(ctx: CallerContext): AuditOrigin {
+  if (ctx.caller === 'host') return { transport: 'socket' };
+  return containerOrigin(ctx.sessionId, ctx.messagingGroupId || null);
+}
+
+/**
+ * Frame-level args use `--hyphen-keys`; recorded details use the same
+ * underscore form the parsed handlers see. Mirrors crud's normalizeArgs
+ * (kept local so audit doesn't depend on a module tests commonly mock).
+ */
+export function normalizeArgKeys(raw: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    out[k.replace(/-/g, '_')] = v;
+  }
+  return out;
+}
+
+/** CLI resource plural → audit resource type, where the singular isn't it. */
+const RESOURCE_TYPE_OVERRIDES: Record<string, string> = {
+  groups: 'agent_group',
+  'messaging-groups': 'messaging_group',
+  'dropped-messages': 'dropped_message',
+  'user-dms': 'user_dm',
+};
+
+/**
+ * Derive touched/attempted resources from a command's effective args. Generic
+ * by design: `id` → the command's own resource, group/user args → their
+ * types, and a bare `{type}` entry when nothing else is known (a denied
+ * `users list` still names what was attempted).
+ */
+export function resourcesForCli(cmd: CommandDef, args: Record<string, unknown>): AuditResource[] {
+  if (!cmd.resource) return [];
+  const type = RESOURCE_TYPE_OVERRIDES[cmd.resource] ?? getResource(cmd.resource)?.name ?? cmd.resource;
+
+  const out: AuditResource[] = [];
+  const push = (t: string, id: unknown): void => {
+    if (typeof id !== 'string' || !id) return;
+    if (!out.some((r) => r.type === t && r.id === id)) out.push({ type: t, id });
+  };
+  push(type, args.id);
+  push('agent_group', args.agent_group_id ?? args.group);
+  push('user', args.user);
+  if (out.length === 0) out.push({ type });
+  return out;
+}
+
+// ── The dispatch middleware ──
+
+type DispatchInner = (req: RequestFrame, ctx: CallerContext, opts?: DispatchOptions) => Promise<ResponseFrame>;
+
+/**
+ * Dispatch middleware — the exported `dispatch` is the wrapped function, so
+ * the socket server, the container delivery-action, and the approved replay
+ * are all covered without changing a call site.
+ *
+ * Outcome derives from the response frame: ok → success, forbidden → denied
+ * (captures pre-handler scope denials), anything else → failure.
+ * approval-pending responses are skipped — the requestApproval decorator owns
+ * every pending event. On replays, opts.approvalId becomes the terminal
+ * event's correlation_id.
+ */
+export function withAudit(inner: DispatchInner): DispatchInner {
+  return async (req, ctx, opts = {}) => {
+    // Trace out-param: dispatch reassigns `req` internally (dash-id fallback,
+    // group auto-fill), so the resolved command + effective args surface here.
+    const trace: DispatchTrace = {};
+    const res = await inner(req, ctx, { ...opts, trace });
+
+    if (!res.ok && res.error.code === 'approval-pending') return res;
+
+    emitAuditEvent(() => {
+      const cmd = trace.cmd;
+      const args = normalizeArgKeys(trace.args ?? req.args);
+      const outcome: AuditOutcome = res.ok ? 'success' : res.error.code === 'forbidden' ? 'denied' : 'failure';
+      const details: Record<string, unknown> = { ...args };
+      if (!res.ok) {
+        details.error = res.error.code;
+        details.reason = res.error.message;
+      }
+      if (!cmd) details.command = trace.command ?? req.command;
+      return {
+        actor: actorForCaller(ctx),
+        origin: originForCaller(ctx),
+        action: cmd ? cmd.action : 'cli.unknown-command',
+        resources: cmd ? resourcesForCli(cmd, args) : [],
+        outcome,
+        correlationId: opts.approvalId ?? null,
+        details,
+      };
+    });
+    return res;
+  };
+}

src/cli/dispatch.ts

@@ -6,7 +6,7 @@
  * Approval gating for risky calls from the container is the only branch
  * that differs by caller. Host callers and `open` commands run inline.
  */
-import { withAudit } from '../audit/wrappers.js';
+import { withAudit } from './dispatch.audit.js';
 import { getContainerConfig } from '../db/container-configs.js';
 import { getAgentGroup } from '../db/agent-groups.js';
 import { getSession } from '../db/sessions.js';
@@ -16,9 +16,10 @@ import { getResource } from './crud.js';
 import { type CommandDef, lookup } from './registry.js';
 
 /**
- * Out-param for the audit middleware: dispatch reassigns `req` internally
- * (dash-joined id fallback, group-scope auto-fill), so the wrapper can't see
- * the resolved command or effective args on the frame it passed in.
+ * Resolution out-param for middleware that wraps dispatch: dispatch reassigns
+ * `req` internally (dash-joined id fallback, group-scope auto-fill), so a
+ * wrapper can't see the resolved command or effective args on the frame it
+ * passed in.
  */
 export type DispatchTrace = {
   cmd?: CommandDef;
@@ -29,9 +30,9 @@ export type DispatchTrace = {
 export type DispatchOptions = {
   /** True when a command is being replayed after approval. */
   approved?: boolean;
-  /** Approval id when replaying — becomes the terminal audit event's correlation_id. */
+  /** Id of the approval that authorized this replay — correlation for middleware/observers. */
   approvalId?: string;
-  /** Filled by dispatch for the audit middleware. */
+  /** Filled by dispatch with the resolved command + effective args. */
   trace?: DispatchTrace;
 };
 
@@ -216,17 +217,17 @@ async function dispatchInner(
 }
 
 /**
- * Public dispatcher — the audit middleware wraps the inner dispatcher, so all
- * three call sites (socket server, container delivery-action, and the
- * approved replay below) emit audit events with zero caller changes.
+ * Public dispatcher — the audit middleware wraps the inner dispatcher, so the
+ * socket server, the container delivery-action, and the approved replay are
+ * all covered without changing a call site.
  */
 export const dispatch = withAudit(dispatchInner);
 
 registerApprovalHandler('cli_command', async ({ payload, notify, approvalId }) => {
   const frame = payload.frame as RequestFrame;
   const callerContext = parseCallerContext(payload.callerContext) ?? { caller: 'host' };
-  // approvalId threads through to the audit middleware: the replay's terminal
-  // event carries the gated chain's correlation_id, emitted there — not here.
+  // approvalId rides opts so middleware/observers around dispatch can
+  // correlate the replay with the approval that authorized it.
   const response = await dispatch(frame, callerContext, { approved: true, approvalId });
 
   if (response.ok) {

src/cli/registry.ts

@@ -32,7 +32,8 @@ export type CommandDef<TArgs = unknown, TData = unknown> = {
    */
   generic?: 'list' | 'get';
   /**
-   * Dotted audit action name, e.g. `groups.config.add-mcp-server`. Stamped
+   * Canonical dotted action name, e.g. `groups.config.add-mcp-server` — for
+   * middleware and observability surfaces that need namespaced verbs. Stamped
    * explicitly by `registerResource` (which knows verb segment boundaries);
    * hand-registered commands may omit it and get `name` with dashes→dots.
    */

src/host-sweep.ts

@@ -43,7 +43,6 @@ import {
   syncProcessingAcks,
   type ContainerState,
 } from './db/session-db.js';
-import { maintainAudit } from './audit/index.js';
 import { log } from './log.js';
 import { openInboundDb, openOutboundDb, openOutboundDbRw, inboundDbPath, heartbeatPath } from './session-manager.js';
 import { isContainerRunning, killContainer, wakeContainer } from './container-runner.js';
@@ -165,10 +164,10 @@ async function sweep(): Promise<void> {
   }
   // MODULE-HOOK:approvals-reason-sweep:end
 
-  // Audit maintenance — retention prune (throttled to once per UTC day inside
-  // the module) + registered post-write hooks' maintain(). No-op when audit
-  // is disabled.
+  // Audit maintenance — retention prune (throttled to once per UTC day
+  // inside the module) + post-write hooks' maintain(). No-op when disabled.
   try {
+    const { maintainAudit } = await import('./audit/index.js');
     maintainAudit();
   } catch (err) {
     log.error('Audit maintenance failed', { err });

src/index.ts

@@ -9,7 +9,6 @@ import path from 'path';
 import { backfillContainerConfigs } from './backfill-container-configs.js';
 import { DATA_DIR } from './config.js';
 import { enforceStartupBackoff, resetCircuitBreaker } from './circuit-breaker.js';
-import { initAuditLog } from './audit/index.js';
 import { migrateGroupsToClaudeLocal } from './claude-md-compose.js';
 import { initDb } from './db/connection.js';
 import { runMigrations } from './db/migrations/index.js';
@@ -83,8 +82,11 @@ async function main(): Promise<void> {
   // 1c. One-time filesystem cutover — idempotent, no-op after first run.
   migrateGroupsToClaudeLocal();
 
-  // 1d. Audit log — registers the decision observer; when enabled, asserts
-  // data/audit/ is writable (throw → exit 1) and runs the boot prune.
+  // 1d. Audit log (opt-in — AUDIT_ENABLED gates writes). The observer import
+  // self-registers approvals.decide; initAuditLog asserts data/audit/ is
+  // writable when enabled (throw → exit 1) and starts post-write hooks.
+  await import('./modules/approvals/approvals-observer.audit.js');
+  const { initAuditLog } = await import('./audit/index.js');
   initAuditLog();
 
   // 2. Container runtime

src/modules/agent-to-agent/create-agent.audit.test.ts

@@ -0,0 +1,86 @@
+/**
+ * agents.create adapter for the ungated door. The inner is a stub — the
+ * contract is "call through, emit success/failure naming parent and child".
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const appended = vi.hoisted(() => ({ lines: [] as string[] }));
+
+vi.mock('../../config.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../config.js')>();
+  return { ...actual, AUDIT_ENABLED: true };
+});
+
+vi.mock('../../audit/store.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../audit/store.js')>();
+  return {
+    ...actual,
+    appendAuditLine: (line: string) => {
+      appended.lines.push(line);
+    },
+  };
+});
+
+vi.mock('../../log.js', () => ({
+  log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+}));
+
+vi.mock('../../db/messaging-groups.js', () => ({
+  getMessagingGroup: () => undefined,
+}));
+
+import type { Session } from '../../types.js';
+import { auditCreateAgentDirect } from './create-agent.audit.js';
+
+const SESSION: Session = {
+  id: 'sess-1',
+  agent_group_id: 'ag-parent',
+  messaging_group_id: null,
+  thread_id: null,
+  agent_provider: null,
+  status: 'active',
+  container_status: 'stopped',
+  last_active: null,
+  created_at: '2026-01-01T00:00:00.000Z',
+};
+
+function events(): Array<Record<string, any>> {
+  return appended.lines.map((l) => JSON.parse(l));
+}
+
+beforeEach(() => {
+  appended.lines.length = 0;
+});
+
+describe('auditCreateAgentDirect', () => {
+  it('emits agents.create success naming parent and child', async () => {
+    const wrapped = auditCreateAgentDirect(async () => ({
+      ok: true,
+      agentGroupId: 'ag-child',
+      name: 'Scout',
+      localName: 'scout',
+      folder: 'scout',
+    }));
+    const result = await wrapped('Scout', 'be helpful', SESSION, { id: 'ag-parent' } as never, () => {});
+    expect(result.ok).toBe(true);
+    const [event] = events();
+    expect(event).toMatchObject({
+      actor: { type: 'agent', id: 'ag-parent' },
+      action: 'agents.create',
+      outcome: 'success',
+      correlation_id: null,
+      details: { name: 'Scout', parent: 'ag-parent', folder: 'scout', instructions_chars: 10 },
+    });
+    expect(event.resources).toEqual([
+      { type: 'agent_group', id: 'ag-parent' },
+      { type: 'agent_group', id: 'ag-child' },
+    ]);
+  });
+
+  it('emits failure with the reason when creation is refused', async () => {
+    const wrapped = auditCreateAgentDirect(async () => ({ ok: false, reason: 'destination name collision' }));
+    await wrapped('Scout', null, SESSION, { id: 'ag-parent' } as never, () => {});
+    const [event] = events();
+    expect(event).toMatchObject({ outcome: 'failure', details: { reason: 'destination name collision' } });
+  });
+});

src/modules/agent-to-agent/create-agent.audit.ts

@@ -0,0 +1,51 @@
+/**
+ * Agent-creation audit adapter — agents.create for
+ * the ungated door. Wraps ONLY the global-scope direct call: the
+ * approval-gated path is covered by the pending/decide/terminal chain
+ * (runApprovedHandler wraps applyCreateAgent's run) — wrapping the shared
+ * body would double-emit.
+ */
+import { emitAuditEvent } from '../../audit/emit.js';
+import type { AuditResource } from '../../audit/types.js';
+import { originForSession } from '../../audit/vocab.js';
+import type { AgentGroup, Session } from '../../types.js';
+// Type-only import from the module this adapter wraps — erased at runtime,
+// so create-agent.ts importing this file back is not a cycle.
+import type { CreateAgentResult } from './create-agent.js';
+
+type PerformCreateAgentFn = (
+  name: string,
+  instructions: string | null,
+  session: Session,
+  sourceGroup: AgentGroup,
+  notify: (text: string) => void,
+) => Promise<CreateAgentResult>;
+
+export function auditCreateAgentDirect(inner: PerformCreateAgentFn): PerformCreateAgentFn {
+  return async (name, instructions, session, sourceGroup, notify) => {
+    const result = await inner(name, instructions, session, sourceGroup, notify);
+    emitAuditEvent(() => {
+      const resources: AuditResource[] = [{ type: 'agent_group', id: sourceGroup.id }];
+      const details: Record<string, unknown> = {
+        name,
+        parent: sourceGroup.id,
+        instructions_chars: instructions ? instructions.length : 0,
+      };
+      if (result.ok) {
+        resources.push({ type: 'agent_group', id: result.agentGroupId });
+        details.folder = result.folder;
+      } else {
+        details.reason = result.reason;
+      }
+      return {
+        actor: { type: 'agent', id: session.agent_group_id },
+        origin: originForSession(session),
+        action: 'agents.create',
+        resources,
+        outcome: result.ok ? 'success' : 'failure',
+        details,
+      };
+    });
+    return result;
+  };
+}

src/modules/agent-to-agent/create-agent.ts

@@ -14,7 +14,6 @@
  */
 import path from 'path';
 
-import { auditCreateAgentDirect } from '../../audit/wrappers.js';
 import { GROUPS_DIR } from '../../config.js';
 import { createAgentGroup, getAgentGroup, getAgentGroupByFolder } from '../../db/agent-groups.js';
 import { getContainerConfig, updateContainerConfigScalars } from '../../db/container-configs.js';
@@ -76,7 +75,7 @@ export async function handleCreateAgent(content: Record<string, unknown>, sessio
   const cliScope = getContainerConfig(session.agent_group_id)?.cli_scope ?? 'group';
   if (cliScope === 'global') {
     // Trusted owner agent group — create directly, then notify (+wake) it.
-    await performCreateAgentDirect(name, instructions, session, sourceGroup, (text) => notifyAgent(session, text));
+    await performCreateAgent(name, instructions, session, sourceGroup, (text) => notifyAgent(session, text));
     return;
   }
 
@@ -113,7 +112,7 @@ export const applyCreateAgent: ApprovalHandler = async ({ session, payload, noti
   await performCreateAgent(name, instructions, session, sourceGroup, notify);
 };
 
-/** What creation did — consumed by the ungated door's audit wrapper. */
+/** What creation did — the created group's ids on success, the reason on failure. */
 export type CreateAgentResult =
   | { ok: true; agentGroupId: string; name: string; localName: string; folder: string }
   | { ok: false; reason: string };
@@ -216,10 +215,3 @@ async function performCreateAgent(
   log.info('Agent group created', { agentGroupId, name, localName, folder, parent: sourceGroup.id });
   return { ok: true, agentGroupId, name, localName, folder };
 }
-
-/**
- * The ungated door: only the global-scope direct call is audit-wrapped. The
- * approval path's terminal event comes from the wrapped handler run in the
- * response handler — wrapping the shared body would double-emit.
- */
-const performCreateAgentDirect = auditCreateAgentDirect(performCreateAgent);

src/modules/approvals/approvals-observer.audit.ts

@@ -1,13 +1,18 @@
 /**
- * Decision events — approvals.decide, one per resolved approval, riding the
- * existing approval-resolved hook. Covers every requestApproval-backed action
- * (cli_command, self-mod, create_agent, a2a gate); OneCLI never reaches
- * notifyApprovalResolved and emits its decisions from its own wrappers.
+ * Decision events — approvals.decide, one per
+ * resolved approval, riding the existing approval-resolved hook. Covers every
+ * requestApproval-backed action (cli_command, self-mod, create_agent, a2a
+ * gate); OneCLI never reaches notifyApprovalResolved and emits its decisions
+ * from its own wrappers in approvals.audit.ts.
+ *
+ * Self-registers on import (the tree's observer idiom) — imported once from
+ * the audit block in src/index.ts.
  */
+import { emitAuditEvent } from '../../audit/emit.js';
+import { channelOriginForUser, humanOrSystemActor } from '../../audit/vocab.js';
 // Direct file import (not the approvals barrel) to keep the graph tight.
-import { type ApprovalResolvedEvent, registerApprovalResolvedHandler } from '../modules/approvals/primitive.js';
-import { emitAuditEvent } from './emit.js';
-import { auditActionForApproval, channelOriginForUser, humanOrSystemActor, resourcesForApproval } from './mapping.js';
+import { type ApprovalResolvedEvent, registerApprovalResolvedHandler } from './primitive.js';
+import { auditActionForApproval, resourcesForApproval } from './approvals.audit.js';
 
 export function onApprovalResolved(event: ApprovalResolvedEvent): void {
   emitAuditEvent(() => {
@@ -33,10 +38,6 @@ export function onApprovalResolved(event: ApprovalResolvedEvent): void {
   });
 }
 
-export function registerAuditObserver(): void {
-  registerApprovalResolvedHandler(onApprovalResolved);
-}
-
 function safeParse(json: string): Record<string, unknown> {
   try {
     const parsed: unknown = JSON.parse(json);
@@ -46,3 +47,5 @@ function safeParse(json: string): Record<string, unknown> {
     return {};
   }
 }
+
+registerApprovalResolvedHandler(onApprovalResolved);

src/modules/approvals/approvals.audit.test.ts

@@ -0,0 +1,127 @@
+/**
+ * OneCLI credential wrappers: hold + the three resolution paths. Inners are
+ * stubs — each wrapper's contract is "call through, emit the right event
+ * (or none)". The requestApproval decorator and runApprovedHandler are
+ * covered end-to-end in primitive.audit.test.ts / response-handler.audit.test.ts.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const appended = vi.hoisted(() => ({ lines: [] as string[] }));
+const db = vi.hoisted(() => ({ row: undefined as Record<string, unknown> | undefined }));
+
+vi.mock('../../config.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../config.js')>();
+  return { ...actual, AUDIT_ENABLED: true };
+});
+
+vi.mock('../../audit/store.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../audit/store.js')>();
+  return {
+    ...actual,
+    appendAuditLine: (line: string) => {
+      appended.lines.push(line);
+    },
+  };
+});
+
+vi.mock('../../log.js', () => ({
+  log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+}));
+
+vi.mock('../../db/sessions.js', () => ({
+  getPendingApproval: () => db.row,
+}));
+
+vi.mock('../../db/messaging-groups.js', () => ({
+  getMessagingGroup: () => undefined,
+}));
+
+import { auditOneCliDecision, auditOneCliExpiry, auditOneCliHold, auditOneCliSweep } from './approvals.audit.js';
+
+const ONECLI_ROW = {
+  approval_id: 'oa-abc123',
+  agent_group_id: 'ag-1',
+  channel_type: 'telegram',
+  payload: JSON.stringify({
+    oneCliRequestId: 'uuid-1',
+    method: 'POST',
+    host: 'api.notion.com',
+    path: '/v1/pages',
+    bodyPreview: 'SECRET BODY CONTENT',
+    agent: { externalId: 'ag-1', name: 'Agent' },
+    approver: 'slack:U0ADMIN',
+  }),
+};
+
+function events(): Array<Record<string, any>> {
+  return appended.lines.map((l) => JSON.parse(l));
+}
+
+beforeEach(() => {
+  appended.lines.length = 0;
+  db.row = undefined;
+});
+
+describe('OneCLI wrappers', () => {
+  it('hold: emits pending from the row — shape only, never the body preview', () => {
+    const inner = vi.fn();
+    auditOneCliHold(inner)(ONECLI_ROW);
+    expect(inner).toHaveBeenCalledOnce();
+    const [event] = events();
+    expect(event).toMatchObject({
+      actor: { type: 'agent', id: 'ag-1' },
+      origin: { transport: 'container' },
+      action: 'onecli.credential.use',
+      outcome: 'pending',
+      correlation_id: 'oa-abc123',
+      details: { method: 'POST', host: 'api.notion.com', path: '/v1/pages', body_preview_chars: 19 },
+    });
+    expect(event.resources).toContainEqual({ type: 'user', id: 'slack:U0ADMIN' });
+    expect(JSON.stringify(event)).not.toContain('SECRET BODY CONTENT');
+  });
+
+  it('decision: emits approvals.decide with the clicking human when resolved', () => {
+    db.row = ONECLI_ROW;
+    const wrapped = auditOneCliDecision(() => true);
+    expect(wrapped('oa-abc123', 'approve', 'slack:U0ADMIN')).toBe(true);
+    const [event] = events();
+    expect(event).toMatchObject({
+      actor: { type: 'human', id: 'slack:U0ADMIN' },
+      origin: { transport: 'channel', channel: 'slack' },
+      action: 'approvals.decide',
+      outcome: 'approved',
+      correlation_id: 'oa-abc123',
+      details: { gated_action: 'onecli.credential.use' },
+    });
+  });
+
+  it('decision: emits nothing when the resolver is gone (inner returns false)', () => {
+    db.row = ONECLI_ROW;
+    expect(auditOneCliDecision(() => false)('oa-abc123', 'approve', 'slack:U0ADMIN')).toBe(false);
+    expect(appended.lines).toHaveLength(0);
+  });
+
+  it('expiry: the system actor rejects with the reason', async () => {
+    db.row = ONECLI_ROW;
+    await auditOneCliExpiry(async () => {})('oa-abc123', 'no response');
+    const [event] = events();
+    expect(event).toMatchObject({
+      actor: { type: 'system', id: 'host' },
+      origin: { transport: 'channel', channel: 'telegram' },
+      outcome: 'rejected',
+      details: { reason: 'expired: no response' },
+    });
+  });
+
+  it('sweep: one system rejection per orphaned row', async () => {
+    const rows = [ONECLI_ROW, { ...ONECLI_ROW, approval_id: 'oa-second' }];
+    await auditOneCliSweep(
+      async () => {},
+      () => rows as never,
+    )();
+    const all = events();
+    expect(all).toHaveLength(2);
+    expect(all.map((e) => e.correlation_id)).toEqual(['oa-abc123', 'oa-second']);
+    expect(all.every((e) => e.actor.type === 'system' && e.details.reason === 'host restarted')).toBe(true);
+  });
+});

src/modules/approvals/approvals.audit.ts

@@ -0,0 +1,345 @@
+/**
+ * Approvals audit adapter — owns how the approvals
+ * domain describes itself to the audit log: the requestApproval decorator
+ * (every gated hold → pending event), the post-approve handler runner (the
+ * gated chain's terminal event), the OneCLI credential wrappers (hold + three
+ * resolution paths), and the approval-payload mapping they share. Composed at
+ * this module's edges; business logic contains zero audit calls.
+ */
+import { emitAuditEvent } from '../../audit/emit.js';
+import {
+  type AuditActor,
+  type AuditEventInput,
+  type AuditOrigin,
+  type AuditOutcome,
+  type AuditResource,
+  SYSTEM_ACTOR,
+} from '../../audit/types.js';
+import { channelOriginForUser, humanOrSystemActor, originForSession } from '../../audit/vocab.js';
+import { resourcesForCli } from '../../cli/dispatch.audit.js';
+import type { RequestFrame } from '../../cli/frame.js';
+import { lookup } from '../../cli/registry.js';
+import { getPendingApproval } from '../../db/sessions.js';
+import type { PendingApproval, Session } from '../../types.js';
+// Type-only imports from the module this adapter wraps — erased at runtime,
+// so primitive.ts importing this file back is not a cycle.
+import type { ApprovalHandler, ApprovalHandlerContext, ApprovalHold, RequestApprovalOptions } from './primitive.js';
+
+// ── Approval-payload mapping ──
+
+/** Dotted audit action per approval type; cli_command derives from its frame. */
+export const APPROVAL_AUDIT_ACTIONS: Record<string, string> = {
+  install_packages: 'self-mod.install-packages',
+  add_mcp_server: 'self-mod.add-mcp-server',
+  create_agent: 'agents.create',
+  a2a_message_gate: 'messages.a2a-gate',
+  onecli_credential: 'onecli.credential.use',
+};
+
+export function auditActionForApproval(approvalAction: string, payload: Record<string, unknown>): string {
+  if (approvalAction === 'cli_command') {
+    const frame = payload.frame as RequestFrame | undefined;
+    return (frame && lookup(frame.command)?.action) ?? 'cli.unknown-command';
+  }
+  return APPROVAL_AUDIT_ACTIONS[approvalAction] ?? approvalAction.replace(/_/g, '.');
+}
+
+/**
+ * details for an approval's pending/terminal events. Message-bearing payloads
+ * (a2a gate) record shape only — body_chars and attachment names, never
+ * content; the emit-seam redactor is defense-in-depth, not the mechanism.
+ */
+export function detailsForApprovalPayload(
+  approvalAction: string,
+  payload: Record<string, unknown>,
+): Record<string, unknown> {
+  switch (approvalAction) {
+    case 'cli_command': {
+      const frame = payload.frame as RequestFrame | undefined;
+      return { ...(frame?.args ?? {}) };
+    }
+    case 'create_agent': {
+      const instructions = typeof payload.instructions === 'string' ? payload.instructions : null;
+      return { name: payload.name, instructions_chars: instructions ? instructions.length : 0 };
+    }
+    case 'a2a_message_gate': {
+      const { text, files } = messageShape(payload.content);
+      return { to: payload.platform_id, body_chars: text.length, attachments: files };
+    }
+    default:
+      // install_packages, add_mcp_server, and future types: metadata payloads
+      // pass through as-is — the emit-seam redactor masks sensitive keys.
+      return { ...payload };
+  }
+}
+
+export function resourcesForApproval(
+  approvalAction: string,
+  payload: Record<string, unknown>,
+  session: Session,
+): AuditResource[] {
+  const base: AuditResource[] = [{ type: 'agent_group', id: session.agent_group_id }];
+  if (approvalAction === 'cli_command') {
+    const frame = payload.frame as RequestFrame | undefined;
+    const cmd = frame && lookup(frame.command);
+    if (cmd && frame) {
+      const cliResources = resourcesForCli(cmd, frame.args);
+      for (const r of cliResources) {
+        if (!base.some((b) => b.type === r.type && b.id === r.id)) base.push(r);
+      }
+    }
+  }
+  if (approvalAction === 'a2a_message_gate' && typeof payload.platform_id === 'string' && payload.platform_id) {
+    if (payload.platform_id !== session.agent_group_id) {
+      base.push({ type: 'agent_group', id: payload.platform_id });
+    }
+  }
+  return base;
+}
+
+/** Mirror of agent-route's message-content parse — shape extraction only. */
+function messageShape(content: unknown): { text: string; files: string[] } {
+  if (typeof content !== 'string') return { text: '', files: [] };
+  try {
+    const parsed = JSON.parse(content) as { text?: unknown; files?: unknown };
+    return {
+      text: typeof parsed.text === 'string' ? parsed.text : '',
+      files: Array.isArray(parsed.files) ? parsed.files.filter((f): f is string => typeof f === 'string') : [],
+    };
+    // eslint-disable-next-line no-catch-all/no-catch-all -- non-JSON content is the raw body; shape extraction must not throw
+  } catch {
+    return { text: content, files: [] };
+  }
+}
+
+// ── requestApproval decorator ──
+
+type RequestApprovalFn = (opts: RequestApprovalOptions) => Promise<ApprovalHold | null>;
+
+/**
+ * requestApproval decorator — owns every pending event, for all gated
+ * surfaces at once: only this seam holds the action, payload, minted approval
+ * id, and the approver the card actually went to. Pass-through: callers see
+ * the hold exactly as the inner returns it. No hold → no event.
+ */
+export function auditRequestApproval(inner: RequestApprovalFn): RequestApprovalFn {
+  return async (opts) => {
+    const hold = await inner(opts);
+    if (!hold) return hold;
+    emitAuditEvent(() => ({
+      actor: { type: 'agent', id: opts.session.agent_group_id },
+      origin: originForSession(opts.session),
+      action: auditActionForApproval(opts.action, opts.payload),
+      resources: [
+        ...resourcesForApproval(opts.action, opts.payload, opts.session),
+        { type: 'approval', id: hold.approvalId },
+        // Who was asked: the picked approver is part of the record.
+        { type: 'user', id: hold.approverUserId },
+      ],
+      outcome: 'pending',
+      correlationId: hold.approvalId,
+      details: detailsForApprovalPayload(opts.action, opts.payload),
+    }));
+    return hold;
+  };
+}
+
+// ── Post-approve handler runner ──
+
+/**
+ * Emits the terminal event of a gated chain (success/failure from whether the
+ * handler threw), correlated by the approval id. cli_command is skipped: its
+ * replay goes back through the dispatch middleware, which alone sees the real
+ * response frame. Rethrows so the response handler's own catch/notify
+ * behavior is unchanged.
+ */
+export async function runApprovedHandler(
+  handler: ApprovalHandler,
+  ctx: ApprovalHandlerContext,
+  approval: PendingApproval,
+  session: Session,
+): Promise<void> {
+  const skip = approval.action === 'cli_command';
+  const terminal = (outcome: AuditOutcome, error?: string): void => {
+    if (skip) return;
+    emitAuditEvent(() => ({
+      actor: { type: 'agent', id: session.agent_group_id },
+      origin: originForSession(session),
+      action: auditActionForApproval(approval.action, ctx.payload),
+      resources: [
+        ...resourcesForApproval(approval.action, ctx.payload, session),
+        { type: 'approval', id: approval.approval_id },
+      ],
+      outcome,
+      correlationId: approval.approval_id,
+      details: error
+        ? { ...detailsForApprovalPayload(approval.action, ctx.payload), error }
+        : detailsForApprovalPayload(approval.action, ctx.payload),
+    }));
+  };
+
+  try {
+    await handler(ctx);
+  } catch (err) {
+    terminal('failure', err instanceof Error ? err.message : String(err));
+    throw err;
+  }
+  terminal('success');
+}
+
+// ── OneCLI credential approvals (hold + three resolution paths) ──
+
+/** = APPROVAL_AUDIT_ACTIONS.onecli_credential; named for the OneCLI wrappers. */
+export const ONECLI_AUDIT_ACTION = 'onecli.credential.use';
+
+interface OneCliRowShape {
+  approval_id: string;
+  agent_group_id?: string | null;
+  payload: string;
+}
+
+interface OneCliPayload {
+  oneCliRequestId?: string;
+  method?: string;
+  host?: string;
+  path?: string;
+  bodyPreview?: string;
+  agent?: { externalId?: string | null; name?: string };
+  approver?: string;
+}
+
+function oneCliPayload(row: OneCliRowShape): OneCliPayload {
+  try {
+    const parsed: unknown = JSON.parse(row.payload);
+    return parsed && typeof parsed === 'object' ? (parsed as OneCliPayload) : {};
+    // eslint-disable-next-line no-catch-all/no-catch-all -- stored payloads are untrusted; a malformed one must not break event assembly
+  } catch {
+    return {};
+  }
+}
+
+/** Shape-only: the request body's presence is auditable, its content never is. */
+function oneCliDetails(p: OneCliPayload): Record<string, unknown> {
+  return {
+    method: p.method,
+    host: p.host,
+    path: p.path,
+    one_cli_request_id: p.oneCliRequestId,
+    body_preview_chars: typeof p.bodyPreview === 'string' ? p.bodyPreview.length : 0,
+  };
+}
+
+function oneCliResources(row: OneCliRowShape): AuditResource[] {
+  const out: AuditResource[] = [];
+  if (row.agent_group_id) out.push({ type: 'agent_group', id: row.agent_group_id });
+  out.push({ type: 'approval', id: row.approval_id });
+  return out;
+}
+
+/** Pending event for a OneCLI credential hold, derived from its row. */
+export function oneCliHoldEvent(row: OneCliRowShape): AuditEventInput {
+  const p = oneCliPayload(row);
+  const resources = oneCliResources(row);
+  if (p.approver) resources.push({ type: 'user', id: p.approver });
+  return {
+    actor: { type: 'agent', id: row.agent_group_id ?? p.agent?.externalId ?? p.agent?.name ?? 'unknown' },
+    // OneCLI requests come from inside an agent container but carry no session.
+    origin: { transport: 'container' },
+    action: ONECLI_AUDIT_ACTION,
+    resources,
+    outcome: 'pending',
+    correlationId: row.approval_id,
+    details: oneCliDetails(p),
+  };
+}
+
+/** approvals.decide for a OneCLI resolution (click, expiry, or startup sweep). */
+export function oneCliDecideEvent(
+  row: OneCliRowShape & { channel_type?: string | null },
+  args: { actor: AuditActor; origin: AuditOrigin; outcome: 'approved' | 'rejected'; reason?: string },
+): AuditEventInput {
+  const details: Record<string, unknown> = {
+    gated_action: ONECLI_AUDIT_ACTION,
+    ...oneCliDetails(oneCliPayload(row)),
+  };
+  if (args.reason) details.reason = args.reason;
+  return {
+    actor: args.actor,
+    origin: args.origin,
+    action: 'approvals.decide',
+    resources: oneCliResources(row),
+    outcome: args.outcome,
+    correlationId: row.approval_id,
+    details,
+  };
+}
+
+/** Wraps the hold's row insert — emits the pending event derived from the row. */
+export function auditOneCliHold<T extends OneCliRowShape>(inner: (row: T) => void): (row: T) => void {
+  return (row) => {
+    inner(row);
+    emitAuditEvent(() => oneCliHoldEvent(row));
+  };
+}
+
+/**
+ * Wraps the card-click resolver. The row is pre-read because the inner
+ * deletes it on resolution; `userId` is the resolving admin (already part of
+ * the resolver's contract — empty means a timer/sweep, i.e. the system).
+ */
+export function auditOneCliDecision(
+  inner: (approvalId: string, selectedOption: string, userId: string) => boolean,
+): (approvalId: string, selectedOption: string, userId: string) => boolean {
+  return (approvalId, selectedOption, userId) => {
+    const row = getPendingApproval(approvalId);
+    const resolved = inner(approvalId, selectedOption, userId);
+    if (resolved && row) {
+      emitAuditEvent(() =>
+        oneCliDecideEvent(row, {
+          actor: humanOrSystemActor(userId),
+          origin: channelOriginForUser(userId),
+          outcome: selectedOption === 'approve' ? 'approved' : 'rejected',
+        }),
+      );
+    }
+    return resolved;
+  };
+}
+
+/** Wraps the expiry timer's finalizer — the system actor rejects. */
+export function auditOneCliExpiry(
+  inner: (approvalId: string, reason: string) => Promise<void>,
+): (approvalId: string, reason: string) => Promise<void> {
+  return async (approvalId, reason) => {
+    const row = getPendingApproval(approvalId);
+    await inner(approvalId, reason);
+    if (row) {
+      emitAuditEvent(() =>
+        oneCliDecideEvent(row, {
+          actor: SYSTEM_ACTOR,
+          origin: { transport: 'channel', channel: row.channel_type ?? undefined },
+          outcome: 'rejected',
+          reason: `expired: ${reason}`,
+        }),
+      );
+    }
+  };
+}
+
+/** Wraps the startup sweep — one system rejection per orphaned row. */
+export function auditOneCliSweep(inner: () => Promise<void>, listRows: () => PendingApproval[]): () => Promise<void> {
+  return async () => {
+    const rows = listRows();
+    await inner();
+    for (const row of rows) {
+      emitAuditEvent(() =>
+        oneCliDecideEvent(row, {
+          actor: SYSTEM_ACTOR,
+          origin: { transport: 'channel', channel: row.channel_type ?? undefined },
+          outcome: 'rejected',
+          reason: 'host restarted',
+        }),
+      );
+    }
+  };
+}

src/modules/approvals/onecli-approvals.ts

@@ -19,7 +19,7 @@
  */
 import { OneCLI, type ApprovalRequest, type ManualApprovalHandle } from '@onecli-sh/sdk';
 
-import { auditOneCliDecision, auditOneCliExpiry, auditOneCliHold, auditOneCliSweep } from '../../audit/wrappers.js';
+import { auditOneCliDecision, auditOneCliExpiry, auditOneCliHold, auditOneCliSweep } from './approvals.audit.js';
 import { pickApprovalDelivery, pickApprover } from './primitive.js';
 import { ONECLI_API_KEY, ONECLI_URL } from '../../config.js';
 import { getAgentGroup } from '../../db/agent-groups.js';
@@ -68,7 +68,12 @@ function shortApprovalId(): string {
 /** Row insert for a hold — the audit wrapper emits the pending event from it. */
 const recordOneCliHold = auditOneCliHold(createPendingApproval);
 
-function resolveOneCLIApprovalInner(approvalId: string, selectedOption: string): boolean {
+/**
+ * Called from the approvals response handler when a card button is clicked.
+ * `userId` is the namespaced id of the clicking admin — the resolution's
+ * identity, recorded here (empty when the resolver is a timer/sweep).
+ */
+function resolveOneCLIApprovalInner(approvalId: string, selectedOption: string, userId: string): boolean {
   const state = pending.get(approvalId);
   if (!state) return false;
   pending.delete(approvalId);
@@ -81,12 +86,11 @@ function resolveOneCLIApprovalInner(approvalId: string, selectedOption: string):
   deletePendingApproval(approvalId);
 
   state.resolve(decision);
-  log.info('OneCLI approval resolved', { approvalId, decision });
+  log.info('OneCLI approval resolved', { approvalId, decision, decidedBy: userId || 'system' });
   return true;
 }
 
 /**
- * Called from the approvals response handler when a card button is clicked.
  * The audit wrapper records the decision with the clicking admin as actor
  * (OneCLI rows never reach notifyApprovalResolved, so the shared observer
  * can't cover them).

src/modules/approvals/primitive.ts

@@ -21,9 +21,8 @@
  * exposing just user-roles/user-dms) is more churn than it's worth. Revisit
  * if either module becomes genuinely optional (see REFACTOR_PLAN open q #3).
  */
-// Direct file import (not the audit barrel): the barrel pulls in observer.ts,
-// which imports this module — the narrow path keeps init order trivial.
-import { auditRequestApproval } from '../../audit/wrappers.js';
+// Sibling adapter import; it imports this module back type-only (no cycle).
+import { auditRequestApproval } from './approvals.audit.js';
 import { normalizeOptions, type RawOption } from '../../channels/ask-question.js';
 import { getMessagingGroup } from '../../db/messaging-groups.js';
 import { createPendingApproval, getSession } from '../../db/sessions.js';
@@ -220,9 +219,9 @@ export interface RequestApprovalOptions {
 }
 
 /**
- * A successfully queued hold — what the audit decorator needs to emit the
- * pending event (the id is minted and the approver picked in here, invisible
- * to callers otherwise). Null when no hold reached an approver.
+ * A successfully queued hold: the minted approval id and the approver the
+ * card was actually delivered to — both decided in here and otherwise
+ * invisible to callers. Null when no hold reached an approver.
  */
 export interface ApprovalHold {
   approvalId: string;
@@ -233,8 +232,9 @@ export interface ApprovalHold {
 /**
  * Queue an approval request. Picks an approver, delivers the card to their
  * DM, and records the pending_approvals row. Fire-and-forget from the
- * caller's perspective — the admin's response kicks off the registered
- * approval handler for this action via the response dispatcher.
+ * caller's perspective (the returned hold is informational) — the admin's
+ * response kicks off the registered approval handler for this action via the
+ * response dispatcher.
  */
 async function requestApprovalInner(opts: RequestApprovalOptions): Promise<ApprovalHold | null> {
   const { session, action, payload, title, question, agentName, approverUserId } = opts;
@@ -298,7 +298,7 @@ async function requestApprovalInner(opts: RequestApprovalOptions): Promise<Appro
 
 /**
  * Public export — the audit decorator wraps the inner request so every gated
- * hold emits its pending event from one place. Callers see Promise<void>
- * semantics as before (the hold value is audit plumbing).
+ * hold emits its pending event from one place. Pass-through: callers see the
+ * hold exactly as the inner returns it.
  */
 export const requestApproval = auditRequestApproval(requestApprovalInner);

src/modules/approvals/response-handler.audit.test.ts

@@ -30,7 +30,8 @@ vi.mock('../../container-runner.js', () => ({
   wakeContainer: vi.fn().mockResolvedValue(undefined),
 }));
 
-import { registerAuditObserver } from '../../audit/observer.js';
+// Self-registers the approvals.decide observer on import (the composed wiring).
+import './approvals-observer.audit.js';
 import { closeDb, initTestDb, runMigrations } from '../../db/index.js';
 import { createAgentGroup } from '../../db/agent-groups.js';
 import { createPendingApproval, createSession, getPendingApproval, getSession } from '../../db/sessions.js';
@@ -40,8 +41,6 @@ import { finalizeReject } from './finalize.js';
 import { registerApprovalHandler } from './primitive.js';
 import { handleApprovalsResponse } from './response-handler.js';
 
-registerAuditObserver();
-
 function now(): string {
   return new Date().toISOString();
 }

src/modules/approvals/response-handler.ts

@@ -15,7 +15,7 @@
  * The response handler is registered via core's `registerResponseHandler`;
  * core iterates handlers and the first one to return `true` claims the response.
  */
-import { runApprovedHandler } from '../../audit/index.js';
+import { runApprovedHandler } from './approvals.audit.js';
 import { wakeContainer } from '../../container-runner.js';
 import { deletePendingApproval, getPendingApproval, getSession } from '../../db/sessions.js';
 import type { ResponsePayload } from '../../response-registry.js';

src/modules/permissions/index.ts

@@ -27,13 +27,7 @@ import {
   setSenderScopeGate,
   type AccessGateResult,
 } from '../../router.js';
-import {
-  auditChannelDecision,
-  auditChannelNameInterceptor,
-  auditSenderDecision,
-  type ChannelApprovalResult,
-  type SenderApprovalResult,
-} from '../../audit/wrappers.js';
+import { auditChannelDecision, auditChannelNameInterceptor, auditSenderDecision } from './permissions.audit.js';
 import type { InboundEvent } from '../../channels/adapter.js';
 import { registerResponseHandler, type ResponsePayload } from '../../response-registry.js';
 import { getDeliveryAdapter } from '../../delivery.js';
@@ -215,6 +209,22 @@ setSenderScopeGate(
   },
 );
 
+/**
+ * What a sender-approval card click decided — who was allowed/denied into
+ * which group, and which admin decided. The response registry consumes only
+ * `claimed`; the decision descriptor is for observers composed around the
+ * handler (and for tests).
+ */
+export interface SenderDecision {
+  approved: boolean;
+  senderIdentity: string;
+  agentGroupId: string;
+  messagingGroupId: string;
+  approverId: string;
+  channelType: string;
+}
+export type SenderApprovalResult = { claimed: boolean; decision?: SenderDecision };
+
 /**
  * Response handler for the unknown-sender approval card.
  *
@@ -308,6 +318,23 @@ setChannelRequestGate(async (mg, event) => {
   await requestChannelApproval({ messagingGroupId: mg.id, event });
 });
 
+/**
+ * What a channel-registration flow decided: connected (to which agent group,
+ * created or existing), rejected, or failed — and which admin drove it. Like
+ * SenderDecision, the registry consumes only `claimed`.
+ */
+export interface ChannelDecision {
+  kind: 'connected' | 'rejected' | 'failed';
+  messagingGroupId: string;
+  approverId: string;
+  channelType?: string;
+  agentGroupId?: string;
+  createdAgentGroup?: boolean;
+  agentName?: string;
+  reason?: string;
+}
+export type ChannelApprovalResult = { claimed: boolean; decision?: ChannelDecision };
+
 /**
  * Response handler for the unknown-channel registration card.
  *
@@ -599,7 +626,7 @@ async function channelNameInterceptor(event: InboundEvent): Promise<ChannelAppro
       err,
     });
     deletePendingChannelApproval(row.messaging_group_id);
-    // The group WAS created above — the audit record must say so.
+    // The group WAS created above — the decision descriptor must say so.
     return { claimed: true, decision: { kind: 'failed', reason: 'failed to parse stored event', ...decisionBase } };
   }
 

src/modules/permissions/permissions.audit.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Permissions audit adapters: card decisions and the name interceptor.
+ * Inners are stubs — each wrapper's contract is "call through, emit the
+ * right event (or none), coerce back to claimed".
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const appended = vi.hoisted(() => ({ lines: [] as string[] }));
+
+vi.mock('../../config.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../config.js')>();
+  return { ...actual, AUDIT_ENABLED: true };
+});
+
+vi.mock('../../audit/store.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../audit/store.js')>();
+  return {
+    ...actual,
+    appendAuditLine: (line: string) => {
+      appended.lines.push(line);
+    },
+  };
+});
+
+vi.mock('../../log.js', () => ({
+  log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+}));
+
+import { auditChannelDecision, auditChannelNameInterceptor, auditSenderDecision } from './permissions.audit.js';
+
+const PAYLOAD = {
+  questionId: 'q1',
+  value: 'approve',
+  userId: 'U1',
+  channelType: 'slack',
+  platformId: 'p',
+  threadId: null,
+};
+
+function events(): Array<Record<string, any>> {
+  return appended.lines.map((l) => JSON.parse(l));
+}
+
+beforeEach(() => {
+  appended.lines.length = 0;
+});
+
+describe('auditSenderDecision', () => {
+  const decision = {
+    approved: true,
+    senderIdentity: 'slack:U0NEW',
+    agentGroupId: 'ag-1',
+    messagingGroupId: 'mg-1',
+    approverId: 'slack:U0ADMIN',
+    channelType: 'slack',
+  };
+
+  it('emits senders.allow success on approve and coerces claimed', async () => {
+    const wrapped = auditSenderDecision(async () => ({ claimed: true, decision }));
+    expect(await wrapped(PAYLOAD)).toBe(true);
+    const [event] = events();
+    expect(event).toMatchObject({
+      actor: { type: 'human', id: 'slack:U0ADMIN' },
+      origin: { transport: 'channel', channel: 'slack' },
+      action: 'senders.allow',
+      outcome: 'success',
+      correlation_id: null,
+      details: {},
+    });
+    expect(event.resources).toEqual([
+      { type: 'user', id: 'slack:U0NEW' },
+      { type: 'agent_group', id: 'ag-1' },
+      { type: 'messaging_group', id: 'mg-1' },
+    ]);
+  });
+
+  it('emits rejected on deny', async () => {
+    const wrapped = auditSenderDecision(async () => ({ claimed: true, decision: { ...decision, approved: false } }));
+    await wrapped(PAYLOAD);
+    expect(events()[0].outcome).toBe('rejected');
+  });
+
+  it('emits nothing without a decision (unclaimed or unauthorized click)', async () => {
+    const unclaimed = auditSenderDecision(async () => ({ claimed: false }));
+    const unauthorized = auditSenderDecision(async () => ({ claimed: true }));
+    expect(await unclaimed(PAYLOAD)).toBe(false);
+    expect(await unauthorized(PAYLOAD)).toBe(true);
+    expect(appended.lines).toHaveLength(0);
+  });
+});
+
+describe('auditChannelDecision / auditChannelNameInterceptor', () => {
+  const base = { messagingGroupId: 'mg-1', approverId: 'slack:U0ADMIN', channelType: 'slack' };
+
+  it('maps connected → success with the wired agent group', async () => {
+    const wrapped = auditChannelDecision(async () => ({
+      claimed: true,
+      decision: { kind: 'connected' as const, agentGroupId: 'ag-1', createdAgentGroup: false, ...base },
+    }));
+    await wrapped(PAYLOAD);
+    const [event] = events();
+    expect(event).toMatchObject({
+      action: 'channels.register',
+      outcome: 'success',
+      details: { created_agent_group: false },
+    });
+    expect(event.resources).toEqual([
+      { type: 'messaging_group', id: 'mg-1' },
+      { type: 'agent_group', id: 'ag-1' },
+    ]);
+  });
+
+  it('maps rejected and failed outcomes', async () => {
+    await auditChannelDecision(async () => ({ claimed: true, decision: { kind: 'rejected' as const, ...base } }))(
+      PAYLOAD,
+    );
+    await auditChannelDecision(async () => ({
+      claimed: true,
+      decision: { kind: 'failed' as const, reason: 'target agent group no longer exists', ...base },
+    }))(PAYLOAD);
+    const all = events();
+    expect(all[0]).toMatchObject({ action: 'channels.register', outcome: 'rejected' });
+    expect(all[1]).toMatchObject({ action: 'channels.register', outcome: 'failure' });
+    expect(all[1].details.reason).toContain('no longer exists');
+  });
+
+  it('records the interceptor-created agent group — the third creation door', async () => {
+    const wrapped = auditChannelNameInterceptor(async () => ({
+      claimed: true,
+      decision: {
+        kind: 'connected' as const,
+        agentGroupId: 'ag-new',
+        createdAgentGroup: true,
+        agentName: 'Scout',
+        ...base,
+      },
+    }));
+    expect(await wrapped({} as never)).toBe(true);
+    const [event] = events();
+    expect(event.details).toMatchObject({ created_agent_group: true, agent_name: 'Scout' });
+    expect(event.resources).toContainEqual({ type: 'agent_group', id: 'ag-new' });
+  });
+});

src/modules/permissions/permissions.audit.ts

@@ -0,0 +1,80 @@
+/**
+ * Permissions audit adapter — senders.allow and
+ * channels.register events for the card/interceptor stack that never touches
+ * the approvals primitive. The inner handlers return domain decision
+ * descriptors (SenderApprovalResult / ChannelApprovalResult, defined with the
+ * handlers); these adapters emit the event and coerce back to the boolean the
+ * response registry / router expect.
+ */
+import { emitAuditEvent } from '../../audit/emit.js';
+import type { AuditResource } from '../../audit/types.js';
+import type { InboundEvent } from '../../channels/adapter.js';
+import type { ResponsePayload } from '../../response-registry.js';
+// Type-only import from the module this adapter wraps — erased at runtime,
+// so permissions/index.ts importing this file back is not a cycle.
+import type { ChannelApprovalResult, ChannelDecision, SenderApprovalResult } from './index.js';
+
+export function auditSenderDecision(
+  inner: (payload: ResponsePayload) => Promise<SenderApprovalResult>,
+): (payload: ResponsePayload) => Promise<boolean> {
+  return async (payload) => {
+    const result = await inner(payload);
+    const d = result.decision;
+    if (d) {
+      emitAuditEvent(() => ({
+        actor: { type: 'human', id: d.approverId },
+        origin: { transport: 'channel', channel: d.channelType || undefined },
+        action: 'senders.allow',
+        resources: [
+          { type: 'user', id: d.senderIdentity },
+          { type: 'agent_group', id: d.agentGroupId },
+          { type: 'messaging_group', id: d.messagingGroupId },
+        ],
+        outcome: d.approved ? 'success' : 'rejected',
+        // The withheld message is never read here — ids only.
+        details: {},
+      }));
+    }
+    return result.claimed;
+  };
+}
+
+function emitChannelDecision(d: ChannelDecision): void {
+  emitAuditEvent(() => {
+    const resources: AuditResource[] = [{ type: 'messaging_group', id: d.messagingGroupId }];
+    if (d.agentGroupId) resources.push({ type: 'agent_group', id: d.agentGroupId });
+    const details: Record<string, unknown> = {};
+    if (d.createdAgentGroup !== undefined) details.created_agent_group = d.createdAgentGroup;
+    if (d.agentName) details.agent_name = d.agentName;
+    if (d.reason) details.reason = d.reason;
+    return {
+      actor: { type: 'human', id: d.approverId },
+      origin: { transport: 'channel', channel: d.channelType || undefined },
+      action: 'channels.register',
+      resources,
+      outcome: d.kind === 'connected' ? 'success' : d.kind === 'rejected' ? 'rejected' : 'failure',
+      details,
+    };
+  });
+}
+
+export function auditChannelDecision(
+  inner: (payload: ResponsePayload) => Promise<ChannelApprovalResult>,
+): (payload: ResponsePayload) => Promise<boolean> {
+  return async (payload) => {
+    const result = await inner(payload);
+    if (result.decision) emitChannelDecision(result.decision);
+    return result.claimed;
+  };
+}
+
+/** The free-text name reply — the third agent-creation door (new group + wiring). */
+export function auditChannelNameInterceptor(
+  inner: (event: InboundEvent) => Promise<ChannelApprovalResult>,
+): (event: InboundEvent) => Promise<boolean> {
+  return async (event) => {
+    const result = await inner(event);
+    if (result.decision) emitChannelDecision(result.decision);
+    return result.claimed;
+  };
+}