feat: /add-audit skill — opt-in ncl-surface audit log on the guard seam

Ships the local audit log as an install skill, scoped to the ncl command
surface: one withAudit(dispatch) composition at the definition site covers
both transports and the grant-carrying approved replay; holds are recorded
as pending events correlated by approval id (recovered from the hold row),
so --correlation returns the whole gated chain. src/audit/ installs as a
domain-free leaf — schema v1, recursive key-pattern redactor (JSON string
args parsed so inner secret keys mask), NDJSON day-files under data/audit/,
fail-open + loud emit, post-write exporter hooks, boot writability refusal,
self-contained retention prune (boot + daily, unref'd timer). `ncl audit
list` is host + global-scope only (off the group-scope allowlist, fails
closed) and errors clearly on a disabled box. Core reach-ins: the dispatch
composition and the resource-barrel import, both guarded by a shipped
AST/behavior wiring test; guard conformance stays clean at boot and in CI.
Approval-lifecycle events, OneCLI credential holds, and channel/sender
events are later increments that attach as pure adds.

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

.claude/skills/add-audit/REMOVE.md

@@ -0,0 +1,52 @@
+# Remove /add-audit
+
+Reverses every change the skill made. Safe to re-run even if some pieces are
+already gone. Run from the NanoClaw project root.
+
+## 1. Delete the copied files
+
+```bash
+rm -rf src/audit
+rm -f src/cli/dispatch.audit.ts src/cli/dispatch.audit.test.ts
+rm -f src/cli/resources/audit.ts
+rm -f src/audit-wiring.test.ts
+```
+
+## 2. Revert the dispatch composition
+
+In `src/cli/dispatch.ts`, delete (not comment out) the three edits the skill
+made:
+
+1. The import line: `import { withAudit } from './dispatch.audit.js';`
+2. The composition block (comment + `export const dispatch = withAudit(dispatchInner);`)
+3. Rename the dispatcher back — change `async function dispatchInner(` to
+   `export async function dispatch(`
+
+## 3. Unregister the resource
+
+Delete the `import './audit.js';` line from `src/cli/resources/index.ts`.
+
+## 4. Remove the settings
+
+Delete the `AUDIT_ENABLED` and `AUDIT_RETENTION_DAYS` lines from `.env`.
+
+## 5. Rebuild and restart
+
+```bash
+pnpm run build
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
+# systemctl --user restart $(systemd_unit)             # Linux
+```
+
+## Day-files
+
+`data/audit/*.ndjson` are the operator's records and are deliberately left in
+place. To purge them too:
+
+```bash
+rm -rf data/audit
+```
+
+No dependency was added, nothing under `container/` was touched, and no DB
+schema changed — there is nothing else to undo.

.claude/skills/add-audit/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: add-audit
+description: Add an opt-in local audit log for the ncl command surface — every dispatch outcome on both transports (host socket and container), including scope denials, approval holds, and approved replays, written as SIEM-shaped append-only NDJSON day-files under data/audit/. Read back with `ncl audit list`; plug exporters in via registerAuditHook. Off until AUDIT_ENABLED=true.
+---
+
+# /add-audit — Local Audit Log (ncl surface)
+
+Records one canonical audit event for every command that reaches the `ncl`
+dispatcher — human over the host socket or agent over the container transport
+— including denials. Both transports converge on the exported `dispatch`, so
+one composition covers the whole surface: there is no second door.
+
+```
+ncl (host socket) ──┐
+                    ├─→ dispatch = withAudit(dispatchInner) ─→ one NDJSON line
+container cli_request ┘        │                               data/audit/<UTC-day>.ndjson
+approved replay (grant) ───────┘
+```
+
+What one event carries: `actor` (`host:<os-user>` or the agent group),
+`origin` (transport, session, channel), dotted `action` from the guard
+catalog (e.g. `groups.config.add-mcp-server`), touched/attempted `resources`,
+`outcome` (`success · failure · denied · pending`), `correlation_id` (the
+approval id on gated chains — the pending event and the approved replay share
+it, so `--correlation <id>` returns the whole chain), and redacted `details`.
+
+Scope of this increment: the ncl dispatch surface only. Approval-lifecycle
+events (request/decision as their own events), OneCLI credential holds, and
+channel/sender events are later increments — they attach to `src/audit/` as
+pure adds (new `*.audit.ts` adapters and observer subscriptions).
+
+## Steps
+
+### 0. Pre-flight (idempotency)
+
+The apply is safe to re-run; every step below is guarded. Skip to
+**Enable** if all of these already hold:
+
+- `src/audit/` exists
+- `src/cli/resources/index.ts` contains `import './audit.js';`
+- `src/cli/dispatch.ts` contains `export const dispatch = withAudit(dispatchInner);`
+
+Before editing, verify the reach-in targets still exist: `src/cli/dispatch.ts`
+must contain `export async function dispatch(` (or the already-applied
+composition), and `src/cli/resources/index.ts` must be the resource barrel (a
+list of `import './<resource>.js';` lines). If either has moved, stop and
+adapt rather than guessing.
+
+### 1. Copy the payload
+
+From the NanoClaw project root:
+
+```bash
+cp -R "${CLAUDE_SKILL_DIR}/add/src/." src/
+```
+
+What lands (mirrors of the destination paths):
+
+- `src/audit/` — the domain-free leaf: event schema (`types.ts`), env config
+  (`config.ts`), redactor, NDJSON day-file store, emit seam, post-write hooks,
+  reader, boot/maintenance wiring, vocabulary — plus its tests.
+- `src/cli/dispatch.audit.ts` — the CLI adapter: `withAudit` middleware and
+  the actor/origin/resource mapping (+ `dispatch.audit.test.ts`).
+- `src/cli/resources/audit.ts` — the read-only `ncl audit` resource.
+- `src/audit-wiring.test.ts` — goes red if either core edit below is deleted
+  or drifts.
+
+### 2. Register the resource
+
+Append to `src/cli/resources/index.ts` (skip if the line is already present):
+
+```typescript
+import './audit.js';
+```
+
+### 3. Compose the dispatch middleware
+
+This is the skill's one functional reach-in, in `src/cli/dispatch.ts`. Three
+small edits:
+
+1. Add the import (next to the other `./` imports):
+
+   ```typescript
+   import { withAudit } from './dispatch.audit.js';
+   ```
+
+2. Rename the dispatcher declaration — change
+
+   ```typescript
+   export async function dispatch(
+   ```
+
+   to
+
+   ```typescript
+   async function dispatchInner(
+   ```
+
+3. Directly after that function's closing brace (before the
+   `registerApprovalHandler('cli_command', …)` block), add:
+
+   ```typescript
+   // Audit middleware (installed by /add-audit): the exported dispatch is the
+   // wrapped function, so both transports and the approved replay below all
+   // pass the one composition.
+   export const dispatch = withAudit(dispatchInner);
+   ```
+
+The composition must live at the definition site (not at the import sites):
+the approved-replay handler in the same file calls `dispatch(...)` too, and
+only the wrapped export covers it. `src/audit-wiring.test.ts` asserts exactly
+this shape via the TypeScript AST.
+
+Loading `dispatch.audit.ts` also boots the audit log: on an enabled box it
+asserts `data/audit/` is writable (refusing to start beats a silent audit
+gap), runs the boot retention prune, and arms an unref'd maintenance timer.
+Nothing else in core changes — no `index.ts` or `host-sweep.ts` edits.
+
+### 4. Enable
+
+Add the two settings to `.env` (idempotent — overwrite or append):
+
+```bash
+grep -q '^AUDIT_ENABLED=' .env && sed -i.bak 's/^AUDIT_ENABLED=.*/AUDIT_ENABLED=true/' .env && rm -f .env.bak || echo 'AUDIT_ENABLED=true' >> .env
+grep -q '^AUDIT_RETENTION_DAYS=' .env || echo 'AUDIT_RETENTION_DAYS=90' >> .env
+```
+
+`AUDIT_ENABLED` is the master switch — off (or absent) means `emitAuditEvent`
+is a no-op and `data/audit/` is never created. `AUDIT_RETENTION_DAYS`: day
+files strictly older than the horizon are hard-deleted (unlinked) at boot and
+once per UTC day; `0` = keep forever; unset = 90.
+
+### 5. Build and test
+
+Run `build` before the tests — it's what catches a missed copy or a drifted
+import path across the whole composed tree:
+
+```bash
+pnpm run build
+pnpm exec vitest run src/audit src/cli/dispatch.audit.test.ts src/audit-wiring.test.ts
+pnpm test
+```
+
+### 6. Restart the service
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
+# systemctl --user restart $(systemd_unit)             # Linux
+```
+
+### 7. Verify (runtime smoke)
+
+```bash
+ncl groups list                     # any command — this one is now an audit event
+cat data/audit/$(date -u +%F).ndjson | tail -1
+ncl audit list --limit 5
+```
+
+The last line of the day-file is the `groups.list` event you just caused.
+
+## Reading it back
+
+```
+ncl audit list [--actor <id>] [--action <name-or-prefix>] [--resource <id-or-type>]
+               [--outcome success|failure|denied|pending|approved|rejected]
+               [--since 7d|24h|30m|ISO] [--until …] [--correlation <approval-id>]
+               [--limit N] [--format ndjson]
+```
+
+Newest first, default limit 100. `--action groups.config` matches the whole
+dotted subtree. `--format ndjson` streams the stored lines verbatim — pipe to
+a file for SIEM import. On a disabled box the command errors with
+`audit log is disabled — set AUDIT_ENABLED=true` rather than returning an
+empty list that would read as "no actions happened".
+
+The resource is deliberately **not** on the group-scope allowlist: audit
+spans agent groups, so group-scoped agents are refused before the handler
+(fails closed). Host callers and `cli_scope: global` agents only.
+
+## Redaction, failure posture, exporters
+
+- Every event's `details` passes a recursive key-pattern redactor
+  (`/(token|secret|key|password|credential|auth|bearer)/i` → `[REDACTED]`,
+  ~2 KB per-value cap) at the single emit seam.
+- Fail-open + loud: a failed append is `log.error`'d and the audited action
+  proceeds. At boot, an enabled box refuses to start if `data/audit/` isn't
+  writable.
+- In-process exporters register via `registerAuditHook` (from
+  `src/audit/index.js`) — post-write hooks that fire only after the local
+  append succeeds, so an external system can never be ahead of the source of
+  truth. Ship one as its own `/add-*` skill; declare `/add-audit` as its
+  dependency.
+
+## Troubleshooting
+
+- **Host won't start, banner names the audit directory** — `AUDIT_ENABLED=true`
+  but `data/audit/` isn't writable. Fix permissions or disable audit.
+- **`audit log is disabled — set AUDIT_ENABLED=true`** — the read-back guard;
+  enable in `.env` and restart.
+- **An agent gets "CLI access is scoped to this agent group" for `ncl audit`**
+  — by design; grant the group `cli_scope: global` only if it should read
+  cross-group history.
+- **`pnpm test` on an enabled box adds a few events to today's day-file** —
+  expected: the base dispatch tests drive real dispatches. Harmless noise;
+  the audit test suites themselves write only to temp dirs or capture buffers.
+
+## Removal
+
+See [REMOVE.md](REMOVE.md) — reverses every change; existing day-files are
+left in place (they're the operator's records).

.claude/skills/add-audit/add/src/audit-wiring.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Wiring tests for the /add-audit skill's two core edits — they go red if
+ * either edit is deleted or drifts:
+ *
+ *  1. src/cli/dispatch.ts — the exported dispatch must be the composed
+ *     `withAudit(dispatchInner)` (AST check: only the definition-site
+ *     composition covers both transports AND the in-module approved replay).
+ *  2. src/cli/resources/index.ts — the audit resource must register through
+ *     the real barrel (behavior check), stay OFF the group-scope allowlist,
+ *     and leave the guard conformance walk clean.
+ *
+ * Plus the emit invariant the module's discipline rests on: emitAuditEvent
+ * appears only in src/audit/ and *.audit.ts adapter files.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+// Same production barrels the boot conformance walk sees (mirrors
+// src/guard/conformance.test.ts).
+import './cli/commands/index.js';
+import './modules/index.js';
+import './cli/delivery-action.js';
+import './cli/dispatch.js';
+
+import { commandGuard, GROUP_SCOPE_RESOURCES, lookup } from './cli/registry.js';
+import { grantContinuationGaps } from './guard-conformance.js';
+
+describe('audit resource registration (barrel wiring)', () => {
+  it('registers audit-list through the real resource barrel', () => {
+    const cmd = lookup('audit-list');
+    expect(cmd).toBeDefined();
+    expect(cmd?.action).toBe('audit.list');
+    expect(cmd?.access).toBe('open');
+  });
+
+  it('derives a guard-catalog entry for the audit command', () => {
+    const guard = commandGuard('audit-list');
+    expect(guard.action).toBe('audit.list');
+  });
+
+  it('is NOT on the group-scope allowlist — group-scoped agents fail closed', () => {
+    expect(GROUP_SCOPE_RESOURCES.has('audit')).toBe(false);
+  });
+
+  it('leaves the boot conformance walk clean with the audit resource registered', () => {
+    expect(grantContinuationGaps()).toEqual([]);
+  });
+});
+
+describe('dispatch composition (AST wiring)', () => {
+  const source = fs.readFileSync(path.resolve('src/cli/dispatch.ts'), 'utf8');
+  const sf = ts.createSourceFile('dispatch.ts', source, ts.ScriptTarget.Latest, true);
+
+  const hasExportModifier = (node: ts.HasModifiers): boolean =>
+    (ts.getModifiers(node) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+
+  let importsWithAudit = false;
+  let innerDeclaredUnexported = false;
+  let exportsWrappedDispatch = false;
+  let exportsUnwrappedDispatchFn = false;
+
+  sf.forEachChild((node) => {
+    if (
+      ts.isImportDeclaration(node) &&
+      ts.isStringLiteral(node.moduleSpecifier) &&
+      node.moduleSpecifier.text === './dispatch.audit.js'
+    ) {
+      const named = node.importClause?.namedBindings;
+      if (named && ts.isNamedImports(named) && named.elements.some((e) => e.name.text === 'withAudit')) {
+        importsWithAudit = true;
+      }
+    }
+    if (ts.isFunctionDeclaration(node) && node.name?.text === 'dispatchInner') {
+      innerDeclaredUnexported = !hasExportModifier(node);
+    }
+    if (ts.isFunctionDeclaration(node) && node.name?.text === 'dispatch' && hasExportModifier(node)) {
+      exportsUnwrappedDispatchFn = true;
+    }
+    if (ts.isVariableStatement(node) && hasExportModifier(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (
+          ts.isIdentifier(decl.name) &&
+          decl.name.text === 'dispatch' &&
+          decl.initializer &&
+          ts.isCallExpression(decl.initializer) &&
+          ts.isIdentifier(decl.initializer.expression) &&
+          decl.initializer.expression.text === 'withAudit' &&
+          decl.initializer.arguments.length === 1 &&
+          ts.isIdentifier(decl.initializer.arguments[0]) &&
+          decl.initializer.arguments[0].text === 'dispatchInner'
+        ) {
+          exportsWrappedDispatch = true;
+        }
+      }
+    }
+  });
+
+  it('imports withAudit from the audit adapter', () => {
+    expect(importsWithAudit).toBe(true);
+  });
+
+  it('keeps the inner dispatcher unexported (the guarded path is the only path)', () => {
+    expect(innerDeclaredUnexported).toBe(true);
+  });
+
+  it('exports dispatch as withAudit(dispatchInner)', () => {
+    expect(exportsWrappedDispatch).toBe(true);
+    expect(exportsUnwrappedDispatchFn).toBe(false);
+  });
+});
+
+describe('emit invariant', () => {
+  it('emitAuditEvent appears only in src/audit/ and *.audit.ts files', () => {
+    const srcRoot = path.resolve('src');
+    const offenders: string[] = [];
+    const walk = (dir: string): void => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        if (!entry.name.endsWith('.ts')) continue;
+        const rel = path.relative(srcRoot, full).split(path.sep).join('/');
+        if (rel === 'audit-wiring.test.ts') continue; // this file names the symbol
+        if (rel.startsWith('audit/')) continue;
+        if (/\.audit(\.test)?\.ts$/.test(rel)) continue;
+        if (fs.readFileSync(full, 'utf8').includes('emitAuditEvent')) offenders.push(rel);
+      }
+    };
+    walk(srcRoot);
+    expect(offenders).toEqual([]);
+  });
+});

.claude/skills/add-audit/add/src/audit/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Audit env config (installed by /add-audit) — the two audit vars, read the
+ * same way src/config.ts reads every host setting (readEnvFile from .env,
+ * with process.env taking precedence). Kept audit-owned so installing the
+ * skill never edits core config.ts: the feature's whole footprint in core is
+ * the dispatch composition in dispatch.ts and the resource-barrel import.
+ */
+import { readEnvFile } from '../env.js';
+
+const envConfig = readEnvFile(['AUDIT_ENABLED', 'AUDIT_RETENTION_DAYS']);
+
+/**
+ * Master switch. Off by default — nothing is persisted (and data/audit/ is
+ * never created) until an operator sets AUDIT_ENABLED=true.
+ */
+export const AUDIT_ENABLED = (process.env.AUDIT_ENABLED || envConfig.AUDIT_ENABLED) === 'true';
+
+/**
+ * Day-file retention horizon in days; consulted only when audit is enabled.
+ * Unset or unparseable → 90. An explicit 0 (or negative) = keep forever.
+ */
+function parseRetentionDays(raw: string | undefined): number {
+  if (raw === undefined || raw.trim() === '') return 90;
+  const n = Number.parseInt(raw, 10);
+  return Number.isNaN(n) ? 90 : n;
+}
+
+export const AUDIT_RETENTION_DAYS = parseRetentionDays(
+  process.env.AUDIT_RETENTION_DAYS || envConfig.AUDIT_RETENTION_DAYS,
+);

.claude/skills/add-audit/add/src/audit/emit.ts

@@ -0,0 +1,43 @@
+/**
+ * The single emit seam. Adapters import emitAuditEvent from here directly
+ * (it is deliberately not re-exported by the barrel): only src/audit/ and
+ * `*.audit.ts` adapter files may call it — grep holds the invariant.
+ *
+ * The opt-in check lives here, so the whole feature switches at one point.
+ * Fail-open + loud: a failed append (or a throwing input thunk) is
+ * log.error'd and the audited action proceeds.
+ */
+import { randomUUID } from 'crypto';
+
+import { log } from '../log.js';
+import { AUDIT_ENABLED } from './config.js';
+import { notifyAuditHooks } from './hooks.js';
+import { redactDetails } from './redact.js';
+import { appendAuditLine } from './store.js';
+import type { AuditEvent, AuditEventInput } from './types.js';
+
+export function emitAuditEvent(input: AuditEventInput | (() => AuditEventInput)): void {
+  if (!AUDIT_ENABLED) return; // The one opt-in check — the whole feature switches here.
+  try {
+    if (typeof input === 'function') input = input();
+    const event: AuditEvent = {
+      event_id: randomUUID(),
+      time: new Date().toISOString(),
+      schema_version: 1,
+      actor: { ...input.actor, email: null, user_id: null, group_ids: null },
+      origin: input.origin,
+      action: input.action,
+      resources: input.resources,
+      outcome: input.outcome,
+      correlation_id: input.correlationId ?? null,
+      details: redactDetails(input.details ?? {}),
+    };
+    const line = JSON.stringify(event);
+    appendAuditLine(line);
+    notifyAuditHooks(event, line);
+    // eslint-disable-next-line no-catch-all/no-catch-all -- fail-open is the posture: an audit failure must never take down the audited action
+  } catch (err) {
+    const action = typeof input === 'function' ? undefined : input.action;
+    log.error('Audit append failed — action proceeding (fail-open)', { action, err });
+  }
+}

.claude/skills/add-audit/add/src/audit/hooks.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Post-write hook contract: hooks observe the LOG (fire only after a
+ * successful append, exported ⊆ written), failures are isolated everywhere,
+ * and the lifecycle (init/maintain/shutdown) behaves.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const state = vi.hoisted(() => ({ enabled: true, appendThrows: false, appended: [] as string[] }));
+
+vi.mock('../config.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../config.js')>();
+  return {
+    ...actual,
+    DATA_DIR: '/tmp/nanoclaw-test-hooks-unused',
+  };
+});
+
+vi.mock('./config.js', () => ({
+  get AUDIT_ENABLED() {
+    return state.enabled;
+  },
+  AUDIT_RETENTION_DAYS: 90,
+}));
+
+vi.mock('./store.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./store.js')>();
+  return {
+    ...actual,
+    appendAuditLine: (line: string) => {
+      if (state.appendThrows) throw new Error('disk full');
+      state.appended.push(line);
+    },
+  };
+});
+
+vi.mock('../log.js', () => ({
+  log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
+
+let hooks: typeof import('./hooks.js');
+let emit: typeof import('./emit.js');
+let log: (typeof import('../log.js'))['log'];
+
+beforeEach(async () => {
+  state.enabled = true;
+  state.appendThrows = false;
+  state.appended.length = 0;
+  vi.resetModules(); // fresh hook registry per test
+  hooks = await import('./hooks.js');
+  emit = await import('./emit.js');
+  log = (await import('../log.js')).log;
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+const EVENT_INPUT = {
+  actor: { type: 'human' as const, id: 'host:test' },
+  origin: { transport: 'socket' as const },
+  action: 'groups.list',
+  resources: [{ type: 'agent_group' }],
+  outcome: 'success' as const,
+  details: { limit: 5 },
+};
+
+describe('post-write notification', () => {
+  it('calls a registered hook with the parsed event and the exact stored line', () => {
+    const seen: Array<{ event: import('./types.js').AuditEvent; line: string }> = [];
+    hooks.registerAuditHook({ name: 'demo', onEvent: (event, line) => seen.push({ event, line }) });
+
+    emit.emitAuditEvent(EVENT_INPUT);
+
+    expect(state.appended).toHaveLength(1);
+    expect(seen).toHaveLength(1);
+    expect(seen[0].line).toBe(state.appended[0]);
+    expect(JSON.parse(seen[0].line)).toEqual(seen[0].event);
+    expect(seen[0].event.action).toBe('groups.list');
+  });
+
+  it('does NOT call hooks when the local append fails — exported ⊆ written', () => {
+    const onEvent = vi.fn();
+    hooks.registerAuditHook({ name: 'demo', onEvent });
+    state.appendThrows = true;
+
+    expect(() => emit.emitAuditEvent(EVENT_INPUT)).not.toThrow(); // action still proceeds
+    expect(onEvent).not.toHaveBeenCalled();
+    expect(log.error).toHaveBeenCalledWith(expect.stringContaining('Audit append failed'), expect.anything());
+  });
+
+  it('does NOT call hooks when audit is disabled', () => {
+    const onEvent = vi.fn();
+    hooks.registerAuditHook({ name: 'demo', onEvent });
+    state.enabled = false;
+
+    emit.emitAuditEvent(EVENT_INPUT);
+
+    expect(state.appended).toHaveLength(0);
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+
+  it('isolates a throwing hook: the write survives, later hooks still run, the action proceeds', () => {
+    const second = vi.fn();
+    hooks.registerAuditHook({
+      name: 'broken',
+      onEvent: () => {
+        throw new Error('exporter exploded');
+      },
+    });
+    hooks.registerAuditHook({ name: 'healthy', onEvent: second });
+
+    expect(() => emit.emitAuditEvent(EVENT_INPUT)).not.toThrow();
+
+    expect(state.appended).toHaveLength(1); // the log has the event regardless
+    expect(second).toHaveBeenCalledTimes(1);
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining('Audit hook threw'),
+      expect.objectContaining({ hook: 'broken', action: 'groups.list' }),
+    );
+  });
+});
+
+describe('lifecycle', () => {
+  it('initAuditHooks surfaces a failing init as a fatal error naming the hook', () => {
+    hooks.registerAuditHook({ name: 'ok', onEvent: () => {}, init: vi.fn() });
+    hooks.registerAuditHook({
+      name: 'bad-boot',
+      onEvent: () => {},
+      init: () => {
+        throw new Error('no route to collector');
+      },
+    });
+
+    expect(() => hooks.initAuditHooks()).toThrow(/audit hook "bad-boot" failed to initialize.*no route/);
+  });
+
+  it('maintainAuditHooks calls every maintain and isolates throws', () => {
+    const m1 = vi.fn(() => {
+      throw new Error('flush failed');
+    });
+    const m2 = vi.fn();
+    hooks.registerAuditHook({ name: 'a', onEvent: () => {}, maintain: m1 });
+    hooks.registerAuditHook({ name: 'b', onEvent: () => {}, maintain: m2 });
+    hooks.registerAuditHook({ name: 'c', onEvent: () => {} }); // no maintain — fine
+
+    expect(() => hooks.maintainAuditHooks()).not.toThrow();
+    expect(m1).toHaveBeenCalledTimes(1);
+    expect(m2).toHaveBeenCalledTimes(1);
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining('maintenance failed'),
+      expect.objectContaining({ hook: 'a' }),
+    );
+  });
+
+  it('shutdownAuditHooks awaits async shutdowns and isolates throws', async () => {
+    const order: string[] = [];
+    hooks.registerAuditHook({
+      name: 'a',
+      onEvent: () => {},
+      shutdown: async () => {
+        await Promise.resolve();
+        order.push('a');
+      },
+    });
+    hooks.registerAuditHook({
+      name: 'b',
+      onEvent: () => {},
+      shutdown: () => {
+        throw new Error('handle already closed');
+      },
+    });
+    hooks.registerAuditHook({
+      name: 'c',
+      onEvent: () => {},
+      shutdown: () => {
+        order.push('c');
+      },
+    });
+
+    await hooks.shutdownAuditHooks();
+
+    expect(order).toEqual(['a', 'c']);
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining('shutdown failed'),
+      expect.objectContaining({ hook: 'b' }),
+    );
+  });
+
+  it('maintainAudit skips hook maintenance when audit is disabled', async () => {
+    const init = await import('./init.js');
+    const maintain = vi.fn();
+    hooks.registerAuditHook({ name: 'a', onEvent: () => {}, maintain });
+
+    state.enabled = false;
+    init.maintainAudit();
+    expect(maintain).not.toHaveBeenCalled();
+
+    state.enabled = true;
+    init.maintainAudit();
+    expect(maintain).toHaveBeenCalledTimes(1);
+  });
+});

.claude/skills/add-audit/add/src/audit/hooks.ts

@@ -0,0 +1,92 @@
+/**
+ * Post-write audit hooks — the in-process extension seam.
+ *
+ * A hook observes the audit LOG, not the event stream: `onEvent` fires only
+ * after an event has been durably appended to the local day-file, so anything
+ * a hook exports is guaranteed to exist in the source of truth
+ * (exported ⊆ written). If the local append fails, hooks are not called —
+ * and a hook that misses events (crash, restart) catches up by reading the
+ * day-files, which is the at-least-once story.
+ *
+ * Registration follows the tree's observer idiom (registerApprovalResolvedHandler,
+ * registerResponseHandler, …): an in-tree or skill-installed module calls
+ * `registerAuditHook(...)` at import time — no core edits, and credentials or
+ * transport for an external system live in that module, never here.
+ */
+import { log } from '../log.js';
+import type { AuditEvent } from './types.js';
+
+export interface AuditHook {
+  /** Short identifier used in logs and lifecycle errors. */
+  name: string;
+  /**
+   * Called after a successful local append. `line` is the exact stored bytes
+   * (one NDJSON line, no trailing newline); `event` is the parsed record.
+   * MUST be fast and non-blocking — this runs on the audited action's call
+   * path. A real exporter buffers here and does its IO from `maintain`/its own
+   * timers. Throwing is tolerated: isolated and logged, never propagated.
+   */
+  onEvent(event: AuditEvent, line: string): void;
+  /** Boot hook, called only when audit is enabled. Throw = host refuses to start. */
+  init?(): void;
+  /** Periodic maintenance — called from the audit maintenance timer (enabled boxes only). */
+  maintain?(): void;
+  /** Graceful-shutdown hook (flush buffers, close handles). */
+  shutdown?(): void | Promise<void>;
+}
+
+const hooks: AuditHook[] = [];
+
+export function registerAuditHook(hook: AuditHook): void {
+  hooks.push(hook);
+}
+
+/** Fan out one written event to every hook, isolating failures per hook. */
+export function notifyAuditHooks(event: AuditEvent, line: string): void {
+  for (const hook of hooks) {
+    try {
+      hook.onEvent(event, line);
+      // eslint-disable-next-line no-catch-all/no-catch-all -- isolation is the contract: one bad hook must not affect the log, other hooks, or the audited action
+    } catch (err) {
+      log.error('Audit hook threw — event is safely in the log', { hook: hook.name, action: event.action, err });
+    }
+  }
+}
+
+/** Boot lifecycle. A hook that can't start is a silent-export-gap risk — fatal. */
+export function initAuditHooks(): void {
+  for (const hook of hooks) {
+    try {
+      hook.init?.();
+    } catch (err) {
+      throw new Error(
+        `audit hook "${hook.name}" failed to initialize: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err },
+      );
+    }
+  }
+}
+
+/** Periodic lifecycle — maintenance, isolated per hook. */
+export function maintainAuditHooks(): void {
+  for (const hook of hooks) {
+    try {
+      hook.maintain?.();
+      // eslint-disable-next-line no-catch-all/no-catch-all -- one hook's maintenance failure must not stop the others (or the timer)
+    } catch (err) {
+      log.error('Audit hook maintenance failed', { hook: hook.name, err });
+    }
+  }
+}
+
+/** Shutdown lifecycle — awaited by the host's graceful shutdown. */
+export async function shutdownAuditHooks(): Promise<void> {
+  for (const hook of hooks) {
+    try {
+      await hook.shutdown?.();
+      // eslint-disable-next-line no-catch-all/no-catch-all -- shutdown must drain every hook even when one throws
+    } catch (err) {
+      log.error('Audit hook shutdown failed', { hook: hook.name, err });
+    }
+  }
+}

.claude/skills/add-audit/add/src/audit/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Opt-in local audit log — installed by /add-audit.
+ *
+ * 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 { AUDIT_ENABLED, AUDIT_RETENTION_DAYS } from './config.js';
+export { initAuditLog, maintainAudit } from './init.js';
+export { type AuditHook, registerAuditHook } from './hooks.js';

.claude/skills/add-audit/add/src/audit/init.ts

@@ -0,0 +1,54 @@
+/**
+ * Boot-time audit wiring, self-contained (installed by /add-audit).
+ *
+ * initAuditLog() runs at module load of the CLI audit adapter
+ * (cli/dispatch.audit.ts) — i.e. during the host's barrel phase, before the
+ * CLI server or any delivery poll accepts work — because dispatch.ts, which
+ * both transports import, composes withAudit at module scope. When enabled:
+ * assert data/audit/ is writable (refusing to start beats running with a
+ * silent audit gap), run the boot prune, start the registered post-write
+ * hooks, and arm the maintenance timer.
+ *
+ * The timer owns the daily cadence in-module (checked hourly; the prune
+ * itself fires at most once per UTC day) so installing the skill touches
+ * dispatch.ts and the resource barrel only — no host-sweep edit. It is
+ * unref'd: it never keeps the process alive.
+ */
+import { log } from '../log.js';
+import { onShutdown } from '../response-registry.js';
+import { AUDIT_ENABLED, AUDIT_RETENTION_DAYS } from './config.js';
+import { initAuditHooks, maintainAuditHooks, shutdownAuditHooks } from './hooks.js';
+import { assertAuditWritable, AUDIT_DIR, markPrunedToday, pruneAuditLog, pruneAuditLogIfDue } from './store.js';
+
+const MAINTENANCE_INTERVAL_MS = 60 * 60 * 1000;
+
+let initialized = false;
+
+export function initAuditLog(): void {
+  if (!AUDIT_ENABLED || initialized) return;
+  initialized = true;
+  try {
+    assertAuditWritable();
+  } catch (err) {
+    throw new Error(
+      `AUDIT_ENABLED=true but the audit directory is not writable: ${AUDIT_DIR} (${err instanceof Error ? err.message : String(err)})`,
+      { cause: err },
+    );
+  }
+  pruneAuditLog();
+  markPrunedToday();
+  initAuditHooks(); // throw → boot fails, same posture as the writability assert
+  onShutdown(() => shutdownAuditHooks());
+  setInterval(maintainAudit, MAINTENANCE_INTERVAL_MS).unref();
+  log.info('Audit log enabled', { dir: AUDIT_DIR, retentionDays: AUDIT_RETENTION_DAYS });
+}
+
+/**
+ * One maintenance tick: retention prune (throttled to once per UTC day
+ * internally) plus every hook's periodic maintenance. No-op when audit is
+ * disabled. Exported so a future scheduler can drive it too.
+ */
+export function maintainAudit(): void {
+  pruneAuditLogIfDue();
+  if (AUDIT_ENABLED) maintainAuditHooks();
+}

.claude/skills/add-audit/add/src/audit/reader.test.ts

@@ -0,0 +1,153 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const state = vi.hoisted(() => ({ dataDir: '', enabled: true }));
+
+vi.mock('../config.js', () => ({
+  get DATA_DIR() {
+    return state.dataDir;
+  },
+}));
+
+vi.mock('./config.js', () => ({
+  get AUDIT_ENABLED() {
+    return state.enabled;
+  },
+  AUDIT_RETENTION_DAYS: 90,
+}));
+
+vi.mock('../log.js', () => ({
+  log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
+
+let reader: typeof import('./reader.js');
+let store: typeof import('./store.js');
+
+beforeEach(async () => {
+  state.dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'audit-reader-'));
+  state.enabled = true;
+  vi.resetModules();
+  store = await import('./store.js');
+  reader = await import('./reader.js');
+});
+
+afterEach(() => {
+  fs.rmSync(state.dataDir, { recursive: true, force: true });
+});
+
+function dayString(daysAgo: number): string {
+  return store.utcDay(new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000));
+}
+
+function isoAt(daysAgo: number, tag: number): string {
+  const base = new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000);
+  return `${base.toISOString().slice(0, 10)}T10:00:0${tag}.000Z`;
+}
+
+let seq = 0;
+function seedEvent(daysAgo: number, overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  seq += 1;
+  const event = {
+    event_id: `e-${seq}`,
+    time: isoAt(daysAgo, seq % 10),
+    schema_version: 1,
+    actor: { type: 'human', id: 'host:moshe', email: null, user_id: null, group_ids: null },
+    origin: { transport: 'socket' },
+    action: 'groups.list',
+    resources: [{ type: 'agent_group', id: 'ag-1' }],
+    outcome: 'success',
+    correlation_id: null,
+    details: {},
+    ...overrides,
+  };
+  const dir = path.join(state.dataDir, 'audit');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(path.join(dir, `${dayString(daysAgo)}.ndjson`), JSON.stringify(event) + '\n');
+  return event;
+}
+
+describe('listAuditEvents', () => {
+  it('throws the disabled error rather than returning an empty list', () => {
+    state.enabled = false;
+    expect(() => reader.listAuditEvents({})).toThrow('audit log is disabled — set AUDIT_ENABLED=true');
+  });
+
+  it('returns flat rows newest-first across day-files, honoring --limit', () => {
+    seedEvent(2, { event_id: 'old' });
+    seedEvent(1, { event_id: 'mid-a' });
+    seedEvent(1, { event_id: 'mid-b' });
+    seedEvent(0, { event_id: 'new' });
+
+    const rows = reader.listAuditEvents({}) as Array<Record<string, unknown>>;
+    expect(rows.map((r) => r.event_id)).toEqual(['new', 'mid-b', 'mid-a', 'old']);
+    expect(rows[0]).toMatchObject({ actor: 'host:moshe', action: 'groups.list', outcome: 'success' });
+    expect(rows[0].resources).toBe('agent_group:ag-1');
+
+    const limited = reader.listAuditEvents({ limit: 2 }) as Array<Record<string, unknown>>;
+    expect(limited.map((r) => r.event_id)).toEqual(['new', 'mid-b']);
+  });
+
+  it('filters by actor, outcome, correlation, and resource (id or type)', () => {
+    seedEvent(0, { event_id: 'a', actor: { type: 'agent', id: 'ag-1' }, outcome: 'denied' });
+    seedEvent(0, { event_id: 'b', correlation_id: 'appr-9', resources: [{ type: 'approval', id: 'appr-9' }] });
+    seedEvent(0, { event_id: 'c', resources: [{ type: 'user', id: 'slack:U1' }] });
+
+    expect((reader.listAuditEvents({ actor: 'ag-1' }) as unknown[]).length).toBe(1);
+    expect((reader.listAuditEvents({ outcome: 'denied' }) as unknown[]).length).toBe(1);
+    expect((reader.listAuditEvents({ correlation: 'appr-9' }) as unknown[]).length).toBe(1);
+    expect((reader.listAuditEvents({ resource: 'slack:U1' }) as unknown[]).length).toBe(1);
+    expect((reader.listAuditEvents({ resource: 'approval' }) as unknown[]).length).toBe(1);
+  });
+
+  it('matches actions exactly or by dotted prefix', () => {
+    seedEvent(0, { event_id: 'cfg', action: 'groups.config.add-mcp-server' });
+    seedEvent(0, { event_id: 'list', action: 'groups.list' });
+    seedEvent(0, { event_id: 'other', action: 'sessions.list' });
+
+    expect((reader.listAuditEvents({ action: 'groups' }) as unknown[]).length).toBe(2);
+    expect((reader.listAuditEvents({ action: 'groups.config' }) as unknown[]).length).toBe(1);
+    expect((reader.listAuditEvents({ action: 'groups.list' }) as unknown[]).length).toBe(1);
+    // Prefix means dotted segments, not substrings.
+    expect((reader.listAuditEvents({ action: 'group' }) as unknown[]).length).toBe(0);
+  });
+
+  it('applies --since/--until with relative and ISO forms', () => {
+    seedEvent(5, { event_id: 'old' });
+    seedEvent(0, { event_id: 'recent' });
+
+    const relative = reader.listAuditEvents({ since: '2d' }) as Array<Record<string, unknown>>;
+    expect(relative.map((r) => r.event_id)).toEqual(['recent']);
+
+    const iso = reader.listAuditEvents({ until: dayString(2) }) as Array<Record<string, unknown>>;
+    expect(iso.map((r) => r.event_id)).toEqual(['old']);
+
+    expect(() => reader.listAuditEvents({ since: 'yesterdayish' })).toThrow('invalid --since');
+  });
+
+  it('--format ndjson returns the stored lines verbatim', () => {
+    const seeded = seedEvent(0, { event_id: 'x1' });
+    const out = reader.listAuditEvents({ format: 'ndjson' });
+    expect(typeof out).toBe('string');
+    expect(JSON.parse(out as string)).toEqual(seeded);
+    expect(() => reader.listAuditEvents({ format: 'csv' })).toThrow('invalid --format');
+  });
+
+  it('skips malformed stored lines and still returns the rest', () => {
+    seedEvent(0, { event_id: 'good' });
+    fs.appendFileSync(path.join(state.dataDir, 'audit', `${dayString(0)}.ndjson`), 'not-json\n');
+
+    const rows = reader.listAuditEvents({}) as Array<Record<string, unknown>>;
+    expect(rows.map((r) => r.event_id)).toEqual(['good']);
+  });
+
+  it('rejects an unknown --outcome value', () => {
+    expect(() => reader.listAuditEvents({ outcome: 'meh' })).toThrow('invalid --outcome');
+  });
+
+  it('returns empty when nothing has been recorded yet', () => {
+    expect(reader.listAuditEvents({})).toEqual([]);
+  });
+});

.claude/skills/add-audit/add/src/audit/reader.ts

@@ -0,0 +1,160 @@
+/**
+ * Read-back for `ncl audit list` — a newest-first stream-scan over the
+ * day-files. No index: fine at v1 volume, and adding one later doesn't change
+ * the store. NDJSON export returns the stored lines verbatim.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { log } from '../log.js';
+import { AUDIT_ENABLED } from './config.js';
+import { AUDIT_DIR, utcDay } from './store.js';
+import type { AuditEvent, AuditOutcome } from './types.js';
+
+const OUTCOMES: ReadonlySet<string> = new Set(['success', 'failure', 'denied', 'pending', 'approved', 'rejected']);
+const DAY_FILE_RE = /^(\d{4}-\d{2}-\d{2})\.ndjson$/;
+const DEFAULT_LIMIT = 100;
+
+export interface AuditQuery {
+  actor?: string;
+  /** Exact action or dotted prefix (`groups` matches `groups.config.update`). */
+  action?: string;
+  /** Matches any resources[] entry by id or by type. */
+  resource?: string;
+  outcome?: AuditOutcome;
+  sinceMs?: number;
+  untilMs?: number;
+  correlation?: string;
+  limit: number;
+}
+
+/** `7d` / `24h` / `30m` relative to now, or an ISO date/datetime (UTC). */
+export function parseTimeFlag(value: string, flag: string): number {
+  const rel = /^(\d+)([dhm])$/.exec(value);
+  if (rel) {
+    const n = Number(rel[1]);
+    const unitMs = rel[2] === 'd' ? 86_400_000 : rel[2] === 'h' ? 3_600_000 : 60_000;
+    return Date.now() - n * unitMs;
+  }
+  const abs = Date.parse(value);
+  if (!Number.isNaN(abs)) return abs;
+  throw new Error(`invalid ${flag} value "${value}" — use e.g. 7d, 24h, 30m, or an ISO date`);
+}
+
+/** Newest first across files and within each file, up to q.limit. */
+export function queryAuditEvents(q: AuditQuery): { events: AuditEvent[]; lines: string[] } {
+  const events: AuditEvent[] = [];
+  const lines: string[] = [];
+  let malformed = 0;
+
+  for (const { day, file } of dayFilesNewestFirst()) {
+    if (events.length >= q.limit) break;
+    // Whole-day skip: a file can't match a window its day lies outside.
+    if (q.sinceMs !== undefined && day < utcDay(new Date(q.sinceMs))) continue;
+    if (q.untilMs !== undefined && day > utcDay(new Date(q.untilMs))) continue;
+
+    let content: string;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+      // eslint-disable-next-line no-catch-all/no-catch-all -- a torn/pruned day-file must not fail the whole query
+    } catch (err) {
+      log.warn('Audit reader failed to read day-file', { file, err });
+      continue;
+    }
+    const fileLines = content.split('\n').filter((l) => l.trim() !== '');
+    // Lines within a file are chronological — walk backwards for newest-first.
+    for (let i = fileLines.length - 1; i >= 0 && events.length < q.limit; i--) {
+      let event: AuditEvent;
+      try {
+        event = JSON.parse(fileLines[i]) as AuditEvent;
+        // eslint-disable-next-line no-catch-all/no-catch-all -- malformed stored lines are skipped (counted + warned below)
+      } catch {
+        malformed++;
+        continue;
+      }
+      if (!matches(event, q)) continue;
+      events.push(event);
+      lines.push(fileLines[i]);
+    }
+  }
+
+  if (malformed > 0) {
+    log.warn('Audit reader skipped malformed lines', { malformed });
+  }
+  return { events, lines };
+}
+
+function dayFilesNewestFirst(): Array<{ day: string; file: string }> {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(AUDIT_DIR);
+    // eslint-disable-next-line no-catch-all/no-catch-all -- no audit dir yet means no events, not an error
+  } catch {
+    return [];
+  }
+  return entries
+    .map((e) => DAY_FILE_RE.exec(e))
+    .filter((m): m is RegExpExecArray => m !== null)
+    .map((m) => ({ day: m[1], file: path.join(AUDIT_DIR, m[0]) }))
+    .sort((a, b) => (a.day < b.day ? 1 : -1));
+}
+
+function matches(event: AuditEvent, q: AuditQuery): boolean {
+  if (q.actor !== undefined && event.actor?.id !== q.actor) return false;
+  if (q.action !== undefined && event.action !== q.action && !event.action?.startsWith(q.action + '.')) return false;
+  if (q.outcome !== undefined && event.outcome !== q.outcome) return false;
+  if (q.correlation !== undefined && event.correlation_id !== q.correlation) return false;
+  if (q.resource !== undefined) {
+    const hit = (event.resources ?? []).some((r) => r.id === q.resource || r.type === q.resource);
+    if (!hit) return false;
+  }
+  const t = Date.parse(event.time ?? '');
+  if (q.sinceMs !== undefined && !(t >= q.sinceMs)) return false;
+  if (q.untilMs !== undefined && !(t <= q.untilMs)) return false;
+  return true;
+}
+
+/**
+ * `ncl audit list` handler. Disabled → an explicit error: an empty list would
+ * read as "no actions happened", which is a different truth than "not
+ * recording". `--format ndjson` returns the stored lines verbatim (the human
+ * formatter passes strings through); default returns flat rows for the table.
+ */
+export function listAuditEvents(args: Record<string, unknown>): string | Array<Record<string, unknown>> {
+  if (!AUDIT_ENABLED) {
+    throw new Error('audit log is disabled — set AUDIT_ENABLED=true');
+  }
+
+  const format = args.format !== undefined ? String(args.format) : '';
+  if (format && format !== 'ndjson') {
+    throw new Error(`invalid --format "${format}" — only "ndjson" is supported`);
+  }
+  const outcome = args.outcome !== undefined ? String(args.outcome) : undefined;
+  if (outcome !== undefined && !OUTCOMES.has(outcome)) {
+    throw new Error(`invalid --outcome "${outcome}" — one of: ${[...OUTCOMES].join(', ')}`);
+  }
+
+  const q: AuditQuery = {
+    actor: args.actor !== undefined ? String(args.actor) : undefined,
+    action: args.action !== undefined ? String(args.action) : undefined,
+    resource: args.resource !== undefined ? String(args.resource) : undefined,
+    outcome: outcome as AuditOutcome | undefined,
+    correlation: args.correlation !== undefined ? String(args.correlation) : undefined,
+    sinceMs: args.since !== undefined ? parseTimeFlag(String(args.since), '--since') : undefined,
+    untilMs: args.until !== undefined ? parseTimeFlag(String(args.until), '--until') : undefined,
+    limit: args.limit !== undefined ? Math.max(1, Number(args.limit) || DEFAULT_LIMIT) : DEFAULT_LIMIT,
+  };
+
+  const { events, lines } = queryAuditEvents(q);
+  if (format === 'ndjson') return lines.join('\n');
+
+  return events.map((e) => ({
+    time: e.time,
+    actor: e.actor?.id ?? '',
+    action: e.action,
+    resources: (e.resources ?? []).map((r) => (r.id ? `${r.type}:${r.id}` : r.type)).join(' '),
+    outcome: e.outcome,
+    correlation: e.correlation_id ?? '',
+    event_id: e.event_id,
+  }));
+}

.claude/skills/add-audit/add/src/audit/redact.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import { redactDetails } from './redact.js';
+
+describe('redactDetails', () => {
+  it('masks sensitive keys at any depth, case-insensitively', () => {
+    const out = redactDetails({
+      name: 'notion',
+      env: { NOTION_TOKEN: 'secret-value', SAFE_VALUE: 'ok' },
+      nested: { Authorization: 'Bearer abc', list: [{ 'api-key': 'k' }, { plain: 'p' }] },
+      password: 'hunter2',
+    });
+    expect(out).toEqual({
+      name: 'notion',
+      env: { NOTION_TOKEN: '[REDACTED]', SAFE_VALUE: 'ok' },
+      nested: { Authorization: '[REDACTED]', list: [{ 'api-key': '[REDACTED]' }, { plain: 'p' }] },
+      password: '[REDACTED]',
+    });
+  });
+
+  it('matches the documented key pattern (token|secret|key|password|credential|auth|bearer)', () => {
+    const out = redactDetails({
+      access_token: 'x',
+      clientSecret: 'x',
+      ssh_key: 'x',
+      credentials: 'x',
+      oauth_flow: 'x',
+      bearerValue: 'x',
+      username: 'moshe',
+    });
+    expect(Object.entries(out).filter(([, v]) => v === '[REDACTED]')).toHaveLength(6);
+    expect(out.username).toBe('moshe');
+  });
+
+  it('never recurses into a masked key — the whole value is replaced', () => {
+    const out = redactDetails({ auth: { inner: 'visible?' } });
+    expect(out.auth).toBe('[REDACTED]');
+  });
+
+  it('truncates strings over 2 KB post-redaction', () => {
+    const long = 'a'.repeat(5000);
+    const out = redactDetails({ blob: long, short: 'b' });
+    expect(out.blob).toBe('a'.repeat(2048) + '…[truncated]');
+    expect(out.short).toBe('b');
+  });
+
+  it('passes non-string scalars through untouched', () => {
+    const out = redactDetails({ n: 42, b: true, z: null, u: undefined });
+    expect(out).toEqual({ n: 42, b: true, z: null, u: undefined });
+  });
+
+  it('caps depth (cycle guard) without throwing', () => {
+    const cyclic: Record<string, unknown> = { a: 1 };
+    cyclic.self = cyclic;
+    const out = redactDetails(cyclic);
+    let cursor: unknown = out;
+    for (let i = 0; i < 20 && typeof cursor === 'object' && cursor !== null; i++) {
+      cursor = (cursor as Record<string, unknown>).self;
+    }
+    expect(cursor).toBe('[MAX_DEPTH]');
+  });
+
+  it('does not mutate the input', () => {
+    const input = { token: 'x', nested: { list: ['a'.repeat(3000)] } };
+    const snapshot = JSON.parse(JSON.stringify(input));
+    redactDetails(input);
+    expect(input).toEqual(snapshot);
+  });
+});

.claude/skills/add-audit/add/src/audit/redact.ts

@@ -0,0 +1,32 @@
+/**
+ * The one redactor, applied to every event's `details` at the emit seam —
+ * guarding current and future surfaces by default. Key-pattern mask plus a
+ * per-value size cap; message bodies are never passed in (emit sites record
+ * shape only — the audit log is a governance record, not a chat archive).
+ */
+
+const SENSITIVE_KEY = /(token|secret|key|password|credential|auth|bearer)/i;
+const MAX_VALUE_CHARS = 2048;
+const MAX_DEPTH = 8;
+
+export function redactDetails(details: Record<string, unknown>): Record<string, unknown> {
+  return redactObject(details, 0);
+}
+
+function redactObject(obj: Record<string, unknown>, depth: number): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[k] = SENSITIVE_KEY.test(k) ? '[REDACTED]' : redactValue(v, depth + 1);
+  }
+  return out;
+}
+
+function redactValue(value: unknown, depth: number): unknown {
+  if (typeof value === 'string') {
+    return value.length > MAX_VALUE_CHARS ? `${value.slice(0, MAX_VALUE_CHARS)}…[truncated]` : value;
+  }
+  if (value === null || typeof value !== 'object') return value;
+  if (depth > MAX_DEPTH) return '[MAX_DEPTH]';
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, depth + 1));
+  return redactObject(value as Record<string, unknown>, depth);
+}

.claude/skills/add-audit/add/src/audit/store.test.ts

@@ -0,0 +1,187 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Core config (DATA_DIR) and the audit config (toggles) are mocked so
+// store/emit resolve a per-test temp DATA_DIR and audit switches. Getters
+// keep the values live across vi.resetModules().
+const state = vi.hoisted(() => ({ dataDir: '', enabled: true, retention: 90 }));
+
+vi.mock('../config.js', () => ({
+  get DATA_DIR() {
+    return state.dataDir;
+  },
+}));
+
+vi.mock('./config.js', () => ({
+  get AUDIT_ENABLED() {
+    return state.enabled;
+  },
+  get AUDIT_RETENTION_DAYS() {
+    return state.retention;
+  },
+}));
+
+vi.mock('../log.js', () => ({
+  log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
+
+let store: typeof import('./store.js');
+let emit: typeof import('./emit.js');
+let log: (typeof import('../log.js'))['log'];
+
+beforeEach(async () => {
+  state.dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'audit-store-'));
+  state.enabled = true;
+  state.retention = 90;
+  vi.resetModules();
+  store = await import('./store.js');
+  emit = await import('./emit.js');
+  log = (await import('../log.js')).log;
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  fs.chmodSync(path.join(state.dataDir), 0o700);
+  const auditDir = path.join(state.dataDir, 'audit');
+  if (fs.existsSync(auditDir)) fs.chmodSync(auditDir, 0o700);
+  fs.rmSync(state.dataDir, { recursive: true, force: true });
+});
+
+function auditDir(): string {
+  return path.join(state.dataDir, 'audit');
+}
+
+function writeDayFile(day: string, lines = 1): void {
+  fs.mkdirSync(auditDir(), { recursive: true });
+  fs.writeFileSync(path.join(auditDir(), `${day}.ndjson`), '{"x":1}\n'.repeat(lines));
+}
+
+function dayString(daysAgo: number): string {
+  return store.utcDay(new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000));
+}
+
+const EVENT_INPUT = {
+  actor: { type: 'human' as const, id: 'host:test' },
+  origin: { transport: 'socket' as const },
+  action: 'groups.list',
+  resources: [{ type: 'agent_group' }],
+  outcome: 'success' as const,
+};
+
+describe('appendAuditLine', () => {
+  it("appends one line to today's UTC day-file, creating the directory lazily", () => {
+    expect(fs.existsSync(auditDir())).toBe(false);
+    store.appendAuditLine('{"a":1}');
+    store.appendAuditLine('{"b":2}');
+    const file = path.join(auditDir(), `${store.utcDay()}.ndjson`);
+    expect(fs.readFileSync(file, 'utf8')).toBe('{"a":1}\n{"b":2}\n');
+  });
+});
+
+describe('emitAuditEvent', () => {
+  it('writes a schema_version-1 record with envelope fields and null enrichment', () => {
+    emit.emitAuditEvent({ ...EVENT_INPUT, details: { limit: 100 } });
+    const file = path.join(auditDir(), `${store.utcDay()}.ndjson`);
+    const record = JSON.parse(fs.readFileSync(file, 'utf8').trim());
+    expect(record).toMatchObject({
+      schema_version: 1,
+      actor: { type: 'human', id: 'host:test', email: null, user_id: null, group_ids: null },
+      origin: { transport: 'socket' },
+      action: 'groups.list',
+      outcome: 'success',
+      correlation_id: null,
+      details: { limit: 100 },
+    });
+    expect(record.event_id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(new Date(record.time).toISOString()).toBe(record.time);
+  });
+
+  it('redacts details at the emit seam', () => {
+    emit.emitAuditEvent({ ...EVENT_INPUT, details: { env: { API_TOKEN: 'x' } } });
+    const file = path.join(auditDir(), `${store.utcDay()}.ndjson`);
+    expect(fs.readFileSync(file, 'utf8')).toContain('"API_TOKEN":"[REDACTED]"');
+  });
+
+  it('is a no-op when audit is disabled — the directory is never created', () => {
+    state.enabled = false;
+    emit.emitAuditEvent(EVENT_INPUT);
+    expect(fs.existsSync(auditDir())).toBe(false);
+  });
+
+  it('fails open and loud when the append fails', () => {
+    fs.mkdirSync(auditDir(), { recursive: true });
+    fs.chmodSync(auditDir(), 0o500);
+    expect(() => emit.emitAuditEvent(EVENT_INPUT)).not.toThrow();
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining('Audit append failed'),
+      expect.objectContaining({ action: 'groups.list' }),
+    );
+  });
+});
+
+describe('assertAuditWritable', () => {
+  it('creates the directory and probes it with a zero-byte append', () => {
+    store.assertAuditWritable();
+    expect(fs.existsSync(path.join(auditDir(), `${store.utcDay()}.ndjson`))).toBe(true);
+  });
+
+  it('throws when the directory is not writable', () => {
+    fs.mkdirSync(auditDir(), { recursive: true });
+    fs.chmodSync(auditDir(), 0o500);
+    expect(() => store.assertAuditWritable()).toThrow();
+  });
+});
+
+describe('pruneAuditLog', () => {
+  it('unlinks only day-files strictly older than the horizon', () => {
+    writeDayFile(dayString(100));
+    writeDayFile(dayString(91));
+    writeDayFile(dayString(90));
+    writeDayFile(dayString(1));
+    fs.writeFileSync(path.join(auditDir(), 'not-a-day-file.txt'), 'keep');
+    fs.writeFileSync(path.join(auditDir(), '2026-01-01.ndjson.bak'), 'keep');
+    store.pruneAuditLog(90);
+    const left = fs.readdirSync(auditDir()).sort();
+    expect(left).toEqual(
+      [`${dayString(90)}.ndjson`, `${dayString(1)}.ndjson`, '2026-01-01.ndjson.bak', 'not-a-day-file.txt'].sort(),
+    );
+  });
+
+  it('keeps forever when retention is 0', () => {
+    writeDayFile(dayString(400));
+    store.pruneAuditLog(0);
+    expect(fs.existsSync(path.join(auditDir(), `${dayString(400)}.ndjson`))).toBe(true);
+  });
+
+  it('is a no-op when the audit directory does not exist', () => {
+    expect(() => store.pruneAuditLog(90)).not.toThrow();
+  });
+});
+
+describe('pruneAuditLogIfDue', () => {
+  it('prunes at most once per UTC day', () => {
+    writeDayFile(dayString(100));
+    store.pruneAuditLogIfDue();
+    expect(fs.existsSync(path.join(auditDir(), `${dayString(100)}.ndjson`))).toBe(false);
+    writeDayFile(dayString(100));
+    store.pruneAuditLogIfDue();
+    expect(fs.existsSync(path.join(auditDir(), `${dayString(100)}.ndjson`))).toBe(true);
+  });
+
+  it('does nothing when audit is disabled', () => {
+    state.enabled = false;
+    writeDayFile(dayString(100));
+    store.pruneAuditLogIfDue();
+    expect(fs.existsSync(path.join(auditDir(), `${dayString(100)}.ndjson`))).toBe(true);
+  });
+
+  it('does nothing after markPrunedToday until the day rolls over', () => {
+    store.markPrunedToday();
+    writeDayFile(dayString(100));
+    store.pruneAuditLogIfDue();
+    expect(fs.existsSync(path.join(auditDir(), `${dayString(100)}.ndjson`))).toBe(true);
+  });
+});

.claude/skills/add-audit/add/src/audit/store.ts

@@ -0,0 +1,81 @@
+/**
+ * Day-file store — daily NDJSON files under data/audit/, host process is the
+ * single writer. Append-only is structural: nothing here can update a line,
+ * and retention is unlinking whole files (a literal hard delete). Both
+ * transports converge host-side, so single-writer holds by construction.
+ *
+ * This module throws on fs failure; the fail-open posture (log.error, action
+ * proceeds) lives in emit.ts, and the boot-time strictness (refuse to start)
+ * lives in init.ts.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { DATA_DIR } from '../config.js';
+import { log } from '../log.js';
+import { AUDIT_ENABLED, AUDIT_RETENTION_DAYS } from './config.js';
+
+export const AUDIT_DIR = path.join(DATA_DIR, 'audit');
+const DAY_FILE_RE = /^(\d{4}-\d{2}-\d{2})\.ndjson$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function utcDay(d: Date = new Date()): string {
+  return d.toISOString().slice(0, 10);
+}
+
+export function dayFilePath(day: string): string {
+  return path.join(AUDIT_DIR, `${day}.ndjson`);
+}
+
+/** The single append point. Throws on fs failure — emitAuditEvent catches. */
+export function appendAuditLine(line: string): void {
+  fs.mkdirSync(AUDIT_DIR, { recursive: true });
+  fs.appendFileSync(dayFilePath(utcDay()), line + '\n');
+}
+
+/** Boot-time writability assert — a zero-byte append is a true write probe. */
+export function assertAuditWritable(): void {
+  fs.mkdirSync(AUDIT_DIR, { recursive: true });
+  fs.appendFileSync(dayFilePath(utcDay()), '');
+}
+
+/** Unlink day-files strictly older than (today UTC − retentionDays). 0 or negative = keep forever. */
+export function pruneAuditLog(retentionDays: number = AUDIT_RETENTION_DAYS): void {
+  if (retentionDays <= 0) return;
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(AUDIT_DIR);
+    // eslint-disable-next-line no-catch-all/no-catch-all -- no audit dir yet means nothing to prune, not an error
+  } catch {
+    return;
+  }
+  const horizon = utcDay(new Date(Date.now() - retentionDays * DAY_MS));
+  let pruned = 0;
+  for (const entry of entries) {
+    const m = DAY_FILE_RE.exec(entry);
+    if (!m || m[1] >= horizon) continue;
+    try {
+      fs.unlinkSync(path.join(AUDIT_DIR, entry));
+      pruned++;
+      // eslint-disable-next-line no-catch-all/no-catch-all -- one stuck file must not stop the prune of the others
+    } catch (err) {
+      log.error('Audit prune failed to unlink day-file', { file: entry, err });
+    }
+  }
+  if (pruned > 0) log.info('Audit retention pruned day-files', { pruned, retentionDays });
+}
+
+let lastPruneDay: string | null = null;
+
+/** Retention prune, throttled to once per UTC day — safe to call every tick. */
+export function pruneAuditLogIfDue(): void {
+  if (!AUDIT_ENABLED || AUDIT_RETENTION_DAYS <= 0) return;
+  const today = utcDay();
+  if (lastPruneDay === today) return;
+  lastPruneDay = today;
+  pruneAuditLog();
+}
+
+export function markPrunedToday(): void {
+  lastPruneDay = utcDay();
+}

.claude/skills/add-audit/add/src/audit/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Canonical audit event — one flat, SIEM-shaped record per action.
+ *
+ * Fields are chosen so they project losslessly onto OCSF and Elastic ECS
+ * (the two schemas SIEMs converge on); the store keeps the neutral shape and
+ * a future forwarder pays the translation once, at the edge. `schema_version`
+ * covers evolution — additive changes only within a version.
+ */
+
+export type AuditActorType = 'human' | 'agent' | 'system';
+
+export interface AuditActor {
+  type: AuditActorType;
+  /** `host:<os-user>` | `<channel>:<handle>` | agent group id | `host` (system). */
+  id: string;
+}
+
+export interface AuditOrigin {
+  transport: 'socket' | 'container' | 'channel';
+  session_id?: string;
+  messaging_group_id?: string;
+  channel?: string;
+}
+
+export interface AuditResource {
+  type: string;
+  /** Omitted when only the attempted type is known (e.g. a denied list). */
+  id?: string;
+}
+
+export type AuditOutcome = 'success' | 'failure' | 'denied' | 'pending' | 'approved' | 'rejected';
+
+/** What emit sites provide. Envelope fields are stamped by emitAuditEvent. */
+export interface AuditEventInput {
+  actor: AuditActor;
+  origin: AuditOrigin;
+  /** Dotted namespaced verb, e.g. `groups.config.add-mcp-server`. */
+  action: string;
+  resources: AuditResource[];
+  outcome: AuditOutcome;
+  /** The approval id on gated chains; null/omitted otherwise. */
+  correlationId?: string | null;
+  details?: Record<string, unknown>;
+}
+
+export interface AuditEvent {
+  event_id: string;
+  time: string;
+  schema_version: 1;
+  actor: AuditActor & { email: null; user_id: null; group_ids: null };
+  origin: AuditOrigin;
+  action: string;
+  resources: AuditResource[];
+  outcome: AuditOutcome;
+  correlation_id: string | null;
+  details: Record<string, unknown>;
+}
+
+/** Actor for timer/sweep-driven outcomes (expiries, startup sweeps). */
+export const SYSTEM_ACTOR: AuditActor = { type: 'system', id: 'host' };

.claude/skills/add-audit/add/src/audit/vocab.ts

@@ -0,0 +1,39 @@
+/**
+ * Domain-free event vocabulary — actor and origin constructors shared by the
+ * domain-owned `*.audit.ts` adapters (the CLI adapter today; approval and
+ * channel adapters attach here in later increments). 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)
+ * lives in the adapter file of the domain that owns it.
+ */
+import os from 'os';
+
+import { getMessagingGroup } from '../db/messaging-groups.js';
+import type { AuditOrigin } 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';
+  }
+}
+
+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;
+}

.claude/skills/add-audit/add/src/cli/dispatch.audit.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Audit middleware behavior of the exported dispatch — what gets recorded,
+ * for whom, and how gated chains correlate. Drives the real wrapped dispatch
+ * (real registry, real guard); audit is force-enabled and the store's append
+ * is captured. DB reads and approval delivery are mocked.
+ */
+import os from 'os';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { PendingApproval } from '../types.js';
+
+const appended = vi.hoisted(() => ({ lines: [] as string[] }));
+const pendingRows = vi.hoisted(() => ({ rows: [] as unknown[] }));
+
+vi.mock('../audit/config.js', () => ({
+  AUDIT_ENABLED: true,
+  AUDIT_RETENTION_DAYS: 90,
+}));
+
+// Neutralize the adapter's module-scope boot (writability assert, prune,
+// maintenance timer) — the middleware is the unit under test here.
+vi.mock('../audit/init.js', () => ({
+  initAuditLog: vi.fn(),
+  maintainAudit: vi.fn(),
+}));
+
+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: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
+
+const mockGetContainerConfig = vi.fn();
+vi.mock('../db/container-configs.js', () => ({
+  getContainerConfig: (...args: unknown[]) => mockGetContainerConfig(...args),
+}));
+
+vi.mock('../db/agent-groups.js', () => ({
+  getAgentGroup: vi.fn(() => ({ id: 'g1', name: 'Group One' })),
+}));
+
+const mockGetPendingApproval = vi.fn();
+vi.mock('../db/sessions.js', () => ({
+  getSession: vi.fn(() => ({ id: 's1', agent_group_id: 'g1', messaging_group_id: 'mg1' })),
+  getPendingApproval: (...args: unknown[]) => mockGetPendingApproval(...args),
+  getPendingApprovalsByAction: () => pendingRows.rows,
+}));
+
+vi.mock('../db/messaging-groups.js', () => ({
+  getMessagingGroup: vi.fn(() => ({ channel_type: 'slack' })),
+}));
+
+const mockGetResource = vi.fn();
+vi.mock('./crud.js', () => ({
+  getResource: (...args: unknown[]) => mockGetResource(...args),
+}));
+
+vi.mock('../modules/approvals/index.js', () => ({
+  registerApprovalHandler: vi.fn(),
+  requestApproval: vi.fn(async () => undefined),
+}));
+
+import { register } from './registry.js';
+
+register({
+  name: 'groups-test',
+  description: 'echo command on the groups resource',
+  action: 'groups.test',
+  resource: 'groups',
+  access: 'open',
+  parseArgs: (raw) => raw,
+  handler: async (args) => ({ echo: args }),
+});
+
+register({
+  name: 'groups-get',
+  description: 'echo command for dash-joined id resolution',
+  action: 'groups.get',
+  resource: 'groups',
+  access: 'open',
+  parseArgs: (raw) => raw,
+  handler: async (args) => ({ echo: args }),
+});
+
+register({
+  name: 'wirings-list',
+  description: 'not on the group-scope allowlist',
+  action: 'wirings.list',
+  resource: 'wirings',
+  access: 'open',
+  parseArgs: (raw) => raw,
+  handler: async () => [],
+});
+
+register({
+  name: 'groups-fail',
+  description: 'handler that throws',
+  action: 'groups.fail',
+  resource: 'groups',
+  access: 'open',
+  parseArgs: (raw) => raw,
+  handler: async () => {
+    throw new Error('boom');
+  },
+});
+
+register({
+  name: 'groups-gated',
+  description: 'approval-gated command',
+  action: 'groups.gated',
+  resource: 'groups',
+  access: 'approval',
+  parseArgs: (raw) => raw,
+  handler: async () => 'ran',
+});
+
+import { dispatch } from './dispatch.js';
+import type { CallerContext } from './frame.js';
+
+const AGENT_CTX: CallerContext = { caller: 'agent', sessionId: 's1', agentGroupId: 'g1', messagingGroupId: 'mg1' };
+
+function grantRow(frameId: string, command: string): PendingApproval {
+  return {
+    approval_id: 'appr-123-abc',
+    session_id: 's1',
+    request_id: 'appr-123-abc',
+    action: 'cli_command',
+    payload: JSON.stringify({ frame: { id: frameId, command, args: {} }, callerContext: AGENT_CTX }),
+    created_at: new Date().toISOString(),
+    agent_group_id: 'g1',
+    channel_type: null,
+    platform_id: null,
+    platform_message_id: null,
+    expires_at: null,
+    status: 'pending',
+    title: 'CLI: groups-gated',
+    options_json: '[]',
+    approver_user_id: null,
+  };
+}
+
+function events(): Array<Record<string, any>> {
+  return appended.lines.map((l) => JSON.parse(l));
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  appended.lines.length = 0;
+  pendingRows.rows = [];
+  mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });
+  mockGetResource.mockImplementation((plural: string) => (plural === 'groups' ? { scopeField: 'id' } : undefined));
+});
+
+describe('withAudit(dispatch)', () => {
+  it('records a success event for a host caller with socket origin and host actor', async () => {
+    const resp = await dispatch({ id: '1', command: 'groups-test', args: { foo: 'bar' } }, { caller: 'host' });
+
+    expect(resp.ok).toBe(true);
+    const [event] = events();
+    expect(event).toMatchObject({
+      schema_version: 1,
+      actor: { type: 'human', id: `host:${os.userInfo().username}`, email: null },
+      origin: { transport: 'socket' },
+      action: 'groups.test',
+      outcome: 'success',
+      correlation_id: null,
+      details: { foo: 'bar' },
+    });
+  });
+
+  it('records effective args after group auto-fill, with container origin and channel', async () => {
+    await dispatch({ id: '1', command: 'groups-test', args: {} }, AGENT_CTX);
+
+    const [event] = events();
+    expect(event.actor).toMatchObject({ type: 'agent', id: 'g1' });
+    expect(event.origin).toEqual({
+      transport: 'container',
+      session_id: 's1',
+      messaging_group_id: 'mg1',
+      channel: 'slack',
+    });
+    expect(event.details).toMatchObject({ id: 'g1', agent_group_id: 'g1', group: 'g1' });
+    expect(event.resources).toContainEqual({ type: 'agent_group', id: 'g1' });
+  });
+
+  it('records a denied event for a scope denial, naming the attempted resource type', async () => {
+    const resp = await dispatch({ id: '1', command: 'wirings-list', args: {} }, AGENT_CTX);
+
+    expect(resp.ok).toBe(false);
+    const [event] = events();
+    expect(event).toMatchObject({
+      action: 'wirings.list',
+      outcome: 'denied',
+      resources: [{ type: 'wirings' }],
+      details: { error: 'forbidden' },
+    });
+    expect(event.details.reason).toContain('scoped');
+  });
+
+  it('records a failure event when the handler throws', async () => {
+    await dispatch({ id: '1', command: 'groups-fail', args: {} }, { caller: 'host' });
+
+    const [event] = events();
+    expect(event).toMatchObject({ action: 'groups.fail', outcome: 'failure', details: { error: 'handler-error' } });
+    expect(event.details.reason).toContain('boom');
+  });
+
+  it('records a hold as a pending event correlated to the approval row it created', async () => {
+    pendingRows.rows = [grantRow('1', 'groups-gated')];
+
+    const resp = await dispatch({ id: '1', command: 'groups-gated', args: {} }, AGENT_CTX);
+
+    expect(resp.ok).toBe(false);
+    if (!resp.ok) expect(resp.error.code).toBe('approval-pending');
+    const [event] = events();
+    expect(event).toMatchObject({
+      action: 'groups.gated',
+      outcome: 'pending',
+      correlation_id: 'appr-123-abc',
+    });
+    expect(event.resources).toContainEqual({ type: 'approval', id: 'appr-123-abc' });
+    expect(event.details.error).toBeUndefined();
+  });
+
+  it('records an uncorrelated pending event when no approval row was created (no approver)', async () => {
+    pendingRows.rows = [];
+
+    await dispatch({ id: '1', command: 'groups-gated', args: {} }, AGENT_CTX);
+
+    const [event] = events();
+    expect(event).toMatchObject({ outcome: 'pending', correlation_id: null });
+  });
+
+  it('records an approved replay as success with the grant approval id as correlation_id', async () => {
+    const grant = grantRow('9', 'groups-gated');
+    mockGetPendingApproval.mockReturnValue(grant);
+
+    const resp = await dispatch({ id: '9', command: 'groups-gated', args: {} }, AGENT_CTX, { grant });
+
+    expect(resp.ok).toBe(true);
+    const [event] = events();
+    expect(event).toMatchObject({
+      action: 'groups.gated',
+      outcome: 'success',
+      correlation_id: 'appr-123-abc',
+    });
+    expect(event.resources).toContainEqual({ type: 'approval', id: 'appr-123-abc' });
+  });
+
+  it('records unknown commands as cli.unknown-command with the raw name in details', async () => {
+    await dispatch({ id: '1', command: 'nope-nothing', args: {} }, { caller: 'host' });
+
+    const [event] = events();
+    expect(event).toMatchObject({
+      action: 'cli.unknown-command',
+      outcome: 'failure',
+      resources: [],
+      details: { command: 'nope-nothing', error: 'unknown-command' },
+    });
+  });
+
+  it('records the resolved command and id for dash-joined positional ids', async () => {
+    const uuid = '550e8400-e29b-41d4-a716-446655440000';
+    await dispatch({ id: '1', command: `groups-get-${uuid}`, args: {} }, { caller: 'host' });
+
+    const [event] = events();
+    expect(event).toMatchObject({ action: 'groups.get', outcome: 'success' });
+    expect(event.resources).toContainEqual({ type: 'agent_group', id: uuid });
+    expect(event.details.id).toBe(uuid);
+  });
+
+  it('normalizes hyphenated arg keys in details', async () => {
+    await dispatch({ id: '1', command: 'groups-test', args: { 'dry-run': 'true' } }, { caller: 'host' });
+
+    const [event] = events();
+    expect(event.details).toMatchObject({ dry_run: 'true' });
+  });
+
+  it('parses JSON string args so the redactor reaches their inner keys', async () => {
+    await dispatch(
+      { id: '1', command: 'groups-test', args: { env: '{"NOTION_TOKEN":"tok-123","SAFE":"ok"}', note: '{not json' } },
+      { caller: 'host' },
+    );
+
+    const [event] = events();
+    expect(event.details.env).toEqual({ NOTION_TOKEN: '[REDACTED]', SAFE: 'ok' });
+    expect(event.details.note).toBe('{not json');
+  });
+});

.claude/skills/add-audit/add/src/cli/dispatch.audit.ts

@@ -0,0 +1,238 @@
+/**
+ * CLI audit adapter (installed by /add-audit) — 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.
+ *
+ * Loading this module also boots the audit log (writability assert, boot
+ * prune, hook lifecycle, maintenance timer): dispatch.ts is imported by both
+ * transports during the host's barrel phase, so initAuditLog() runs before
+ * any command is accepted — and an enabled box with an unwritable
+ * data/audit/ refuses to start.
+ */
+import { emitAuditEvent } from '../audit/emit.js';
+import { initAuditLog } from '../audit/init.js';
+import { type AuditActor, type AuditOrigin, type AuditOutcome, type AuditResource } from '../audit/types.js';
+import { containerOrigin, hostUser } from '../audit/vocab.js';
+import { getContainerConfig } from '../db/container-configs.js';
+import { getPendingApprovalsByAction } from '../db/sessions.js';
+import type { PendingApproval } from '../types.js';
+import { getResource } from './crud.js';
+import type { CallerContext, RequestFrame, ResponseFrame } from './frame.js';
+import { type CommandDef, lookup } from './registry.js';
+
+initAuditLog();
+
+// ── 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;
+}
+
+// ── Dispatch mechanics, mirrored for the record ──
+// Dispatch resolves the command and auto-fills args on a local copy of the
+// frame that never leaves it, so the middleware mirrors the two documented
+// mechanics below. The copies are mechanical, and drift only ever degrades a
+// record's detail (a fallback action name, a missing auto-filled arg) — never
+// dispatch behavior, and never an outcome.
+
+/**
+ * Mirror of dispatch's command resolution: exact lookup, then the longest
+ * registered dash-prefix with the remainder recorded as --id.
+ */
+function resolveForRecord(req: RequestFrame): { cmd?: CommandDef; args: Record<string, unknown> } {
+  const direct = lookup(req.command);
+  if (direct) return { cmd: direct, args: req.args };
+  let shortened = req.command;
+  let idx: number;
+  while ((idx = shortened.lastIndexOf('-')) > 0) {
+    shortened = shortened.slice(0, idx);
+    const fallback = lookup(shortened);
+    if (fallback) {
+      const tail = req.command.slice(shortened.length + 1);
+      return { cmd: fallback, args: { ...req.args, id: req.args.id ?? tail } };
+    }
+  }
+  return { args: req.args };
+}
+
+/**
+ * Mirror of dispatch's group-scope arg auto-fill, so the record shows the
+ * effective args the handler saw (e.g. which agent group a bare
+ * `sessions list` actually listed).
+ */
+function effectiveArgs(
+  cmd: CommandDef | undefined,
+  args: Record<string, unknown>,
+  ctx: CallerContext,
+): Record<string, unknown> {
+  if (ctx.caller !== 'agent') return args;
+  if ((getContainerConfig(ctx.agentGroupId)?.cli_scope ?? 'group') !== 'group') return args;
+  const fill: Record<string, unknown> = {
+    agent_group_id: args.agent_group_id ?? ctx.agentGroupId,
+    group: args.group ?? ctx.agentGroupId,
+  };
+  if (cmd?.resource === 'groups' || cmd?.resource === 'destinations') {
+    fill.id = args.id ?? ctx.agentGroupId;
+  }
+  return { ...args, ...fill };
+}
+
+/**
+ * CLI args arrive as strings, so a JSON-object/array value (e.g.
+ * `--env '{"NOTION_TOKEN":"…"}'`) would reach the redactor as one opaque
+ * string under an innocent key and its inner secret keys would survive.
+ * Recording the parsed form lets the redactor walk inside — the audit log's
+ * "secrets never land" property depends on it for exactly this flow.
+ */
+function parseJsonishValues(args: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(args)) {
+    if (typeof v === 'string' && (v.startsWith('{') || v.startsWith('['))) {
+      try {
+        out[k] = JSON.parse(v);
+        continue;
+        // eslint-disable-next-line no-catch-all/no-catch-all -- not JSON after all: record the string as-is
+      } catch {
+        /* fall through */
+      }
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * The approval row a hold just created for this frame — it gives the pending
+ * event the same correlation_id the approved replay will carry as its guard
+ * grant. requestApproval keeps the minted id internal, so the row is
+ * recovered by the frame id it stored in its payload; no row (e.g. no
+ * configured approver) → the hold is still recorded, uncorrelated.
+ */
+function holdApprovalIdFor(frameId: string): string | null {
+  const rows = getPendingApprovalsByAction('cli_command');
+  for (let i = rows.length - 1; i >= 0; i--) {
+    try {
+      const payload = JSON.parse(rows[i].payload) as { frame?: { id?: string } };
+      if (payload.frame?.id === frameId) return rows[i].approval_id;
+      // eslint-disable-next-line no-catch-all/no-catch-all -- a row with an unparseable payload is simply not this frame's hold
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// ── The dispatch middleware ──
+
+type DispatchInner = (
+  req: RequestFrame,
+  ctx: CallerContext,
+  opts?: { grant?: PendingApproval },
+) => Promise<ResponseFrame>;
+
+/**
+ * Dispatch middleware — the exported `dispatch` is the wrapped function, so
+ * the socket server, the container delivery-action, and the in-module
+ * approved replay are all covered by the one composition.
+ *
+ * Outcome derives from the response frame: ok → success, forbidden → denied
+ * (captures pre-handler scope denials), approval-pending → pending (the
+ * record of a hold), anything else → failure. Correlation is the approval id:
+ * an approved replay carries the approval row as its guard grant
+ * (opts.grant), and a fresh hold is correlated by recovering the row it just
+ * created — so `--correlation <approval-id>` returns the whole gated chain.
+ */
+export function withAudit(inner: DispatchInner): DispatchInner {
+  return async (req, ctx, opts = {}) => {
+    const res = await inner(req, ctx, opts);
+    emitAuditEvent(() => {
+      const resolved = resolveForRecord(req);
+      const cmd = resolved.cmd;
+      const pending = !res.ok && res.error.code === 'approval-pending';
+      const outcome: AuditOutcome = res.ok
+        ? 'success'
+        : res.error.code === 'forbidden'
+          ? 'denied'
+          : pending
+            ? 'pending'
+            : 'failure';
+      // A denial records the attempt as asked (raw args): nothing ran, so the
+      // auto-fill never conceptually happened — and a cross-group attempt
+      // must show the foreign id the caller passed, not a filled-in own-group.
+      const args = normalizeArgKeys(outcome === 'denied' ? resolved.args : effectiveArgs(cmd, resolved.args, ctx));
+      const correlationId = opts.grant?.approval_id ?? (pending ? holdApprovalIdFor(req.id) : null);
+      const details: Record<string, unknown> = parseJsonishValues(args);
+      if (!res.ok && !pending) {
+        details.error = res.error.code;
+        details.reason = res.error.message;
+      }
+      if (!cmd) details.command = req.command;
+      const resources = cmd ? resourcesForCli(cmd, args) : [];
+      if (correlationId) resources.push({ type: 'approval', id: correlationId });
+      return {
+        actor: actorForCaller(ctx),
+        origin: originForCaller(ctx),
+        action: cmd ? (cmd.action ?? `cli.${cmd.name}`) : 'cli.unknown-command',
+        resources,
+        outcome,
+        correlationId,
+        details,
+      };
+    });
+    return res;
+  };
+}

.claude/skills/add-audit/add/src/cli/resources/audit.ts

@@ -0,0 +1,56 @@
+import { listAuditEvents } from '../../audit/reader.js';
+import { registerResource } from '../crud.js';
+
+/**
+ * Read-only audit resource (installed by /add-audit). The "table" is the
+ * NDJSON day-file store — no generic CRUD verbs are declared, so it is never
+ * queried as SQL; `list` is a custom operation backed by the audit reader.
+ *
+ * Deliberately NOT on the group-scope allowlist (GROUP_SCOPE_RESOURCES):
+ * audit spans agent groups, so group-scoped agents are refused before the
+ * handler — the resource is host + `cli_scope: global` only, by omission
+ * (fails closed).
+ */
+registerResource({
+  name: 'audit_event',
+  plural: 'audit',
+  table: '(data/audit/*.ndjson)',
+  description: 'Local audit log — one event per ncl command. Newest first. Requires AUDIT_ENABLED=true.',
+  idColumn: 'event_id',
+  columns: [
+    { name: 'actor', type: 'string', description: 'Filter: exact actor id (host:<user>, <channel>:<handle>, agent group id)' },
+    { name: 'action', type: 'string', description: 'Filter: exact action or dotted prefix (e.g. groups.config)' },
+    { name: 'resource', type: 'string', description: 'Filter: matches any event resource by id or type' },
+    {
+      name: 'outcome',
+      type: 'string',
+      description: 'Filter: event outcome',
+      enum: ['success', 'failure', 'denied', 'pending', 'approved', 'rejected'],
+    },
+    { name: 'since', type: 'string', description: 'Window start: 7d / 24h / 30m relative, or ISO date' },
+    { name: 'until', type: 'string', description: 'Window end: same formats as --since' },
+    { name: 'correlation', type: 'string', description: 'Filter: approval id tying a gated chain together' },
+    { name: 'limit', type: 'number', description: 'Max events (default 100, newest first)' },
+    { name: 'format', type: 'string', description: 'Output format', enum: ['ndjson'] },
+  ],
+  operations: {},
+  customOperations: {
+    list: {
+      access: 'open',
+      description: 'Query audit events, newest first. --format ndjson streams the stored lines for SIEM export.',
+      examples: [
+        'ncl audit list --outcome denied --since 7d',
+        'ncl audit list --correlation appr-1751970000000-x1y2z3',
+        'ncl audit list --action groups.config --format ndjson',
+      ],
+      handler: async (args) => listAuditEvents(args),
+      formatHuman: (data) => {
+        // NDJSON export prints the stored lines verbatim; for the table view
+        // this throws so dispatch falls back to the row objects, which every
+        // client already renders.
+        if (typeof data === 'string') return data;
+        throw new Error('render rows client-side');
+      },
+    },
+  },
+});

.claude/skills/add-clidash/REMOVE.md

@@ -0,0 +1,22 @@
+# Remove /add-clidash
+
+clidash is fully self-contained, so removal is a single directory delete. It
+made no edits to NanoClaw `src/`, added no dependency, and wired into nothing.
+
+```bash
+# Stop the service first if you set one up:
+systemctl --user disable --now clidash 2>/dev/null || true
+rm -f ~/.config/systemd/user/clidash.service
+
+# Remove the tool:
+rm -rf tools/clidash
+```
+
+If you added the config to `.gitignore` in step 2 of the install, remove that
+line too:
+
+```
+tools/clidash/clidash.config.json
+```
+
+Nothing else needs reverting.

.claude/skills/add-clidash/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: add-clidash
+description: Add clidash — a zero-dependency, read-only web dashboard that derives its tabs and tables at runtime from any CLI that lists resources as JSON. Ships pre-wired for NanoClaw's ncl CLI (agent groups, sessions, channels, users, roles), plus message-activity charts, a log tail, and a read-only file viewer for group skills/CLAUDE.md/profiles.
+---
+
+# /add-clidash — CLI-derived read-only dashboard
+
+clidash is a small, read-only web dashboard. You point it at any CLI that can
+list resources as JSON (NanoClaw's `ncl`, `docker`, `kubectl`, …) and it builds
+the dashboard at runtime: one tab per resource, a generic table over whatever
+columns the rows have. A new `ncl` resource becomes a new tab and a new column
+becomes a new table column with **zero code changes**.
+
+It ships pre-wired for NanoClaw's `ncl` CLI and adds three NanoClaw-aware
+panels driven entirely by config:
+
+- **Agents overview** — status cards joining groups + sessions + messaging
+  groups + wirings (green <15m / amber <2h / red older).
+- **Activity** — per-session inbound/outbound message totals and a daily series,
+  read directly from the session DBs (`ncl` has no messages resource).
+- **Logs** — last N lines of allowlisted host log files.
+- **Files** — a read-only viewer for group skills, `CLAUDE.md`, and profiles.
+
+## Why it's safe
+
+clidash is **read-only by construction**: the server can only `execFile` the
+argv templates in its config. `{resource}` is the sole substitution and is
+allowlist-validated against the discovered/static resource set before exec —
+never a shell, no free-form input reaches argv. There is no auth; **the network
+is the auth boundary** — it binds `127.0.0.1` by default. Only ever bind a
+private interface (e.g. a tailnet IP), never a public one.
+
+It's distinct from `/add-dashboard` (which pushes JSON snapshots to a separate
+`@nanoco/nanoclaw-dashboard` npm package): clidash has **zero dependencies**, no
+build step, no push pipeline, and no edits to NanoClaw source — it just reads
+`ncl` and the session DBs.
+
+## Steps
+
+### 1. Copy the tool into place
+
+clidash is fully self-contained — copy the whole directory in:
+
+`tools/` is not a standard NanoClaw directory and `cp -R` won't create it, so
+make it first:
+
+```bash
+mkdir -p tools
+cp -R .claude/skills/add-clidash/add/tools/clidash tools/clidash
+```
+
+That is the only file change this skill makes. Nothing in NanoClaw `src/` is
+touched, no dependency is added.
+
+### 2. Create the config
+
+The example config is pre-wired for NanoClaw with paths relative to the repo
+root, so it works as-is when you run clidash from `tools/clidash/`:
+
+```bash
+cd tools/clidash
+cp clidash.config.example.json clidash.config.json
+```
+
+`clidash.config.json` is your local config — add it to `.gitignore` if you
+don't want to commit install-specific paths:
+
+```bash
+echo 'tools/clidash/clidash.config.json' >> ../../.gitignore
+```
+
+The example assumes `ncl` is built at `bin/ncl`. If `bin/ncl` doesn't exist,
+build it first (`pnpm run build`) or point `clis.ncl.bin` at the right path.
+
+### 3. Test
+
+Tests use a stub CLI — no real `ncl` or `docker` needed:
+
+```bash
+npm test
+```
+
+All tests should pass (Node ≥ 22.5, `node:test`, zero dependencies).
+
+### 4. Run and verify
+
+```bash
+node server.js          # serves http://127.0.0.1:4690
+```
+
+In another shell, confirm it's live and that `ncl` discovery worked:
+
+```bash
+curl -s http://127.0.0.1:4690/api/clis | head -c 400      # CLIs + discovered resources
+curl -s http://127.0.0.1:4690/api/r/ncl/groups | head -c 400   # a real resource table
+```
+
+Then open `http://127.0.0.1:4690/` in a browser. You should see the Agents
+overview plus a tab per `ncl` resource.
+
+### 5. (Optional) Run as a service
+
+clidash binds `127.0.0.1` by default. To reach it from other devices, bind a
+private (e.g. tailnet) IP via the `BIND` env var or `bind` in config — never a
+public interface.
+
+```ini
+# ~/.config/systemd/user/clidash.service   (Linux)
+[Unit]
+Description=clidash read-only CLI dashboard
+
+[Service]
+WorkingDirectory=%h/nanoclaw/tools/clidash
+ExecStart=/usr/bin/node %h/nanoclaw/tools/clidash/server.js
+Environment=BIND=127.0.0.1
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user enable --now clidash
+```
+
+On macOS, wrap `node server.js` (with `WorkingDirectory` = `tools/clidash`) in a
+launchd plist the same way the main NanoClaw service is configured.
+
+## Configuration reference
+
+`clidash.config.json` keys (see `tools/clidash/README.md` and
+`clidash.config.example.json` for the full shape):
+
+| Key | Purpose |
+|-----|---------|
+| `port`, `bind`, `refreshSeconds` | server bind + UI auto-refresh cadence |
+| `clis.<name>.bin` / `cwd` / `env` | how to invoke the CLI (`bin` is relative to `cwd`) |
+| `clis.<name>.discover` or `resources` | runtime discovery (`ncl help`) vs a static resource list |
+| `clis.<name>.list` | argv template; `{resource}` is the only substitution |
+| `clis.<name>.output` | `json` or `jsonlines` (docker/kubectl style) |
+| `clis.<name>.unwrap` | dot-path into a response envelope (e.g. `data`) |
+| `clis.<name>.enrich`/`badges`/`summary` | table decorations (ID→name joins, status colors, summary cards) |
+| `activity` | `sessionsRoot` + `days` for the message-activity charts |
+| `logs` | `dir`, `tailLines`, and an allowlist of `files` to tail |
+| `docs` | file viewer: `root`, a `deny` glob list, and `collections` of glob patterns |
+
+Adding a second CLI is config-only — e.g. `docker` is included as a `jsonlines`
+example. View plugins (`views/<cli>-<view>.js`) are the only per-CLI code and
+are optional.
+
+## Troubleshooting
+
+- **`ENOENT` / config not found** — run from `tools/clidash/` and make sure you
+  copied `clidash.config.example.json` to `clidash.config.json` (step 2), or set
+  `CLIDASH_CONFIG=/abs/path.json`.
+- **No `ncl` resources / discovery empty** — `bin/ncl` isn't built or the path
+  is wrong. Build it (`pnpm run build`) or fix `clis.ncl.bin`.
+- **docker tab errors** — the docker daemon isn't running, or remove the
+  `docker` CLI from config if you don't need it.
+- **Can't reach it from another device** — it binds `127.0.0.1`; set
+  `BIND=<private-ip>` (tailnet), never a public interface.
+- **Empty Activity/Logs/Files** — check that `activity.sessionsRoot`,
+  `logs.dir`, and `docs.root` resolve to your NanoClaw root (relative to where
+  you launch `node server.js`).
+
+## Removal
+
+See [REMOVE.md](REMOVE.md).

.claude/skills/add-clidash/add/tools/clidash/README.md

@@ -0,0 +1,109 @@
+# clidash
+
+CLI-agnostic **read-only** web dashboard. Point it at any CLI that can list
+resources as JSON and it derives the dashboard at runtime: one tab per
+resource, a generic table over whatever columns the rows have. New resource →
+new tab; new column → new table column; **zero code changes**.
+
+It ships pre-wired for NanoClaw's `ncl` CLI (agent groups, sessions, messaging
+groups, wirings, users, roles, …) plus `docker`, but the same config shape
+works for any list-as-JSON CLI.
+
+- **Zero dependencies** — Node built-ins only (Node ≥ 22.5, for `node:sqlite`),
+  no build step,
+  vanilla-JS frontend.
+- **Read-only by construction** — the server can only `execFile` the configured
+  argv templates; `{resource}` is the sole substitution and is validated
+  against the discovered/static resource allowlist. Never a shell.
+- **Standalone** — no imports from NanoClaw source; the core is extractable to
+  its own repo. The NanoClaw-specific knowledge lives entirely in the config
+  and in the `views/ncl-overview.js` view plugin.
+
+## Run
+
+```bash
+cp clidash.config.example.json clidash.config.json   # then edit paths if needed
+node server.js                                        # uses ./clidash.config.json
+CLIDASH_CONFIG=/path/to.json node server.js
+PORT=4690 BIND=127.0.0.1 node server.js               # env overrides
+```
+
+Run it from `tools/clidash/`; the example config uses paths relative to the
+NanoClaw root two levels up, so it works out of the box once `ncl` is built.
+
+## Configure (`clidash.config.json`)
+
+```jsonc
+{
+  "port": 4690,
+  "bind": "127.0.0.1",          // never a public interface; a tailnet IP at most
+  "refreshSeconds": 60,
+  "clis": {
+    "ncl": {
+      "bin": "bin/ncl",                                        // relative to cwd below
+      "cwd": "../..",                                           // the NanoClaw root
+      "discover": { "args": ["help"], "parser": "ncl-help" },   // runtime resource discovery
+      "list": ["{resource}", "list", "--json"],                 // argv template
+      "output": "json",          // or "jsonlines" (docker/kubectl style)
+      "unwrap": "data"           // dot-path into a response envelope
+    },
+    "docker": {
+      "bin": "docker",
+      "resources": ["ps", "images"],          // static alternative to discover
+      "list": ["{resource}", "--format", "{{json .}}"],
+      "output": "jsonlines"
+    }
+  }
+}
+```
+
+`{resource}` may appear as a whole argv element or inside one — e.g. a remote
+CLI via ssh: `"list": ["-i", "key.pem", "user@host", "ncl {resource} list --json"]`.
+
+Per-CLI `env` (merged over the server's env) and `cwd` are supported. See
+`clidash.config.example.json` for the full NanoClaw config, including the
+`enrich`/`badges`/`summary` table decorations and the `activity`/`logs`/`docs`
+sections.
+
+## API
+
+| Route | Returns |
+|---|---|
+| `GET /api/clis` | configured CLIs + discovered/static resources (discovery cached 60s) |
+| `GET /api/r/<cli>/<resource>` | `{ok, rows, fetchedAt}` — coalesced, 10s exec timeout |
+| `GET /api/view/<cli>/<view>` | curated view plugin from `views/<cli>-<view>.js` |
+
+View plugins are the only per-CLI *code*, and optional: a default-exported
+async function receiving `{ fetch }` (bound to that CLI) returning JSON.
+`views/ncl-overview.js` joins groups + sessions + messaging-groups + wirings
+into per-agent status cards (green <15m / amber <2h / red older).
+
+## Test
+
+```bash
+npm test            # unit + integration (node:test, stub CLI — no real CLI needed)
+./test/smoke.sh     # against a running instance
+```
+
+## Deploy as a service
+
+clidash binds `127.0.0.1` by default. To reach it from other devices, bind a
+private (e.g. tailnet) IP — **never a public interface**; the network is the
+auth boundary. Example systemd user service:
+
+```ini
+# ~/.config/systemd/user/clidash.service
+[Unit]
+Description=clidash read-only CLI dashboard
+
+[Service]
+WorkingDirectory=%h/nanoclaw/tools/clidash
+ExecStart=/usr/bin/node %h/nanoclaw/tools/clidash/server.js
+Environment=BIND=127.0.0.1
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+Then `systemctl --user enable --now clidash`.

.claude/skills/add-clidash/add/tools/clidash/activity.js

@@ -0,0 +1,80 @@
+// Message-activity reader for clidash.
+//
+// ncl has no `messages` resource — message data lives in the per-session SQLite
+// DBs (`data/v2-sessions/<group>/<session>/{inbound,outbound}.db`). We read them
+// read-only with Node's built-in `node:sqlite` (no new dependency) and aggregate
+// per-session in/out totals + a daily time-series for charting.
+
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+// Timestamps come in two shapes across tables: SQLite "YYYY-MM-DD HH:MM:SS" (UTC)
+// and already-ISO "YYYY-MM-DDTHH:MM:SS.sssZ". Normalize to a comparable ISO form
+// so date-bucketing and max("last") work regardless of which a row used.
+function normTs(ts) {
+  if (typeof ts !== 'string' || ts.length < 10) return null;
+  if (ts.includes('T')) return ts; // already ISO
+  return `${ts.replace(' ', 'T')}Z`;
+}
+
+function readTable(dbPath, table) {
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    const rows = db.prepare(`SELECT timestamp FROM ${table}`).all();
+    const byDay = new Map();
+    let last = null;
+    for (const r of rows) {
+      const ts = normTs(r.timestamp);
+      if (!ts) continue;
+      const day = ts.slice(0, 10); // ISO date prefix
+      byDay.set(day, (byDay.get(day) ?? 0) + 1);
+      if (last === null || ts > last) last = ts;
+    }
+    return { total: rows.length, byDay, last };
+  } catch {
+    return { total: 0, byDay: new Map(), last: null }; // missing/locked/corrupt → skip
+  } finally {
+    try { db?.close(); } catch { /* already closed */ }
+  }
+}
+
+function listDirs(path) {
+  try {
+    return readdirSync(path, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Aggregate message activity across all session DBs under `sessionsRoot`.
+ * @returns {{ sessions: Array, series: Array<{date,in,out}> }}
+ *   sessions — per session: { agent_group_id, session_id, in, out, lastActivity }
+ *   series   — one bucket per day for the last `days` days (UTC, newest last)
+ */
+export function collectActivity(sessionsRoot, days, now) {
+  const dates = [];
+  for (let i = days - 1; i >= 0; i--) {
+    dates.push(new Date(now.getTime() - i * 86_400_000).toISOString().slice(0, 10));
+  }
+  const series = new Map(dates.map((d) => [d, { date: d, in: 0, out: 0 }]));
+  const sessions = [];
+
+  for (const group of listDirs(sessionsRoot)) {
+    for (const session of listDirs(join(sessionsRoot, group))) {
+      const base = join(sessionsRoot, group, session);
+      // a real session dir has at least one of the two message DBs; skip shared
+      // scaffolding dirs like `.claude-shared` that don't.
+      if (!existsSync(join(base, 'inbound.db')) && !existsSync(join(base, 'outbound.db'))) continue;
+      const inb = readTable(join(base, 'inbound.db'), 'messages_in');
+      const out = readTable(join(base, 'outbound.db'), 'messages_out');
+      const lastActivity = [inb.last, out.last].filter(Boolean).sort().at(-1) ?? null;
+      sessions.push({ agent_group_id: group, session_id: session, in: inb.total, out: out.total, lastActivity });
+      for (const [day, n] of inb.byDay) series.get(day)?.in !== undefined && (series.get(day).in += n);
+      for (const [day, n] of out.byDay) series.get(day)?.out !== undefined && (series.get(day).out += n);
+    }
+  }
+  return { sessions, series: dates.map((d) => series.get(d)) };
+}

.claude/skills/add-clidash/add/tools/clidash/clidash.config.example.json

@@ -0,0 +1,106 @@
+{
+  "port": 4690,
+  "bind": "127.0.0.1",
+  "refreshSeconds": 60,
+  "clis": {
+    "ncl": {
+      "bin": "bin/ncl",
+      "cwd": "../..",
+      "discover": { "args": ["help"], "parser": "ncl-help" },
+      "list": ["{resource}", "list", "--json"],
+      "output": "json",
+      "unwrap": "data",
+      "commands": {
+        "get": ["{resource}", "get", "--id", "{id}", "--json"],
+        "config-get": ["groups", "config", "get", "--id", "{id}", "--json"]
+      },
+      "help": ["{resource}", "help"],
+      "enrich": {
+        "sessions": {
+          "agent_group_id": { "ref": "groups", "label": "name" },
+          "messaging_group_id": { "ref": "messaging-groups", "label": "name" }
+        },
+        "wirings": {
+          "agent_group_id": { "ref": "groups", "label": "name" },
+          "messaging_group_id": { "ref": "messaging-groups", "label": "name" }
+        },
+        "roles": {
+          "agent_group_id": { "ref": "groups", "label": "name" },
+          "user_id": { "ref": "users", "label": "display_name" },
+          "granted_by": { "ref": "users", "label": "display_name" }
+        },
+        "members": {
+          "agent_group_id": { "ref": "groups", "label": "name" },
+          "user_id": { "ref": "users", "label": "display_name" }
+        },
+        "destinations": {
+          "agent_group_id": { "ref": "groups", "label": "name" }
+        },
+        "user-dms": {
+          "user_id": { "ref": "users", "label": "display_name" },
+          "messaging_group_id": { "ref": "messaging-groups", "label": "name" }
+        }
+      },
+      "badges": {
+        "container_status": { "running": "green", "idle": "green", "starting": "amber", "stopped": "gray", "error": "red" },
+        "status": { "active": "green", "stopped": "gray", "error": "red", "pending": "amber" }
+      },
+      "summary": {
+        "sessions": "container_status",
+        "messaging-groups": "channel_type",
+        "roles": "role",
+        "users": "kind",
+        "destinations": "target_type",
+        "dropped-messages": "reason"
+      }
+    },
+    "docker": {
+      "bin": "docker",
+      "resources": ["ps", "images"],
+      "list": ["{resource}", "--format", "{{json .}}"],
+      "output": "jsonlines"
+    }
+  },
+  "activity": {
+    "sessionsRoot": "../../data/v2-sessions",
+    "days": 14
+  },
+  "logs": {
+    "dir": "../../logs",
+    "tailLines": 500,
+    "files": [
+      { "name": "nanoclaw.log", "label": "host log" },
+      { "name": "nanoclaw.error.log", "label": "errors" }
+    ]
+  },
+  "docs": {
+    "root": "../..",
+    "deny": ["node_modules", ".env", "*token*", "*secret*", "*.pem", "*.key", "*.lock", "pnpm-lock.yaml"],
+    "collections": [
+      {
+        "name": "skills",
+        "label": "Skills",
+        "lang": "markdown",
+        "patterns": ["groups/*/skills/*/SKILL.md", "container/skills/*/SKILL.md"]
+      },
+      {
+        "name": "claude-md",
+        "label": "CLAUDE.md",
+        "lang": "markdown",
+        "patterns": ["groups/*/CLAUDE.md", "groups/*/CLAUDE.local.md"]
+      },
+      {
+        "name": "profiles",
+        "label": "Profiles",
+        "lang": "json",
+        "patterns": ["groups/*/profile.json"]
+      },
+      {
+        "name": "conversations",
+        "label": "Conversations",
+        "lang": "markdown",
+        "patterns": ["groups/*/conversations/*.md"]
+      }
+    ]
+  }
+}

.claude/skills/add-clidash/add/tools/clidash/docs.js

@@ -0,0 +1,102 @@
+// Read-only file viewer for clidash.
+//
+// Surfaces on-disk documents (skills, CLAUDE.md, profile.json, conversations)
+// that are NOT ncl resources. Same security posture as the rest of clidash:
+// only files matching a configured collection's glob patterns are listable or
+// readable; a deny-list blocks secrets; path traversal is impossible because a
+// requested path must be a member of the freshly-globbed allow-set.
+
+import { readdirSync, realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+
+// Convert one glob segment to an anchored regex. `*` matches any run of
+// non-slash chars (so it works both as a whole segment and inside a filename,
+// e.g. `CLAUDE*.md`). All other regex metacharacters are escaped.
+function segToRegExp(seg) {
+  const esc = seg.replace(/[.+^${}()|[\]\\?]/g, '\\$&').replace(/\*/g, '[^/]*');
+  return new RegExp('^' + esc + '$');
+}
+
+// A path is denied if any of its segments matches any deny glob.
+function isDenied(relPath, deny) {
+  const segs = relPath.split('/');
+  return deny.some((d) => {
+    const re = segToRegExp(d);
+    return segs.some((s) => re.test(s));
+  });
+}
+
+// Directed walk: descend only entries matching each successive pattern segment.
+function walk(root, rel, segs, depth, out, deny) {
+  if (depth >= segs.length) return;
+  let entries;
+  try {
+    entries = readdirSync(join(root, rel), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const re = segToRegExp(segs[depth]);
+  const last = depth === segs.length - 1;
+  for (const e of entries) {
+    if (e.name === '.' || e.name === '..') continue;
+    if (!re.test(e.name)) continue;
+    const childRel = rel ? `${rel}/${e.name}` : e.name;
+    if (isDenied(childRel, deny)) continue;
+    if (last) {
+      if (e.isFile()) out.add(childRel);
+    } else if (e.isDirectory()) {
+      walk(root, childRel, segs, depth + 1, out, deny);
+    }
+  }
+}
+
+/**
+ * Relative paths under `root` matching any of `patterns`, minus `deny` matches.
+ * Sorted, de-duplicated. Patterns use `*` per the segment rules above; no `**`.
+ */
+export function globFiles(root, patterns, deny = []) {
+  const out = new Set();
+  for (const pattern of patterns) {
+    walk(root, '', pattern.split('/'), 0, out, deny);
+  }
+  return [...out].sort();
+}
+
+/**
+ * Human-friendly grouping/label for a relative path.
+ * `groups/<g>/...` → group `<g>`; `container/...` → group `shared`.
+ */
+const CONTAINER_SEGS = new Set(['skills', 'conversations']); // redundant grouping dirs
+export function describeFile(relPath) {
+  const parts = relPath.split('/');
+  if (parts[0] === 'groups' && parts.length > 2) {
+    const rest = parts.slice(2).filter((s) => !CONTAINER_SEGS.has(s)).join('/');
+    return { group: parts[1], label: `${parts[1]} / ${rest}` };
+  }
+  if (parts[0] === 'container') {
+    const rest = parts.slice(2).filter((s) => !CONTAINER_SEGS.has(s)).join('/');
+    return { group: 'shared', label: `shared / ${rest}` };
+  }
+  return { group: '', label: relPath };
+}
+
+/**
+ * Validate a requested doc path against a collection and return its absolute
+ * path, or throw. A path is allowed only if it is a member of the collection's
+ * freshly-globbed allow-set — this single check enforces the patterns, the
+ * deny-list, and traversal safety at once.
+ */
+export function resolveDoc(root, collection, relPath, deny = []) {
+  const allowed = new Set(globFiles(root, collection.patterns, deny));
+  if (!allowed.has(relPath)) {
+    throw new Error(`Path not allowed: ${relPath}`);
+  }
+  // Defence in depth: the resolved real path must still live under root.
+  const abs = resolve(root, relPath);
+  const rootReal = realpathSync(root);
+  const absReal = realpathSync(abs);
+  if (absReal !== rootReal && !absReal.startsWith(rootReal + sep)) {
+    throw new Error(`Path not allowed: ${relPath}`);
+  }
+  return abs;
+}

.claude/skills/add-clidash/add/tools/clidash/logs.js

@@ -0,0 +1,18 @@
+// Log tailing for clidash — reads the last N lines of an allowlisted log file
+// and strips ANSI color codes (the host logger writes colored output).
+
+import { readFile } from 'node:fs/promises';
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/**
+ * Last `maxLines` lines of a log file, ANSI-stripped.
+ * @returns {{ lines: string[], text: string }}
+ */
+export async function tailFile(path, maxLines) {
+  const raw = (await readFile(path, 'utf8')).replace(ANSI_RE, '');
+  const all = raw.split('\n');
+  if (all.length && all.at(-1) === '') all.pop(); // drop trailing newline's empty field
+  const lines = all.slice(-maxLines);
+  return { lines, text: lines.join('\n') };
+}

.claude/skills/add-clidash/add/tools/clidash/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "clidash",
+  "version": "0.1.0",
+  "description": "CLI-agnostic read-only web dashboard — derives tabs and tables from any CLI that lists resources as JSON",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start": "node server.js",
+    "test": "node --test 'test/*.test.js'"
+  },
+  "engines": {
+    "node": ">=22.5"
+  }
+}

.claude/skills/add-clidash/add/tools/clidash/parsers.js

@@ -0,0 +1,101 @@
+// Pluggable parsers for clidash.
+//
+// discoveryParsers — turn a CLI's "help"-style output into a resource list.
+// parseOutput / unwrapPath — turn a CLI's list output into rows.
+// All per-CLI knowledge beyond these small functions lives in clidash.config.json.
+
+/**
+ * Discovery parsers, keyed by the `discover.parser` name in config.
+ * Each receives the raw discovery output and returns
+ * [{ name, description, verbs }] for resources that support `list`.
+ * They must throw loudly on unrecognized formats — silent empty results
+ * would render as silently-stale tabs.
+ */
+export const discoveryParsers = {
+  /**
+   * Parses ncl's two-column help format:
+   *
+   *   Resources:
+   *     sessions             Session — the runtime unit. ...
+   *                          verbs: list, get
+   *   Commands:
+   *     help                 ...
+   */
+  'ncl-help'(text) {
+    const lines = String(text).split('\n');
+    const start = lines.findIndex((l) => l.trim() === 'Resources:');
+    if (start === -1) {
+      throw new Error('ncl-help parser: no "Resources:" section in output — format may have changed');
+    }
+    const resources = [];
+    let current = null;
+    for (let i = start + 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.trim() === '') continue;
+      if (/^\S/.test(line)) break; // next top-level section, e.g. "Commands:"
+      const verbsMatch = line.match(/^\s+verbs:\s*(.+)$/);
+      if (verbsMatch && current) {
+        current.verbs = verbsMatch[1].split(',').map((v) => v.trim()).filter(Boolean);
+        continue;
+      }
+      const resMatch = line.match(/^  (\S+)\s{2,}(\S.*)$/);
+      if (resMatch) {
+        current = { name: resMatch[1], description: resMatch[2].trim(), verbs: [] };
+        resources.push(current);
+      }
+    }
+    return resources.filter((r) => r.verbs.includes('list'));
+  },
+};
+
+/**
+ * Parses a CLI's list output per the config's `output` field.
+ * - 'json'      — one JSON document.
+ * - 'jsonlines' — one JSON object per line (docker/kubectl style).
+ * Thrown errors carry the raw output on `err.raw` so the UI can show it.
+ */
+export function parseOutput(text, format) {
+  if (format === 'json') {
+    try {
+      return JSON.parse(text);
+    } catch (e) {
+      const err = new Error(`Invalid JSON output: ${e.message}`);
+      err.raw = text;
+      throw err;
+    }
+  }
+  if (format === 'jsonlines') {
+    const rows = [];
+    const lines = String(text).split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      try {
+        rows.push(JSON.parse(line));
+      } catch (e) {
+        const err = new Error(`Invalid JSON on line ${i + 1}: ${e.message}`);
+        err.raw = text;
+        throw err;
+      }
+    }
+    return rows;
+  }
+  throw new Error(`Unknown output format: ${format}`);
+}
+
+/**
+ * Follows a dot-path into a response envelope (e.g. 'data' for ncl's
+ * {id, ok, data} frame). No path → value passes through unchanged.
+ * Missing path throws — a changed envelope must fail loudly.
+ */
+export function unwrapPath(value, path) {
+  if (!path) return value;
+  let cur = value;
+  for (const key of path.split('.')) {
+    if (cur === null || typeof cur !== 'object' || !(key in cur)) {
+      throw new Error(`Unwrap path "${path}" not found in CLI output (missing "${key}")`);
+    }
+    cur = cur[key];
+  }
+  return cur;
+}

.claude/skills/add-clidash/add/tools/clidash/public/app.js

@@ -0,0 +1,715 @@
+// clidash frontend — vanilla JS, no build step.
+//
+// Layout: a left sidebar with top-level items (Overview, Activity) and grouped
+// sections (one per CLI — ncl, docker — and a Files section for on-disk docs).
+// Each page shows the exact command that produced it. Tables auto-derive from
+// `ncl <resource> list --json`; rows drill into their `get` detail.
+//
+// Refresh UX: on first load every resource of every CLI is prefetched so nav is
+// instant. 60s auto-refresh + a manual button. Background refreshes diff-and-
+// inject (the data DOM rebuilds only when the data signature changes).
+
+import { mdToHtml } from './md.js';
+
+const $ = (id) => document.getElementById(id);
+
+const state = {
+  clis: [],
+  docCollections: [],
+  activeView: 'overview',   // 'overview' | 'activity' | 'r:<cli>:<resource>' | 'doc:<collection>'
+  paused: false,
+  refreshSeconds: 60,
+  lastUpdated: null,
+  refreshing: false,
+  snapshots: new Map(),     // "cli/resource" -> { rows, fetchedAt, command }
+  errors: new Map(),
+  activity: null,           // { sessions, series }
+  activityConfigured: false,
+  activityCommand: null,
+  logs: [],                 // [{ name, label }]
+  logCache: new Map(),      // name -> { text, command }
+  activeDocPath: null,
+  openDocGroups: new Set(), // which doc groups (e.g. agents) are expanded
+  docCache: new Map(),
+  configCache: new Map(),   // groupId -> container config (for the overview page)
+  helpCache: new Map(),     // "cli/resource" -> help text | null (prefetched each cycle)
+  detail: null,
+  sidebarOpen: false,
+  renderedSig: null,
+};
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+function svg(tag, attrs = {}, children = []) {
+  const node = document.createElementNS(SVG_NS, tag);
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
+  for (const c of [].concat(children)) if (c != null) node.append(c);
+  return node;
+}
+
+// Lucide-style inline icons (static trusted markup) — crisp, themeable via currentColor.
+const ICONS = {
+  overview: '<rect x="3" y="3" width="7" height="9" rx="1"/><rect x="14" y="3" width="7" height="5" rx="1"/><rect x="14" y="12" width="7" height="9" rx="1"/><rect x="3" y="16" width="7" height="5" rx="1"/>',
+  activity: '<path d="M3 3v18h18"/><path d="M18 17V9"/><path d="M13 17V5"/><path d="M8 17v-3"/>',
+  terminal: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="m6 9 3 3-3 3"/><path d="M13 15h4"/>',
+  box: '<path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/>',
+  folder: '<path d="M4 20h16a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13c0 1.1.9 2 2 2Z"/>',
+  logs: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v5h5"/><path d="M8 13h8"/><path d="M8 17h5"/>',
+};
+function icon(name) {
+  const s = document.createElementNS(SVG_NS, 'svg');
+  s.setAttribute('viewBox', '0 0 24 24');
+  s.setAttribute('fill', 'none');
+  s.setAttribute('stroke', 'currentColor');
+  s.setAttribute('stroke-width', '1.8');
+  s.setAttribute('stroke-linecap', 'round');
+  s.setAttribute('stroke-linejoin', 'round');
+  s.innerHTML = ICONS[name] ?? '';
+  return s;
+}
+
+// ---------------------------------------------------------------- helpers
+
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+
+function relTime(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms)) return iso;
+  const s = Math.round(ms / 1000);
+  if (s < 0) return new Date(iso).toLocaleString();
+  if (s < 60) return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h ago`;
+  return `${Math.round(h / 24)}d ago`;
+}
+
+function coarseAgo(date) {
+  const s = (Date.now() - date.getTime()) / 1000;
+  if (s < 60) return 'less than a minute ago';
+  const m = Math.floor(s / 60);
+  if (m < 60) return m === 1 ? '1 minute ago' : `${m} minutes ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return h === 1 ? '1 hour ago' : `${h} hours ago`;
+  const d = Math.floor(h / 24);
+  return d === 1 ? '1 day ago' : `${d} days ago`;
+}
+
+function staleness(lastActive) {
+  if (!lastActive) return 'gray';
+  const min = (Date.now() - new Date(lastActive).getTime()) / 60000;
+  if (Number.isNaN(min)) return 'gray';
+  return min < 15 ? 'green' : min < 120 ? 'amber' : 'red';
+}
+
+function el(tag, attrs = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (k === 'class') node.className = v;
+    else if (k.startsWith('on')) node.addEventListener(k.slice(2), v);
+    else node.setAttribute(k, v);
+  }
+  for (const child of [].concat(children)) {
+    if (child == null) continue;
+    node.append(child instanceof Node ? child : document.createTextNode(String(child)));
+  }
+  return node;
+}
+
+function fmtValue(value) {
+  if (value === null || value === undefined) return { text: 'null', cls: 'null' };
+  if (typeof value === 'string' && ISO_RE.test(value)) return { iso: value };
+  return { text: typeof value === 'object' ? JSON.stringify(value) : String(value) };
+}
+
+function cellFor(value) {
+  const f = fmtValue(value);
+  if (f.cls === 'null') return el('td', { class: 'null' }, 'null');
+  if (f.iso) {
+    return el('td', {}, el('span', { class: 'reltime', title: f.iso }, [
+      relTime(f.iso), el('span', { class: 'abs' }, f.iso.slice(0, 16).replace('T', ' ')),
+    ]));
+  }
+  if (f.text.length > 42) {
+    const span = el('span', { class: 'trunc', title: f.text }, f.text.slice(0, 39) + '…');
+    span.addEventListener('click', (e) => { e.stopPropagation(); span.textContent = f.text; span.classList.remove('trunc'); });
+    return el('td', {}, span);
+  }
+  return el('td', {}, f.text);
+}
+
+function kvRows(obj) {
+  return Object.entries(obj ?? {}).map(([k, v]) => {
+    let valEl;
+    if (v && typeof v === 'object') valEl = el('pre', { class: 'kv-json' }, JSON.stringify(v, null, 2));
+    else if (typeof v === 'string' && ISO_RE.test(v)) valEl = el('span', { class: 'reltime', title: v }, `${relTime(v)}  (${v.slice(0, 16).replace('T', ' ')})`);
+    else if (v === null || v === undefined) valEl = el('span', { class: 'null' }, 'null');
+    else valEl = el('span', {}, String(v));
+    return el('div', { class: 'kv-row' }, [el('span', { class: 'kv-key' }, k), valEl]);
+  });
+}
+
+function resolveRef(cliName, ref, id) {
+  const snap = state.snapshots.get(`${cliName}/${ref.ref}`);
+  const row = snap?.rows?.find((r) => String(r.id) === String(id));
+  return row ? (row[ref.label] ?? null) : null;
+}
+
+function badgeChip(value, colorMap) {
+  const color = colorMap[String(value).toLowerCase()] ?? 'gray';
+  return el('span', { class: `badge-status ${color}` }, [el('span', { class: `dot ${color}` }), String(value)]);
+}
+
+function buildCell(value, column, ctx) {
+  if (ctx.badges?.[column] && value != null && typeof value !== 'object') {
+    return el('td', {}, badgeChip(value, ctx.badges[column]));
+  }
+  if (ctx.enrich?.[column] && value != null) {
+    const name = resolveRef(ctx.cliName, ctx.enrich[column], value);
+    if (name != null) {
+      return el('td', { class: 'enriched', title: String(value) }, [
+        el('span', {}, String(name)), el('span', { class: 'raw-id' }, String(value)),
+      ]);
+    }
+  }
+  return cellFor(value);
+}
+
+function summaryBar(resource, rows, col, cli) {
+  let label = resource.replace(/-/g, ' ');
+  if (rows.length === 1 && label.endsWith('s')) label = label.slice(0, -1);
+  const bits = [el('span', { class: 'sum-count' }, `${rows.length} ${label}`)];
+  if (col && rows.some((r) => col in r)) {
+    const counts = new Map();
+    for (const r of rows) { const v = r[col] ?? '—'; counts.set(v, (counts.get(v) ?? 0) + 1); }
+    const colorMap = cli.badges?.[col];
+    for (const [v, n] of [...counts.entries()].sort((a, b) => b[1] - a[1])) {
+      bits.push(el('span', { class: 'sum-sep' }, '·'));
+      const c = colorMap?.[String(v).toLowerCase()] ?? null;
+      bits.push(c
+        ? el('span', { class: `badge-status ${c}` }, [el('span', { class: `dot ${c}` }), `${v} ×${n}`])
+        : el('span', { class: 'sum-chip' }, `${v} ×${n}`));
+    }
+  }
+  return el('div', { class: 'summary-bar' }, bits);
+}
+
+// ---------------------------------------------------------------- views
+
+const nclCli = () => state.clis.find((c) => c.name === 'ncl') ?? state.clis[0];
+function currentView() {
+  const v = state.activeView;
+  if (v === 'overview' || v === 'activity') return { type: v };
+  const m = v.match(/^r:([^:]+):(.+)$/);
+  if (m) return { type: 'resource', cli: m[1], resource: m[2] };
+  if (v.startsWith('doc:')) return { type: 'doc', collection: v.slice(4) };
+  if (v.startsWith('log:')) return { type: 'log', name: v.slice(4) };
+  return { type: 'overview' };
+}
+const activeCollection = () => {
+  const v = currentView();
+  return v.type === 'doc' ? state.docCollections.find((c) => c.name === v.collection) : null;
+};
+
+// ---------------------------------------------------------------- fetching
+
+async function fetchJson(url) {
+  const res = await fetch(url);
+  return res.json().catch(() => ({ ok: false, error: `Bad response from ${url}` }));
+}
+
+async function refresh(force = false) {
+  state.refreshing = true;
+  if (force) renderControls();
+
+  const [cliList, docList, logList] = await Promise.all([
+    fetchJson('/api/clis').catch(() => null),
+    fetchJson('/api/docs').catch(() => null),
+    fetchJson('/api/logs').catch(() => null),
+  ]);
+  if (cliList?.clis) {
+    state.clis = cliList.clis;
+    state.refreshSeconds = cliList.clis[0]?.refreshSeconds ?? state.refreshSeconds;
+  }
+  if (docList?.collections) state.docCollections = docList.collections;
+  if (logList?.files) state.logs = logList.files;
+
+  render(); // paint sidebar + active view's loading state immediately
+
+  const jobs = [];
+  jobs.push(fetchJson('/api/activity').then((body) => {
+    if (body.ok && body.configured) {
+      state.activity = { sessions: body.sessions, series: body.series };
+      state.activityConfigured = true; state.activityCommand = body.command ?? null;
+    } else state.activityConfigured = false;
+    render();
+  }));
+  for (const lg of state.logs) {
+    jobs.push(fetchJson(`/api/log/${encodeURIComponent(lg.name)}`).then((body) => {
+      if (body.ok) state.logCache.set(lg.name, { text: body.text, command: body.command });
+      render();
+    }));
+  }
+  for (const c of state.clis) {
+    for (const r of c.resources ?? []) {
+      const key = `${c.name}/${r.name}`;
+      jobs.push(fetchJson(`/api/r/${c.name}/${encodeURIComponent(r.name)}`).then((body) => {
+        if (body.ok) { state.snapshots.set(key, { rows: body.rows, fetchedAt: body.fetchedAt, command: body.command }); state.errors.set(key, null); }
+        else state.errors.set(key, body.raw ? `${body.error}\n\n${body.raw}` : body.error);
+        render();
+      }));
+      if (c.help) {
+        jobs.push(fetchJson(`/api/help/${c.name}/${encodeURIComponent(r.name)}`).then((body) => {
+          state.helpCache.set(key, body.ok ? body.text : null);
+          render();
+        }));
+      }
+    }
+  }
+  await Promise.all(jobs);
+
+  // per-group container config (for the Overview page) — small, refetched each cycle
+  const groups = state.snapshots.get('ncl/groups')?.rows ?? [];
+  await Promise.all(groups.map(async (g) => {
+    const c = await fetchJson(`/api/cmd/ncl/config-get?id=${encodeURIComponent(g.id)}`);
+    if (c.ok) state.configCache.set(g.id, c.data);
+  }));
+
+  state.lastUpdated = new Date();
+  state.refreshing = false;
+  render();
+}
+
+async function openDoc(collectionName, path) {
+  state.activeDocPath = path;
+  const key = `${collectionName}\0${path}`;
+  if (!state.docCache.has(key)) {
+    const body = await fetchJson(`/api/doc?c=${encodeURIComponent(collectionName)}&p=${encodeURIComponent(path)}`);
+    state.docCache.set(key, body.ok ? { lang: body.lang, content: body.content } : { lang: 'error', content: body.error || 'Failed to load' });
+  }
+  state.renderedSig = null;
+  render();
+}
+
+async function openDetail(cliName, resource, id) {
+  state.detail = { cli: cliName, resource, id, loading: true };
+  state.renderedSig = null;
+  render();
+  const rec = await fetchJson(`/api/cmd/${cliName}/get?resource=${encodeURIComponent(resource)}&id=${encodeURIComponent(id)}`);
+  let config = null;
+  if (resource === 'groups') {
+    const cg = await fetchJson(`/api/cmd/${cliName}/config-get?id=${encodeURIComponent(id)}`);
+    if (cg.ok) config = cg.data;
+  }
+  if (!state.detail || state.detail.id !== id) return;
+  state.detail = { cli: cliName, resource, id, record: rec.ok ? rec.data : null, error: rec.ok ? null : rec.error, config };
+  state.renderedSig = null;
+  render();
+}
+
+function closeDetail() { state.detail = null; state.renderedSig = null; render(); }
+
+// Help panel: the description (first paragraph) is always visible; the verbs +
+// fields (everything after the first blank line) sit behind a collapse.
+function helpPanel(text) {
+  if (text === null) return null; // explicitly no help
+  if (text === undefined) return el('div', { class: 'help-panel' }, el('div', { class: 'help-head dim' }, 'loading help…'));
+  const idx = text.indexOf('\n\n');
+  const head = (idx >= 0 ? text.slice(0, idx) : text).trim();
+  const body = idx >= 0 ? text.slice(idx + 2).trim() : '';
+  return el('div', { class: 'help-panel' }, [
+    el('div', { class: 'help-head' }, head),
+    body ? el('details', { class: 'help-more' }, [
+      el('summary', {}, 'verbs & fields'),
+      el('pre', { class: 'help-text' }, body),
+    ]) : null,
+  ]);
+}
+
+function go(view) {
+  state.activeView = view;
+  state.detail = null;
+  state.sidebarOpen = false;
+  state.renderedSig = null;
+  const v = currentView();
+  if (v.type === 'doc') {
+    const coll = state.docCollections.find((c) => c.name === v.collection);
+    const first = coll && (coll.name === 'conversations' ? coll.files.at(-1) : coll.files[0]); // newest conversation
+    state.activeDocPath = state.activeDocPath && coll?.files.some((f) => f.path === state.activeDocPath)
+      ? state.activeDocPath : (first?.path ?? null);
+    // expand only the group holding the active doc; the user picks the rest
+    const activeFile = coll?.files.find((f) => f.path === state.activeDocPath);
+    state.openDocGroups = new Set(activeFile ? [activeFile.group] : []);
+    render();
+    if (state.activeDocPath) openDoc(coll.name, state.activeDocPath);
+    return;
+  }
+  render();
+}
+
+// ---------------------------------------------------------------- rendering
+
+function dataSignature() {
+  const v = currentView();
+  const key = v.type === 'resource' ? `${v.cli}/${v.resource}` : null;
+  const coll = activeCollection();
+  return JSON.stringify({
+    view: state.activeView, clis: state.clis.map((c) => `${c.name}:${(c.resources || []).length}`),
+    activityConfigured: state.activityConfigured,
+    rows: key ? state.snapshots.get(key)?.rows ?? null : null,
+    rowsError: key ? state.errors.get(key) ?? null : null,
+    command: key ? state.snapshots.get(key)?.command ?? null : null,
+    help: key ? state.helpCache.get(key) ?? null : null,
+    overview: v.type === 'overview' ? {
+      groups: state.snapshots.get('ncl/groups')?.rows ?? null,
+      sessions: state.snapshots.get('ncl/sessions')?.rows ?? null,
+      configs: [...state.configCache.entries()],
+      activity: state.activity?.sessions ?? null,
+    } : null,
+    activity: v.type === 'activity' ? state.activity : null,
+    log: v.type === 'log' ? state.logCache.get(v.name)?.text ?? null : null,
+    docFiles: coll ? coll.files.map((f) => f.path) : null,
+    docPath: state.activeDocPath,
+    docGroupsOpen: coll ? [...state.openDocGroups] : null,
+    docContent: coll ? state.docCache.get(`${coll.name}\0${state.activeDocPath}`)?.content ?? null : null,
+    detail: state.detail, paused: state.paused, sidebarOpen: state.sidebarOpen,
+  });
+}
+
+function renderControls() {
+  $('updated').textContent = state.lastUpdated
+    ? `updated ${coarseAgo(state.lastUpdated)}${state.paused ? ' · paused' : ''}` : '';
+  $('refresh').classList.toggle('spinning', state.refreshing);
+}
+
+function render() {
+  renderControls();
+  const sig = dataSignature();
+  if (sig === state.renderedSig) return;
+  state.renderedSig = sig;
+
+  $('sidebar').classList.toggle('open', state.sidebarOpen);
+  $('scrim').hidden = !state.sidebarOpen;
+
+  renderNav();
+
+  const v = currentView();
+  const banner = $('banner');
+  const tabError = v.type === 'resource' ? state.errors.get(`${v.cli}/${v.resource}`) : null;
+  const cli = v.type === 'resource' ? state.clis.find((c) => c.name === v.cli) : null;
+  const bannerMsg = cli?.error ? `Discovery failed for ${v.cli}: ${cli.error}`
+    : (tabError ? `CLI unreachable — showing last good snapshot. ${tabError.split('\n')[0]}` : null);
+  banner.hidden = !bannerMsg;
+  banner.textContent = bannerMsg ?? '';
+
+  renderCmdline(v);
+  if (v.type === 'overview') renderOverviewPage();
+  else if (v.type === 'activity') renderActivity();
+  else if (v.type === 'doc') renderDocs();
+  else if (v.type === 'log') renderLogPage(v.name);
+  else renderTable(v.cli, v.resource);
+  renderDetail();
+}
+
+function navItem(label, view, cls = '', iconName = null) {
+  return el('button', {
+    class: `nav-item ${cls}` + (state.activeView === view ? ' active' : ''),
+    onclick: () => go(view),
+  }, [iconName ? icon(iconName) : null, el('span', {}, label)]);
+}
+
+function renderNav() {
+  const nav = $('nav');
+  const items = [navItem('Overview', 'overview', '', 'overview')];
+  if (state.activityConfigured) items.push(navItem('Activity', 'activity', '', 'activity'));
+
+  for (const cli of state.clis) {
+    items.push(el('div', { class: 'nav-section' }, [icon(cli.name === 'docker' ? 'box' : 'terminal'), el('span', {}, cli.name)]));
+    for (const r of cli.resources ?? []) {
+      items.push(navItem(r.name, `r:${cli.name}:${r.name}`, 'nav-sub'));
+    }
+  }
+  if (state.docCollections.length) {
+    items.push(el('div', { class: 'nav-section' }, [icon('folder'), el('span', {}, 'Files')]));
+    for (const coll of state.docCollections) {
+      items.push(navItem(coll.label, `doc:${coll.name}`, 'nav-sub'));
+    }
+  }
+  if (state.logs.length) {
+    items.push(el('div', { class: 'nav-section' }, [icon('logs'), el('span', {}, 'Logs')]));
+    for (const lg of state.logs) {
+      items.push(navItem(lg.label, `log:${lg.name}`, 'nav-sub'));
+    }
+  }
+  nav.replaceChildren(...items);
+}
+
+function renderCmdline(v) {
+  const bar = $('cmdline');
+  let cmd = null;
+  if (v.type === 'resource') cmd = state.snapshots.get(`${v.cli}/${v.resource}`)?.command;
+  else if (v.type === 'activity') cmd = state.activityCommand;
+  else if (v.type === 'doc') cmd = state.activeDocPath ? `file · ${state.activeDocPath}` : null;
+  else if (v.type === 'log') cmd = state.logCache.get(v.name)?.command ?? null;
+  else if (v.type === 'overview') cmd = 'derived · ncl groups/sessions/messaging-groups/wirings + config-get + activity';
+  bar.hidden = !cmd;
+  bar.textContent = cmd ? `$ ${cmd}` : '';
+}
+
+// ---- Overview page (rich agent cards) ----
+
+function renderOverviewPage() {
+  const content = $('content');
+  const groups = state.snapshots.get('ncl/groups')?.rows;
+  if (!groups) { content.replaceChildren(el('div', { class: 'empty' }, 'Loading…')); return; }
+  const sessions = state.snapshots.get('ncl/sessions')?.rows ?? [];
+  const wirings = state.snapshots.get('ncl/wirings')?.rows ?? [];
+  const mgs = state.snapshots.get('ncl/messaging-groups')?.rows ?? [];
+  const act = state.activity?.sessions ?? [];
+  const mgName = (id) => mgs.find((m) => m.id === id)?.name ?? mgs.find((m) => m.id === id)?.platform_id ?? id;
+
+  const field = (k, v, cls = '') => el('div', { class: 'ov-field' }, [el('span', { class: 'k' }, k), el('span', { class: `v ${cls}` }, v)]);
+
+  const cards = groups.map((g) => {
+    const gs = sessions.filter((s) => s.agent_group_id === g.id);
+    const lastActive = gs.map((s) => s.last_active).filter(Boolean).sort().at(-1) ?? null;
+    const container = gs.some((s) => s.container_status === 'running') ? 'running' : (gs[0]?.container_status ?? 'none');
+    const ga = act.filter((a) => a.agent_group_id === g.id);
+    const msgIn = ga.reduce((a, s) => a + s.in, 0), msgOut = ga.reduce((a, s) => a + s.out, 0);
+    const cfg = state.configCache.get(g.id);
+    const chans = wirings.filter((w) => w.agent_group_id === g.id).map((w) => `${mgs.find((m) => m.id === w.messaging_group_id)?.channel_type ?? '?'}: ${mgName(w.messaging_group_id)}`);
+    const status = staleness(lastActive);
+    const containerColor = container === 'running' ? 'green' : container === 'idle' ? 'green' : container === 'none' ? 'gray' : 'gray';
+
+    const fields = [
+      el('div', { class: 'ov-field' }, [el('span', { class: 'k' }, 'container'), badgeChip(container, { running: 'green', idle: 'green', stopped: 'gray', none: 'gray' })]),
+      field('sessions', String(gs.length)),
+      field('messages', `${msgIn} in · ${msgOut} out`),
+      field('last active', lastActive ? relTime(lastActive) : '—', lastActive ? '' : 'dim'),
+    ];
+    if (cfg) {
+      fields.push(field('provider / model', `${cfg.provider ?? 'claude'} / ${cfg.model ?? 'default'}`));
+      fields.push(el('div', { class: 'ov-field' }, [el('span', { class: 'k' }, 'cli scope'), badgeChip(cfg.cli_scope ?? 'group', { global: 'amber', group: 'green', disabled: 'gray' })]));
+      const pkgs = (cfg.packages_apt?.length ?? 0) + (cfg.packages_npm?.length ?? 0);
+      const mcp = Object.keys(cfg.mcp_servers ?? {}).length;
+      if (pkgs || mcp) fields.push(field('extras', `${pkgs} pkgs · ${mcp} mcp`));
+    }
+
+    return el('div', { class: 'ov-card' }, [
+      el('div', { class: 'ov-head' }, [
+        el('span', { class: `dot ${status}` }),
+        el('span', { class: 'ov-name' }, g.name),
+        el('span', { class: 'ov-folder' }, g.folder),
+      ]),
+      el('div', { class: 'ov-fields' }, fields),
+      el('div', { class: 'ov-chans' }, chans.map((c) => el('span', { class: 'badge' }, c))),
+    ]);
+  });
+
+  content.replaceChildren(
+    el('h2', { class: 'page-title' }, 'Agents overview'),
+    el('div', { class: 'ov-cards' }, cards),
+  );
+}
+
+// ---- Activity ----
+
+function renderActivity() {
+  const content = $('content');
+  const data = state.activity;
+  if (!data) { content.replaceChildren(el('div', { class: 'empty' }, 'Loading…')); return; }
+  const { series, sessions } = data;
+  const totalIn = series.reduce((a, d) => a + d.in, 0);
+  const totalOut = series.reduce((a, d) => a + d.out, 0);
+
+  const W = 720, H = 220, padL = 34, padB = 28, padT = 10;
+  const max = Math.max(1, ...series.map((d) => Math.max(d.in, d.out)));
+  const slot = (W - padL) / series.length;
+  const bw = Math.max(3, slot / 2 - 2);
+  const yOf = (vv) => padT + (H - padT - padB) * (1 - vv / max);
+  const chart = svg('svg', { viewBox: `0 0 ${W} ${H}`, class: 'activity-chart', preserveAspectRatio: 'none' });
+  for (const frac of [0, 0.5, 1]) {
+    const y = yOf(max * frac);
+    chart.append(svg('line', { x1: padL, y1: y, x2: W, y2: y, class: 'grid' }));
+    chart.append(svg('text', { x: padL - 6, y: y + 3, class: 'axis', 'text-anchor': 'end' }, String(Math.round(max * frac))));
+  }
+  series.forEach((d, i) => {
+    const x = padL + i * slot;
+    chart.append(svg('rect', { x: x + 1, y: yOf(d.in), width: bw, height: yOf(0) - yOf(d.in), class: 'bar-in' }, [svg('title', {}, `${d.date}: ${d.in} in`)]));
+    chart.append(svg('rect', { x: x + 1 + bw, y: yOf(d.out), width: bw, height: yOf(0) - yOf(d.out), class: 'bar-out' }, [svg('title', {}, `${d.date}: ${d.out} out`)]));
+    if (i % 2 === 0) chart.append(svg('text', { x: x + bw, y: H - 8, class: 'axis', 'text-anchor': 'middle' }, d.date.slice(5)));
+  });
+  const legend = el('div', { class: 'activity-legend' }, [
+    el('span', {}, [el('span', { class: 'lg in' }), `inbound (${totalIn})`]),
+    el('span', {}, [el('span', { class: 'lg out' }), `outbound (${totalOut})`]),
+    el('span', { class: 'dim' }, `last ${series.length} days`),
+  ]);
+  const sessRows = [...sessions].sort((a, b) => (b.lastActivity || '').localeCompare(a.lastActivity || '')).map((s) => {
+    const groupName = resolveRef('ncl', { ref: 'groups', label: 'name' }, s.agent_group_id) ?? s.agent_group_id;
+    return el('tr', {}, [
+      el('td', {}, groupName),
+      el('td', {}, el('span', { class: 'trunc', title: s.session_id }, s.session_id.slice(0, 22) + '…')),
+      el('td', { class: 'num' }, String(s.in)),
+      el('td', { class: 'num' }, String(s.out)),
+      el('td', {}, s.lastActivity ? el('span', { class: 'reltime', title: s.lastActivity }, relTime(s.lastActivity)) : el('span', { class: 'null' }, '—')),
+    ]);
+  });
+  content.replaceChildren(
+    el('h2', { class: 'page-title' }, 'Message activity'),
+    el('div', { class: 'activity-wrap' }, [
+      legend,
+      el('div', { class: 'chart-box' }, chart),
+      el('div', { class: 'table-wrap' }, el('table', { class: 'activity-table' }, [
+        el('thead', {}, el('tr', {}, ['agent', 'session', 'in', 'out', 'last activity'].map((h) => el('th', {}, h)))),
+        el('tbody', {}, sessRows),
+      ])),
+    ]),
+  );
+}
+
+// ---- Logs (tail of a log file) ----
+
+function renderLogPage(name) {
+  const content = $('content');
+  const label = state.logs.find((l) => l.name === name)?.label ?? name;
+  const cached = state.logCache.get(name);
+  if (!cached) { content.replaceChildren(el('h2', { class: 'page-title' }, label), el('div', { class: 'empty' }, 'Loading…')); return; }
+  const view = el('div', { class: 'log-view' });
+  for (const line of cached.text.split('\n')) {
+    const lvl = /\bERROR\b/i.test(line) ? 'err' : /\bWARN(ING)?\b/i.test(line) ? 'warn' : '';
+    view.append(el('div', { class: `log-line ${lvl}` }, line || ' '));
+  }
+  content.replaceChildren(el('h2', { class: 'page-title' }, label), el('div', { class: 'log-box' }, view));
+  // follow the tail — scroll to the newest line
+  requestAnimationFrame(() => { const b = content.querySelector('.log-box'); if (b) b.scrollTop = b.scrollHeight; });
+}
+
+// ---- Files (doc viewer) ----
+
+function renderDocs() {
+  const coll = activeCollection();
+  const content = $('content');
+  if (!coll) { content.replaceChildren(el('div', { class: 'empty' }, 'No documents.')); return; }
+  if (!coll.files.length) { content.replaceChildren(el('div', { class: 'empty' }, `No ${coll.label.toLowerCase()}.`)); return; }
+  // display name: drop the group prefix, the `/SKILL.md` tail (show the skill
+  // dir), and the .md extension — leaving e.g. "meeting-tagger" or "2026-06-13-…"
+  const itemName = (label) => {
+    let n = label.includes('/') ? label.split('/').slice(1).join('/').trim() : label;
+    return n.replace(/\/SKILL\.md$/, '').replace(/\.md$/, '') || label;
+  };
+  const newestFirst = coll.name === 'conversations';
+  const groups = new Map();
+  for (const f of coll.files) { if (!groups.has(f.group)) groups.set(f.group, []); groups.get(f.group).push(f); }
+  const toggleGroup = (g) => {
+    state.openDocGroups.has(g) ? state.openDocGroups.delete(g) : state.openDocGroups.add(g);
+    state.renderedSig = null; render();
+  };
+  const list = el('div', { class: 'doc-list' });
+  for (const [group, files] of groups) {
+    const open = state.openDocGroups.has(group);
+    list.append(el('button', { class: 'doc-group-toggle' + (open ? ' open' : ''), onclick: () => toggleGroup(group) }, [
+      el('span', { class: 'chev' }, open ? '▾' : '▸'),
+      el('span', { class: 'g-name' }, group || '—'),
+      el('span', { class: 'g-count' }, String(files.length)),
+    ]));
+    if (open) {
+      const ordered = newestFirst ? [...files].reverse() : files;
+      for (const f of ordered) {
+        list.append(el('button', { class: 'doc-item' + (f.path === state.activeDocPath ? ' active' : ''), title: f.path, onclick: () => openDoc(coll.name, f.path) }, itemName(f.label) || f.path));
+      }
+    }
+  }
+  const pane = el('div', { class: 'doc-content' });
+  const cached = state.activeDocPath ? state.docCache.get(`${coll.name}\0${state.activeDocPath}`) : null;
+  if (!state.activeDocPath) pane.append(el('div', { class: 'empty' }, 'Select a document.'));
+  else if (!cached) pane.append(el('div', { class: 'empty' }, 'Loading…'));
+  else if (cached.lang === 'error') pane.append(el('div', { class: 'tab-error' }, cached.content));
+  else if (cached.lang === 'json') {
+    let pretty = cached.content;
+    try { pretty = JSON.stringify(JSON.parse(cached.content), null, 2); } catch { /* keep raw */ }
+    pane.append(el('pre', { class: 'code json' }, pretty));
+  } else if (cached.lang === 'markdown') {
+    const md = el('div', { class: 'markdown' }); md.innerHTML = mdToHtml(cached.content); pane.append(md);
+  } else pane.append(el('pre', { class: 'code' }, cached.content));
+  content.replaceChildren(el('h2', { class: 'page-title' }, coll.label), el('div', { class: 'doc-viewer' }, [list, pane]));
+}
+
+// ---- resource table ----
+
+function renderTable(cliName, resource) {
+  const content = $('content');
+  const cli = state.clis.find((c) => c.name === cliName);
+  if (!cli) { content.replaceChildren(el('div', { class: 'empty' }, 'No such CLI.')); return; }
+  const key = `${cliName}/${resource}`;
+  const snapshot = state.snapshots.get(key);
+  const error = state.errors.get(key);
+  const canDrill = (cli.commands || []).includes('get');
+  const parts = [el('h2', { class: 'page-title' }, resource)];
+  if (cli.help) parts.push(helpPanel(state.helpCache.get(key)));
+  if (error && snapshot) parts.push(el('div', { class: 'stale-note' }, `⚠ live fetch failing — snapshot from ${new Date(snapshot.fetchedAt).toLocaleTimeString()}`));
+  if (!snapshot) {
+    parts.push(error ? el('div', { class: 'tab-error' }, [`Failed to load ${resource}.`, el('pre', {}, error)]) : el('div', { class: 'empty' }, 'Loading…'));
+    content.replaceChildren(...parts); return;
+  }
+  const rows = snapshot.rows;
+  parts.push(summaryBar(resource, rows, cli.summary?.[resource], cli));
+  if (rows.length === 0) { parts.push(el('div', { class: 'empty' }, `No ${resource}.`)); content.replaceChildren(...parts); return; }
+  const columns = [];
+  for (const row of rows) for (const k of Object.keys(row)) if (!columns.includes(k)) columns.push(k);
+  const ctx = { cliName, enrich: cli.enrich?.[resource], badges: cli.badges };
+  const body = rows.map((row) => {
+    const id = row.id; const canRow = canDrill && id != null;
+    return el('tr', { class: canRow ? 'drillable' : '', ...(canRow ? { onclick: () => openDetail(cliName, resource, String(id)) } : {}) },
+      columns.map((c) => buildCell(row[c], c, ctx)));
+  });
+  parts.push(el('div', { class: 'table-wrap' }, el('table', {}, [
+    el('thead', {}, el('tr', {}, columns.map((c) => el('th', {}, c)))),
+    el('tbody', {}, body),
+  ])));
+  content.replaceChildren(...parts);
+}
+
+// ---- drill-down detail overlay ----
+
+function renderDetail() {
+  const overlay = $('detail');
+  if (!state.detail) { overlay.hidden = true; overlay.replaceChildren(); return; }
+  overlay.hidden = false;
+  const d = state.detail;
+  const panel = el('div', { class: 'detail-panel' });
+  panel.append(el('div', { class: 'detail-head' }, [
+    el('div', {}, [el('span', { class: 'detail-res' }, d.resource), ' ', el('span', { class: 'detail-id' }, d.id)]),
+    el('button', { class: 'detail-close', onclick: closeDetail, title: 'Close' }, '✕'),
+  ]));
+  const sub = el('div', { class: 'detail-body' });
+  if (d.loading) sub.append(el('div', { class: 'empty' }, 'Loading…'));
+  else if (d.error) sub.append(el('div', { class: 'tab-error' }, d.error));
+  else if (d.record) sub.append(el('div', { class: 'kv' }, kvRows(d.record)));
+  if (d.config) {
+    sub.append(el('div', { class: 'detail-section' }, 'Container config'));
+    sub.append(el('div', { class: 'kv' }, kvRows(d.config)));
+  }
+  panel.append(sub);
+  overlay.replaceChildren(panel);
+}
+
+// ---------------------------------------------------------------- boot
+
+$('pause').addEventListener('click', () => {
+  state.paused = !state.paused;
+  $('pause').textContent = state.paused ? '▶ resume' : '⏸ pause';
+  $('pause').classList.toggle('paused', state.paused);
+  state.renderedSig = null; render();
+});
+$('refresh').addEventListener('click', () => { if (!state.refreshing) refresh(true); });
+$('hamburger').addEventListener('click', () => { state.sidebarOpen = !state.sidebarOpen; state.renderedSig = null; render(); });
+$('scrim').addEventListener('click', () => { state.sidebarOpen = false; state.renderedSig = null; render(); });
+$('detail').addEventListener('click', (e) => { if (e.target === $('detail')) closeDetail(); });
+document.addEventListener('keydown', (e) => { if (e.key === 'Escape') { if (state.detail) closeDetail(); else if (state.sidebarOpen) { state.sidebarOpen = false; state.renderedSig = null; render(); } } });
+
+async function tick() {
+  if (!state.paused) { try { await refresh(); } catch { /* keep snapshots; retry next tick */ } }
+  else renderControls();
+  setTimeout(tick, state.refreshSeconds * 1000);
+}
+tick();

.claude/skills/add-clidash/add/tools/clidash/public/favicon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#141a24"/>
+      <stop offset="1" stop-color="#0b0e14"/>
+    </linearGradient>
+  </defs>
+  <rect width="32" height="32" rx="7.5" fill="url(#bg)"/>
+  <rect x="0.5" y="0.5" width="31" height="31" rx="7" fill="none" stroke="#2b3342" stroke-width="1"/>
+  <text x="16.2" y="20.8" font-family="monospace" font-size="15" font-weight="700" letter-spacing="-0.5" text-anchor="middle" fill="#5b9dff">ncl</text>
+</svg>

.claude/skills/add-clidash/add/tools/clidash/public/index.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>clidash</title>
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="icon" type="image/x-icon" href="/favicon.ico">
+  <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+  <link rel="manifest" href="/site.webmanifest">
+  <meta name="theme-color" content="#0a0c11">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <button id="hamburger" class="hamburger" title="Menu" aria-label="Toggle menu">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="4" x2="20" y1="6" y2="6"/><line x1="4" x2="20" y1="12" y2="12"/><line x1="4" x2="20" y1="18" y2="18"/></svg>
+  </button>
+  <div id="scrim" class="scrim" hidden></div>
+
+  <div class="app">
+    <aside id="sidebar" class="sidebar">
+      <div class="brand"><h1>clidash</h1></div>
+      <div class="controls">
+        <button id="refresh" class="refresh" title="Refresh now">↻ refresh</button>
+        <button id="pause" class="pause" title="Pause auto-refresh">⏸ pause</button>
+      </div>
+      <div id="updated" class="updated"></div>
+      <nav id="nav" class="nav"></nav>
+    </aside>
+
+    <main class="main">
+      <div id="banner" class="banner" hidden></div>
+      <div id="cmdline" class="cmdline" hidden></div>
+      <section id="content" class="content"></section>
+    </main>
+  </div>
+
+  <div id="detail" class="detail-overlay" hidden></div>
+
+  <script type="module" src="app.js"></script>
+</body>
+</html>

.claude/skills/add-clidash/add/tools/clidash/public/md.js

@@ -0,0 +1,68 @@
+// Minimal, dependency-free, XSS-safe markdown → HTML for clidash's file viewer
+// (SKILL.md / CLAUDE.md). Pure string functions, no DOM — importable in both the
+// browser (app.js) and node tests.
+//
+// Safety model: the ENTIRE source is HTML-escaped first, so no raw markup from a
+// file can reach innerHTML. Markdown transforms then emit only tags this module
+// generates. Link hrefs are taken from the URL capture group and gated to an
+// http(s) scheme, so a `javascript:`/`data:` URL (or one smuggled via link text)
+// can never become an executable href.
+
+export function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}
+
+export function mdToHtml(src) {
+  const lines = escapeHtml(src).split('\n');
+  const out = [];
+  let i = 0;
+  const inline = (t) => t
+    .replace(/`([^`]+)`/g, '<code>$1</code>')
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/\*([^*]+)\*/g, '<em>$1</em>')
+    .replace(/\[([^\]]+)\]\((https?:[^)\s]+)\)/g, (m, text, url) =>
+      /^https?:\/\//i.test(url) ? `<a href="${url}" target="_blank" rel="noopener noreferrer">${text}</a>` : m);
+  while (i < lines.length) {
+    const line = lines[i];
+    if (/^```/.test(line)) {
+      const buf = [];
+      i++;
+      while (i < lines.length && !/^```/.test(lines[i])) buf.push(lines[i++]);
+      i++;
+      out.push(`<pre class="code"><code>${buf.join('\n')}</code></pre>`);
+      continue;
+    }
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    if (h) { out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`); i++; continue; }
+    if (/^\s*([-*])\s+/.test(line)) {
+      const items = [];
+      while (i < lines.length && /^\s*([-*])\s+/.test(lines[i])) {
+        items.push(`<li>${inline(lines[i].replace(/^\s*([-*])\s+/, ''))}</li>`);
+        i++;
+      }
+      out.push(`<ul>${items.join('')}</ul>`);
+      continue;
+    }
+    if (/^\s*\d+\.\s+/.test(line)) {
+      const items = [];
+      while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i])) {
+        items.push(`<li>${inline(lines[i].replace(/^\s*\d+\.\s+/, ''))}</li>`);
+        i++;
+      }
+      out.push(`<ol>${items.join('')}</ol>`);
+      continue;
+    }
+    if (/^\s*(---+|\*\*\*+)\s*$/.test(line)) { out.push('<hr>'); i++; continue; }
+    if (/^\s*>\s?/.test(line)) { out.push(`<blockquote>${inline(line.replace(/^\s*>\s?/, ''))}</blockquote>`); i++; continue; }
+    if (line.trim() === '') { i++; continue; }
+    const para = [line];
+    i++;
+    while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,6}\s|```|\s*[-*]\s|\s*\d+\.\s|\s*>)/.test(lines[i])) {
+      para.push(lines[i++]);
+    }
+    out.push(`<p>${inline(para.join(' '))}</p>`);
+  }
+  return out.join('\n');
+}

.claude/skills/add-clidash/add/tools/clidash/public/site.webmanifest

@@ -0,0 +1,11 @@
+{
+  "name": "clidash",
+  "short_name": "ncl",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ],
+  "theme_color": "#0a0c11",
+  "background_color": "#0a0c11",
+  "display": "standalone"
+}

.claude/skills/add-clidash/add/tools/clidash/public/style.css

@@ -0,0 +1,328 @@
+/* clidash — refined terminal-ops console.
+   IBM Plex superfamily (Sans for UI, Mono for the CLI identity), a deep layered
+   dark palette, real depth, and precise micro-interactions. */
+
+:root {
+  /* layered surfaces */
+  --bg: #0a0c11;
+  --bg-grad: #10141d;
+  --panel: #13171f;
+  --panel-2: #1a1f2a;
+  --border: #222834;
+  --border-strong: #2e3644;
+  /* text */
+  --text: #e8edf5;
+  --dim: #98a2b3;
+  --faint: #5c6675;
+  /* accent + semantics */
+  --accent: #5b9dff;
+  --accent-soft: rgba(91, 157, 255, 0.14);
+  --green: #4cc97a;
+  --amber: #e0a93a;
+  --red: #f76d6d;
+  --purple: #c08cff;
+  --gray: #6b7585;
+  /* shape + motion */
+  --radius: 11px;
+  --radius-sm: 8px;
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);
+  --shadow: 0 6px 22px -8px rgba(0, 0, 0, 0.5);
+  --shadow-lg: 0 18px 44px -12px rgba(0, 0, 0, 0.6);
+  --ease: 160ms cubic-bezier(0.2, 0.6, 0.2, 1);
+  --font-sans: "IBM Plex Sans", -apple-system, system-ui, Segoe UI, sans-serif;
+  --font-mono: "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace;
+}
+
+* { box-sizing: border-box; margin: 0; padding: 0; }
+[hidden] { display: none !important; }
+
+html { scrollbar-color: var(--border-strong) transparent; }
+body {
+  background:
+    radial-gradient(120% 80% at 50% -10%, var(--bg-grad) 0%, transparent 55%),
+    var(--bg);
+  background-attachment: fixed;
+  color: var(--text);
+  font-family: var(--font-sans);
+  font-size: 14px;
+  line-height: 1.5;
+  -webkit-text-size-adjust: 100%;
+  -webkit-font-smoothing: antialiased;
+}
+
+::selection { background: var(--accent-soft); }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 4px; }
+
+h1 {
+  font-family: var(--font-mono); font-size: 17px; font-weight: 600;
+  letter-spacing: -0.3px; color: var(--text);
+}
+h1::before { content: "▍"; color: var(--accent); margin-right: 4px; }
+
+/* ---- layout ---- */
+
+.app { display: flex; align-items: stretch; min-height: 100vh; min-height: 100dvh; }
+
+.sidebar {
+  width: 236px; flex-shrink: 0; height: 100vh; height: 100dvh;
+  position: sticky; top: 0; align-self: flex-start; overflow-y: auto;
+  background: linear-gradient(180deg, rgba(255, 255, 255, 0.015), transparent 200px), var(--bg);
+  border-right: 1px solid var(--border);
+  padding: 18px 12px 40px; display: flex; flex-direction: column; gap: 10px;
+}
+.sidebar .brand { padding: 2px 8px 6px; }
+.sidebar .controls { display: flex; gap: 8px; padding: 0 4px; }
+.sidebar .updated { color: var(--faint); font-size: 11.5px; padding: 0 8px; min-height: 16px; font-family: var(--font-mono); }
+
+.pause, .refresh {
+  flex: 1; background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm);
+  color: var(--dim); padding: 6px 10px; font-size: 12.5px; font-family: var(--font-mono);
+  cursor: pointer; transition: color var(--ease), border-color var(--ease), background var(--ease);
+}
+.pause:hover, .refresh:hover { color: var(--text); border-color: var(--border-strong); background: var(--panel-2); }
+.pause.paused { color: var(--amber); border-color: var(--amber); }
+.refresh.spinning { color: var(--accent); border-color: var(--accent); animation: pulse 0.85s ease-in-out infinite; }
+@keyframes pulse { 50% { opacity: 0.5; } }
+
+.nav { display: flex; flex-direction: column; gap: 1px; margin-top: 6px; }
+.nav-section {
+  color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 1px;
+  font-weight: 600; margin: 16px 10px 5px; font-family: var(--font-mono);
+  display: flex; align-items: center; gap: 7px;
+}
+.nav-section svg { width: 13px; height: 13px; opacity: 0.7; }
+.nav-item {
+  display: flex; align-items: center; gap: 9px; text-align: left;
+  background: none; border: none; border-radius: var(--radius-sm);
+  color: var(--dim); padding: 7px 10px; font-size: 13.5px; cursor: pointer; width: 100%;
+  font-family: var(--font-sans); position: relative;
+  transition: color var(--ease), background var(--ease);
+}
+.nav-item svg { width: 16px; height: 16px; flex-shrink: 0; opacity: 0.85; }
+.nav-item:hover { background: var(--panel); color: var(--text); }
+.nav-item.active { background: var(--accent-soft); color: var(--text); }
+.nav-item.active::before {
+  content: ""; position: absolute; left: -12px; top: 50%; transform: translateY(-50%);
+  width: 3px; height: 18px; background: var(--accent); border-radius: 0 3px 3px 0;
+}
+.nav-item.nav-sub { padding-left: 16px; font-size: 13px; }
+.nav-item.nav-sub.active { color: var(--accent); }
+
+.hamburger {
+  display: none; position: fixed; top: 12px; left: 12px; z-index: 60;
+  background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm);
+  color: var(--text); width: 40px; height: 40px; cursor: pointer; align-items: center; justify-content: center;
+}
+.hamburger svg { width: 20px; height: 20px; }
+.scrim { display: none; }
+
+.main { flex: 1; min-width: 0; padding: 26px 28px 64px; max-width: 1500px; }
+.page-title {
+  font-size: 20px; font-weight: 600; letter-spacing: -0.4px; margin-bottom: 16px;
+  animation: fadeUp 0.3s var(--ease) both;
+}
+
+.banner {
+  background: rgba(247, 109, 109, 0.1); border: 1px solid rgba(247, 109, 109, 0.4);
+  border-radius: var(--radius-sm); color: var(--red); padding: 9px 14px; font-size: 13.5px; margin-bottom: 16px;
+}
+.cmdline {
+  font-family: var(--font-mono); font-size: 12px; color: var(--dim);
+  background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm);
+  padding: 9px 14px; margin-bottom: 18px; overflow-x: auto; white-space: nowrap; box-shadow: var(--shadow-sm);
+}
+.cmdline::first-letter { color: var(--green); }
+
+@keyframes fadeUp { from { opacity: 0; transform: translateY(7px); } }
+
+/* ---- overview cards ---- */
+
+.ov-cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(310px, 1fr)); gap: 16px; }
+.ov-card {
+  background: linear-gradient(180deg, rgba(255, 255, 255, 0.018), transparent 40%), var(--panel);
+  border: 1px solid var(--border); border-radius: var(--radius); padding: 17px 19px;
+  box-shadow: var(--shadow); transition: border-color var(--ease), transform var(--ease);
+  animation: fadeUp 0.4s var(--ease) both;
+}
+.ov-card:nth-child(2) { animation-delay: 0.05s; }
+.ov-card:nth-child(3) { animation-delay: 0.1s; }
+.ov-card:nth-child(4) { animation-delay: 0.15s; }
+.ov-card:hover { border-color: var(--border-strong); transform: translateY(-2px); }
+.ov-head { display: flex; align-items: center; gap: 9px; margin-bottom: 14px; }
+.ov-head .ov-name { font-weight: 600; font-size: 15px; }
+.ov-head .ov-folder { color: var(--faint); font-size: 12px; font-family: var(--font-mono); }
+.ov-fields { display: flex; flex-direction: column; gap: 7px; }
+.ov-field { display: flex; justify-content: space-between; align-items: center; font-size: 13px; }
+.ov-field .k { color: var(--dim); }
+.ov-field .v { color: var(--text); font-variant-numeric: tabular-nums; } .ov-field .v.dim { color: var(--faint); }
+.ov-chans { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 14px; }
+
+.dot, .ov-head .dot { width: 9px; height: 9px; border-radius: 50%; flex-shrink: 0; }
+.dot.green { background: var(--green); box-shadow: 0 0 8px -1px var(--green); }
+.dot.amber { background: var(--amber); box-shadow: 0 0 8px -1px var(--amber); }
+.dot.red { background: var(--red); box-shadow: 0 0 8px -1px var(--red); }
+.dot.gray { background: var(--gray); }
+
+.badge {
+  font-size: 11.5px; border: 1px solid var(--border-strong); border-radius: 99px;
+  padding: 2px 10px; color: var(--dim); background: var(--panel-2); font-family: var(--font-mono);
+}
+
+/* ---- status badges + enriched cells ---- */
+.badge-status { display: inline-flex; align-items: center; gap: 6px; font-size: 12.5px; }
+.badge-status .dot { width: 7px; height: 7px; }
+.badge-status.green { color: var(--green); } .badge-status.amber { color: var(--amber); }
+.badge-status.red { color: var(--red); } .badge-status.gray { color: var(--gray); }
+td.enriched span:first-child { color: var(--text); }
+td.enriched .raw-id { display: block; color: var(--faint); font-size: 11px; font-family: var(--font-mono); }
+
+/* ---- summary bar ---- */
+.summary-bar { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin: 2px 0 16px; font-size: 13px; }
+.summary-bar .sum-count { color: var(--text); font-weight: 600; }
+.summary-bar .sum-sep { color: var(--border-strong); }
+.summary-bar .sum-chip { color: var(--dim); font-family: var(--font-mono); font-size: 12px; }
+
+/* ---- per-resource help panel ---- */
+.help-panel { margin-bottom: 18px; background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); padding: 13px 16px; box-shadow: var(--shadow-sm); }
+.help-head { color: var(--dim); font-size: 13px; line-height: 1.6; }
+.help-head.dim { color: var(--faint); }
+.help-more { margin-top: 9px; }
+.help-more > summary { cursor: pointer; color: var(--accent); font-size: 12px; list-style: none; user-select: none; font-family: var(--font-mono); }
+.help-more > summary::-webkit-details-marker { display: none; }
+.help-more > summary::before { content: "▸ "; }
+.help-more[open] > summary::before { content: "▾ "; }
+.help-text {
+  margin: 9px 0 0; background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius-sm);
+  padding: 13px 15px; font-size: 12px; line-height: 1.6; color: var(--dim);
+  white-space: pre-wrap; overflow-x: auto; font-family: var(--font-mono);
+}
+
+/* ---- document viewer ---- */
+.doc-viewer { display: grid; grid-template-columns: 264px 1fr; gap: 20px; align-items: start; }
+.doc-list { display: flex; flex-direction: column; gap: 2px; max-height: 76vh; overflow-y: auto; padding-right: 4px; }
+.doc-group-toggle {
+  flex-shrink: 0; display: flex; align-items: center; gap: 7px; width: 100%;
+  background: none; border: none; cursor: pointer; text-align: left;
+  color: var(--dim); font-size: 11px; text-transform: uppercase; letter-spacing: 1px;
+  font-weight: 600; font-family: var(--font-mono); margin: 12px 0 4px; padding: 5px 8px;
+  border-radius: var(--radius-sm); transition: color var(--ease), background var(--ease);
+}
+.doc-group-toggle:first-child { margin-top: 0; }
+.doc-group-toggle:hover { color: var(--text); background: var(--panel); }
+.doc-group-toggle.open { color: var(--text); }
+.doc-group-toggle .chev { color: var(--accent); width: 10px; }
+.doc-group-toggle .g-name { flex: 1; }
+.doc-group-toggle .g-count {
+  color: var(--faint); background: var(--panel-2); border-radius: 99px;
+  padding: 1px 8px; font-size: 10.5px; letter-spacing: 0;
+}
+.doc-item {
+  flex-shrink: 0; text-align: left; background: none; border: none; border-radius: var(--radius-sm);
+  color: var(--dim); padding: 6px 11px; font-size: 13px; line-height: 1.5; cursor: pointer;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis; transition: color var(--ease), background var(--ease);
+}
+.doc-item:hover { background: var(--panel); color: var(--text); }
+.doc-item.active { background: var(--accent-soft); color: var(--accent); }
+.doc-content {
+  background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius);
+  padding: 22px 26px; min-height: 220px; max-height: 78vh; overflow-y: auto; box-shadow: var(--shadow);
+}
+
+.markdown { font-size: 14px; line-height: 1.7; color: var(--text); }
+.markdown h1, .markdown h2, .markdown h3, .markdown h4 { margin: 20px 0 8px; line-height: 1.3; font-family: var(--font-mono); }
+.markdown h1 { font-size: 21px; } .markdown h2 { font-size: 17px; color: var(--accent); } .markdown h3 { font-size: 15px; }
+.markdown h1:first-child, .markdown h2:first-child { margin-top: 0; }
+.markdown p { color: var(--text); margin: 8px 0; }
+.markdown ul, .markdown ol { margin: 8px 0 8px 22px; }
+.markdown li { margin: 3px 0; }
+.markdown a { color: var(--accent); }
+.markdown hr { border: none; border-top: 1px solid var(--border); margin: 18px 0; }
+.markdown blockquote { border-left: 3px solid var(--border-strong); padding-left: 12px; color: var(--dim); margin: 8px 0; }
+.markdown code { background: var(--bg); border: 1px solid var(--border); border-radius: 5px; padding: 1px 6px; font-size: 12.5px; font-family: var(--font-mono); }
+.markdown pre.code, .doc-content pre.code {
+  background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius-sm);
+  padding: 14px; overflow-x: auto; font-size: 12.5px; line-height: 1.6; margin: 12px 0; font-family: var(--font-mono);
+}
+.markdown pre.code code { background: none; border: none; padding: 0; }
+.doc-content pre.json { color: var(--text); white-space: pre; font-family: var(--font-mono); }
+
+/* ---- activity ---- */
+.activity-wrap { max-width: 780px; }
+.activity-legend { display: flex; gap: 18px; align-items: center; margin-bottom: 12px; font-size: 13px; color: var(--dim); }
+.activity-legend .lg { display: inline-block; width: 11px; height: 11px; border-radius: 3px; margin-right: 6px; vertical-align: -1px; }
+.activity-legend .lg.in { background: var(--accent); } .activity-legend .lg.out { background: var(--purple); }
+.chart-box { background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius); padding: 16px; margin-bottom: 20px; box-shadow: var(--shadow); }
+.activity-chart { width: 100%; height: 220px; display: block; }
+.activity-chart .bar-in { fill: var(--accent); } .activity-chart .bar-out { fill: var(--purple); }
+.activity-chart .grid { stroke: var(--border); stroke-width: 1; }
+.activity-chart .axis { fill: var(--faint); font-size: 9px; font-family: var(--font-mono); }
+.activity-table td.num, .activity-table th:nth-child(3), .activity-table th:nth-child(4) { text-align: right; }
+.activity-table td.num { font-variant-numeric: tabular-nums; }
+
+/* ---- log viewer ---- */
+.log-box {
+  background: var(--bg); border: 1px solid var(--border); border-radius: var(--radius);
+  max-height: 78vh; overflow: auto; padding: 12px 0; box-shadow: var(--shadow);
+}
+.log-view { font-family: var(--font-mono); font-size: 12px; line-height: 1.65; min-width: max-content; }
+.log-line { padding: 0 16px; white-space: pre; color: var(--dim); }
+.log-line:hover { background: var(--panel); }
+.log-line.err { color: var(--red); background: rgba(247, 109, 109, 0.06); }
+.log-line.warn { color: var(--amber); }
+
+/* ---- tables ---- */
+.table-wrap { overflow-x: auto; -webkit-overflow-scrolling: touch; border: 1px solid var(--border); border-radius: var(--radius); box-shadow: var(--shadow-sm); }
+table { border-collapse: collapse; width: 100%; font-size: 13px; }
+th, td { text-align: left; padding: 9px 14px; border-bottom: 1px solid var(--border); white-space: nowrap; }
+tbody tr:last-child td { border-bottom: none; }
+th { color: var(--dim); font-weight: 600; font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.6px; position: sticky; top: 0; background: var(--panel-2); font-family: var(--font-mono); }
+td { font-variant-numeric: tabular-nums; }
+td.null { color: var(--faint); font-style: italic; }
+tr.drillable { cursor: pointer; transition: background var(--ease); }
+tr.drillable:hover td { background: var(--panel); }
+.reltime .abs { color: var(--faint); font-size: 11.5px; margin-left: 6px; font-family: var(--font-mono); }
+td .trunc { cursor: pointer; border-bottom: 1px dotted var(--faint); }
+.stale-note { color: var(--amber); font-size: 12.5px; margin-bottom: 8px; }
+.empty, .tab-error { color: var(--dim); padding: 26px 2px; font-size: 14px; }
+.tab-error { color: var(--red); }
+.tab-error pre { margin-top: 10px; background: var(--panel); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 12px; color: var(--dim); font-size: 12px; overflow-x: auto; white-space: pre-wrap; font-family: var(--font-mono); }
+
+/* ---- drill-down detail overlay ---- */
+.detail-overlay { position: fixed; inset: 0; background: rgba(2, 4, 8, 0.62); display: flex; justify-content: flex-end; z-index: 50; backdrop-filter: blur(2px); animation: fade 0.18s ease; }
+@keyframes fade { from { opacity: 0; } }
+.detail-panel { width: min(580px, 100%); height: 100%; background: var(--bg); border-left: 1px solid var(--border-strong); overflow-y: auto; box-shadow: var(--shadow-lg); animation: slideIn 0.22s var(--ease); }
+@keyframes slideIn { from { transform: translateX(24px); opacity: 0.6; } }
+.detail-head { display: flex; justify-content: space-between; align-items: center; padding: 17px 22px; border-bottom: 1px solid var(--border); position: sticky; top: 0; background: var(--bg); }
+.detail-res { font-weight: 600; font-size: 15px; }
+.detail-id { color: var(--dim); font-family: var(--font-mono); font-size: 13px; }
+.detail-close { background: none; border: 1px solid var(--border); border-radius: var(--radius-sm); color: var(--dim); width: 30px; height: 30px; cursor: pointer; font-size: 14px; transition: color var(--ease), border-color var(--ease); }
+.detail-close:hover { color: var(--text); border-color: var(--accent); }
+.detail-body { padding: 17px 22px 44px; }
+.detail-section { margin: 24px 0 8px; color: var(--faint); font-size: 10.5px; text-transform: uppercase; letter-spacing: 1px; font-weight: 600; border-top: 1px solid var(--border); padding-top: 17px; font-family: var(--font-mono); }
+.kv { display: flex; flex-direction: column; gap: 2px; }
+.kv-row { display: grid; grid-template-columns: 168px 1fr; gap: 12px; padding: 6px 0; border-bottom: 1px solid var(--border); font-size: 13px; }
+.kv-key { color: var(--dim); font-family: var(--font-mono); font-size: 12.5px; }
+.kv-json { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 8px 10px; font-size: 12px; overflow-x: auto; margin: 0; font-family: var(--font-mono); }
+
+/* ---- mobile ---- */
+@media (max-width: 640px) {
+  .hamburger { display: flex; }
+  .sidebar {
+    position: fixed; top: 0; left: 0; z-index: 70; transform: translateX(-100%);
+    transition: transform 0.22s var(--ease); box-shadow: var(--shadow-lg);
+  }
+  .sidebar.open { transform: translateX(0); }
+  .scrim { display: block; position: fixed; inset: 0; background: rgba(2, 4, 8, 0.55); z-index: 65; backdrop-filter: blur(1px); }
+  .scrim[hidden] { display: none; }
+  .main { padding: 58px 16px 48px; }
+  .ov-cards { grid-template-columns: 1fr; }
+  .doc-viewer { grid-template-columns: 1fr; gap: 12px; }
+  .doc-list { max-height: 220px; flex-direction: row; flex-wrap: wrap; }
+  .doc-content { max-height: none; padding: 18px; }
+  .detail-panel { width: 100%; }
+  .kv-row { grid-template-columns: 1fr; gap: 2px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation: none !important; transition: none !important; }
+}

.claude/skills/add-clidash/add/tools/clidash/server.js

@@ -0,0 +1,437 @@
+// clidash — CLI-agnostic read-only web dashboard.
+// Node built-ins only. All per-CLI knowledge lives in clidash.config.json;
+// the only per-CLI code is optional view plugins (views/) and discovery
+// parsers (parsers.js).
+//
+// Security model: the server can only exec the configured argv templates.
+// `{resource}` is the sole substitution and is validated against the
+// discovered/static resource set before exec. execFile, never a shell.
+
+import { createServer } from 'node:http';
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep, basename } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { discoveryParsers, parseOutput, unwrapPath } from './parsers.js';
+import { globFiles, describeFile, resolveDoc } from './docs.js';
+import { collectActivity } from './activity.js';
+import { tailFile } from './logs.js';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const MAX_DOC_BYTES = 2 * 1024 * 1024; // cap a single served document at 2 MB
+
+const DEFAULTS = {
+  bind: '127.0.0.1',
+  port: 4690,
+  refreshSeconds: 60,
+  execTimeoutMs: 10_000,
+  discoveryTtlMs: 60_000,
+};
+
+const CONTENT_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.webmanifest': 'application/manifest+json',
+};
+
+export function createApp(userConfig) {
+  const config = { ...DEFAULTS, ...userConfig };
+  const publicDir = resolve(config.publicDir ?? join(MODULE_DIR, 'public'));
+  const viewsDir = resolve(config.viewsDir ?? join(MODULE_DIR, 'views'));
+
+  // Human-readable form of a command, for display in the UI ("the command run").
+  const displayCmd = (bin, args) => `${basename(bin)} ${args.join(' ')}`;
+
+  // ---- exec --------------------------------------------------------------
+
+  function execCli(cliCfg, args, label) {
+    return new Promise((resolvePromise, rejectPromise) => {
+      execFile(cliCfg.bin, args, {
+        cwd: cliCfg.cwd,
+        timeout: config.execTimeoutMs,
+        maxBuffer: 32 * 1024 * 1024,
+        env: { ...process.env, ...cliCfg.env },
+      }, (error, stdout, stderr) => {
+        if (error) {
+          const timedOut = error.killed || error.signal === 'SIGTERM';
+          const detail = stderr.trim() || error.message;
+          const msg = timedOut
+            ? `${label} timed out after ${config.execTimeoutMs}ms`
+            : `${label} failed: ${detail}`;
+          rejectPromise(new Error(msg));
+          return;
+        }
+        resolvePromise(stdout);
+      });
+    });
+  }
+
+  // ---- resource discovery (cached, coalesced, keeps last good) -----------
+
+  const discoveryCache = new Map(); // cli -> { at, resources }
+  const discoveryInflight = new Map(); // cli -> Promise
+
+  async function discoverResources(cliName) {
+    const cliCfg = config.clis[cliName];
+    if (cliCfg.resources) {
+      return cliCfg.resources.map((name) =>
+        typeof name === 'string' ? { name, description: '' } : name,
+      );
+    }
+    const cached = discoveryCache.get(cliName);
+    if (cached && Date.now() - cached.at < config.discoveryTtlMs) return cached.resources;
+    if (discoveryInflight.has(cliName)) return discoveryInflight.get(cliName);
+
+    const parser = discoveryParsers[cliCfg.discover.parser];
+    if (!parser) throw new Error(`Unknown discovery parser: ${cliCfg.discover.parser}`);
+    const promise = execCli(cliCfg, cliCfg.discover.args, `${cliName} discovery`)
+      .then((stdout) => {
+        const resources = parser(stdout);
+        discoveryCache.set(cliName, { at: Date.now(), resources });
+        return resources;
+      })
+      .finally(() => discoveryInflight.delete(cliName));
+    discoveryInflight.set(cliName, promise);
+    return promise;
+  }
+
+  // ---- row fetching (coalesced per cli+resource) --------------------------
+
+  const listInflight = new Map(); // "cli\0resource" -> Promise
+
+  async function fetchRows(cliName, resourceName) {
+    const cliCfg = config.clis[cliName];
+    const resources = await discoverResources(cliName);
+    if (!resources.some((r) => r.name === resourceName)) {
+      const err = new Error(`Unknown resource "${resourceName}" for CLI "${cliName}"`);
+      err.statusCode = 404;
+      throw err;
+    }
+    const key = `${cliName}\0${resourceName}`;
+    if (listInflight.has(key)) return listInflight.get(key);
+
+    // {resource} may appear as a whole arg or inside one (e.g. an ssh remote
+    // command). Safe either way — the value is allowlist-validated above.
+    const args = cliCfg.list.map((a) => a.replaceAll('{resource}', resourceName));
+    const promise = execCli(cliCfg, args, `${cliName} ${resourceName} list`)
+      .then((stdout) => {
+        const parsed = parseOutput(stdout, cliCfg.output ?? 'json');
+        const rows = unwrapPath(parsed, cliCfg.unwrap);
+        if (!Array.isArray(rows)) {
+          const err = new Error(`${cliName} ${resourceName}: expected an array of rows`);
+          err.raw = stdout;
+          throw err;
+        }
+        return rows;
+      })
+      .finally(() => listInflight.delete(key));
+    listInflight.set(key, promise);
+    return promise;
+  }
+
+  // ---- detail commands (drill-down: get, config-get, …) -------------------
+
+  const cmdInflight = new Map();
+  const ID_RE = /^[A-Za-z0-9:_.-]+$/; // ncl ids / uuids; no shell metas (and execFile never shells)
+
+  async function runCommand(cliName, cmdName, resourceName, id) {
+    const cliCfg = config.clis[cliName];
+    const template = cliCfg.commands?.[cmdName];
+    if (!template) {
+      const err = new Error(`Unknown command "${cmdName}"`);
+      err.statusCode = 404;
+      throw err;
+    }
+    const needsResource = template.includes('{resource}');
+    if (needsResource) {
+      const resources = await discoverResources(cliName);
+      if (!resources.some((r) => r.name === resourceName)) {
+        const err = new Error(`Unknown resource "${resourceName}"`);
+        err.statusCode = 404;
+        throw err;
+      }
+    }
+    if (template.includes('{id}') && !ID_RE.test(id ?? '')) {
+      const err = new Error('Invalid id');
+      err.statusCode = 400;
+      throw err;
+    }
+    const key = `${cliName}\0${cmdName}\0${resourceName}\0${id}`;
+    if (cmdInflight.has(key)) return cmdInflight.get(key);
+    const args = template.map((a) => a.replaceAll('{resource}', resourceName ?? '').replaceAll('{id}', id ?? ''));
+    const promise = execCli(cliCfg, args, `${cliName} ${cmdName}`)
+      .then((stdout) => unwrapPath(parseOutput(stdout, cliCfg.output ?? 'json'), cliCfg.unwrap))
+      .finally(() => cmdInflight.delete(key));
+    cmdInflight.set(key, promise);
+    return promise;
+  }
+
+  // ---- per-resource help (raw text from `<cli> <resource> help`) -----------
+
+  const helpInflight = new Map();
+  async function runHelp(cliName, resourceName) {
+    const cliCfg = config.clis[cliName];
+    if (!cliCfg.help) { const e = new Error(`No help for "${cliName}"`); e.statusCode = 404; throw e; }
+    const resources = await discoverResources(cliName);
+    if (!resources.some((r) => r.name === resourceName)) {
+      const e = new Error(`Unknown resource "${resourceName}"`); e.statusCode = 404; throw e;
+    }
+    const key = `${cliName}\0${resourceName}`;
+    if (helpInflight.has(key)) return helpInflight.get(key);
+    const args = cliCfg.help.map((a) => a.replaceAll('{resource}', resourceName));
+    const promise = execCli(cliCfg, args, `${cliName} ${resourceName} help`).finally(() => helpInflight.delete(key));
+    helpInflight.set(key, promise);
+    return promise;
+  }
+
+  // ---- view plugins --------------------------------------------------------
+
+  async function listViews(cliName) {
+    try {
+      const files = await readdir(viewsDir);
+      return files
+        .filter((f) => f.startsWith(`${cliName}-`) && f.endsWith('.js'))
+        .map((f) => f.slice(cliName.length + 1, -3));
+    } catch {
+      return [];
+    }
+  }
+
+  async function runView(cliName, viewName) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(viewName)) {
+      const err = new Error(`Invalid view name`);
+      err.statusCode = 404;
+      throw err;
+    }
+    const file = join(viewsDir, `${cliName}-${viewName}.js`);
+    let mod;
+    try {
+      mod = await import(pathToFileURL(file).href);
+    } catch (e) {
+      if (e.code === 'ERR_MODULE_NOT_FOUND') {
+        const err = new Error(`No view "${viewName}" for CLI "${cliName}"`);
+        err.statusCode = 404;
+        throw err;
+      }
+      throw e;
+    }
+    return mod.default({ fetch: (resource) => fetchRows(cliName, resource) });
+  }
+
+  // ---- http ----------------------------------------------------------------
+
+  function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(payload);
+  }
+
+  function sendError(res, err) {
+    const status = err.statusCode ?? 502;
+    const body = { ok: false, error: err.message };
+    if (err.raw !== undefined) body.raw = String(err.raw).slice(0, 64 * 1024);
+    sendJson(res, status, body);
+  }
+
+  async function serveStatic(res, urlPath) {
+    const relative = urlPath === '/' ? 'index.html' : decodeURIComponent(urlPath.slice(1));
+    const file = resolve(publicDir, relative);
+    if (file !== publicDir && !file.startsWith(publicDir + sep)) {
+      sendJson(res, 403, { ok: false, error: 'Forbidden' });
+      return;
+    }
+    try {
+      const content = await readFile(file);
+      const ext = file.slice(file.lastIndexOf('.'));
+      // always revalidate so a redeploy is picked up immediately (no stale JS/CSS)
+      res.writeHead(200, { 'Content-Type': CONTENT_TYPES[ext] ?? 'application/octet-stream', 'Cache-Control': 'no-cache' });
+      res.end(content);
+    } catch {
+      sendJson(res, 404, { ok: false, error: 'Not found' });
+    }
+  }
+
+  return createServer(async (req, res) => {
+    try {
+      if (req.method !== 'GET') {
+        sendJson(res, 405, { ok: false, error: 'Read-only dashboard: GET only' });
+        return;
+      }
+      const urlPath = req.url.split('?')[0];
+      const segments = urlPath.split('/').map((s) => decodeURIComponent(s));
+
+      if (urlPath === '/api/clis') {
+        const clis = await Promise.all(Object.keys(config.clis).map(async (name) => {
+          const entry = {
+            name,
+            refreshSeconds: config.refreshSeconds,
+            views: await listViews(name),
+            commands: Object.keys(config.clis[name].commands ?? {}),
+            enrich: config.clis[name].enrich ?? null,
+            badges: config.clis[name].badges ?? null,
+            summary: config.clis[name].summary ?? null,
+            help: !!config.clis[name].help,
+          };
+          try {
+            entry.resources = await discoverResources(name);
+          } catch (e) {
+            // keep last good discovery (≤TTL old) if we have one; always surface the error
+            entry.resources = discoveryCache.get(name)?.resources ?? [];
+            entry.error = e.message;
+          }
+          return entry;
+        }));
+        sendJson(res, 200, { clis });
+        return;
+      }
+
+      if (segments[1] === 'api' && segments[2] === 'r' && segments.length === 5) {
+        const [, , , cliName, resourceName] = segments;
+        if (!config.clis[cliName]) {
+          sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
+          return;
+        }
+        const rows = await fetchRows(cliName, resourceName);
+        const cliCfg = config.clis[cliName];
+        const command = displayCmd(cliCfg.bin, cliCfg.list.map((a) => a.replaceAll('{resource}', resourceName)));
+        sendJson(res, 200, { ok: true, rows, command, fetchedAt: new Date().toISOString() });
+        return;
+      }
+
+      if (segments[1] === 'api' && segments[2] === 'cmd' && segments.length === 5) {
+        const [, , , cliName, cmdName] = segments;
+        if (!config.clis[cliName]) {
+          sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
+          return;
+        }
+        const q = new URL(req.url, 'http://localhost').searchParams;
+        const data = await runCommand(cliName, cmdName, q.get('resource'), q.get('id'));
+        const tmpl = config.clis[cliName].commands?.[cmdName] ?? [];
+        const command = displayCmd(config.clis[cliName].bin,
+          tmpl.map((a) => a.replaceAll('{resource}', q.get('resource') ?? '').replaceAll('{id}', q.get('id') ?? '')));
+        sendJson(res, 200, { ok: true, data, command, fetchedAt: new Date().toISOString() });
+        return;
+      }
+
+      if (segments[1] === 'api' && segments[2] === 'help' && segments.length === 5) {
+        const [, , , cliName, resourceName] = segments;
+        if (!config.clis[cliName]) {
+          sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
+          return;
+        }
+        const text = await runHelp(cliName, resourceName);
+        sendJson(res, 200, { ok: true, text });
+        return;
+      }
+
+      if (segments[1] === 'api' && segments[2] === 'view' && segments.length === 5) {
+        const [, , , cliName, viewName] = segments;
+        if (!config.clis[cliName]) {
+          sendJson(res, 404, { ok: false, error: `Unknown CLI "${cliName}"` });
+          return;
+        }
+        const result = await runView(cliName, viewName);
+        sendJson(res, 200, { ok: true, result, fetchedAt: new Date().toISOString() });
+        return;
+      }
+
+      // Log tails (allowlisted files under logs.dir).
+      if (urlPath === '/api/logs') {
+        sendJson(res, 200, { files: (config.logs?.files ?? []).map((f) => ({ name: f.name, label: f.label ?? f.name })) });
+        return;
+      }
+      if (segments[1] === 'api' && segments[2] === 'log' && segments.length === 4) {
+        const name = segments[3];
+        const file = config.logs?.files?.find((f) => f.name === name);
+        if (!file) { sendJson(res, 404, { ok: false, error: `Unknown log "${name}"` }); return; }
+        const lines = config.logs.tailLines ?? 400;
+        const { text } = await tailFile(join(config.logs.dir, name), lines);
+        sendJson(res, 200, { ok: true, text, command: `tail -n ${lines} ${join(config.logs.dir, name)}`, fetchedAt: new Date().toISOString() });
+        return;
+      }
+
+      // Message activity (read per-session DBs; ncl has no messages resource).
+      if (urlPath === '/api/activity') {
+        if (!config.activity) { sendJson(res, 200, { ok: true, configured: false }); return; }
+        const days = config.activity.days ?? 14;
+        const { sessions, series } = collectActivity(config.activity.sessionsRoot, days, new Date());
+        const command = `node:sqlite · ${config.activity.sessionsRoot}/*/*/{inbound,outbound}.db (last ${days}d)`;
+        sendJson(res, 200, { ok: true, configured: true, sessions, series, command, fetchedAt: new Date().toISOString() });
+        return;
+      }
+
+      // Read-only file viewer (skills, CLAUDE.md, profiles, conversations).
+      if (urlPath === '/api/docs') {
+        const docs = config.docs;
+        const collections = (docs?.collections ?? []).map((coll) => ({
+          name: coll.name,
+          label: coll.label ?? coll.name,
+          lang: coll.lang ?? 'text',
+          files: globFiles(docs.root, coll.patterns, docs.deny ?? []).map((path) => ({
+            path,
+            ...describeFile(path),
+          })),
+        }));
+        sendJson(res, 200, { collections });
+        return;
+      }
+
+      if (urlPath === '/api/doc') {
+        const docs = config.docs;
+        const query = new URL(req.url, 'http://localhost').searchParams;
+        const collName = query.get('c');
+        const relPath = query.get('p') ?? '';
+        const collection = docs?.collections?.find((c) => c.name === collName);
+        if (!collection) {
+          sendJson(res, 404, { ok: false, error: `Unknown collection "${collName}"` });
+          return;
+        }
+        let abs;
+        try {
+          abs = resolveDoc(docs.root, collection, relPath, docs.deny ?? []);
+        } catch {
+          sendJson(res, 404, { ok: false, error: 'Not found' });
+          return;
+        }
+        const content = await readFile(abs, 'utf8');
+        sendJson(res, 200, {
+          ok: true,
+          path: relPath,
+          lang: collection.lang ?? 'text',
+          content: content.length > MAX_DOC_BYTES ? content.slice(0, MAX_DOC_BYTES) : content,
+        });
+        return;
+      }
+
+      if (urlPath.startsWith('/api/')) {
+        sendJson(res, 404, { ok: false, error: 'Not found' });
+        return;
+      }
+
+      await serveStatic(res, urlPath);
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+}
+
+// ---- standalone entry point ------------------------------------------------
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+if (isMain) {
+  const configPath = process.env.CLIDASH_CONFIG ?? join(MODULE_DIR, 'clidash.config.json');
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  if (process.env.PORT) config.port = Number(process.env.PORT);
+  if (process.env.BIND) config.bind = process.env.BIND;
+  const finalConfig = { ...DEFAULTS, ...config };
+  const server = createApp(finalConfig);
+  server.listen(finalConfig.port, finalConfig.bind, () => {
+    console.log(`clidash listening on http://${finalConfig.bind}:${finalConfig.port}`);
+  });
+}

.claude/skills/add-clidash/add/tools/clidash/test/activity-server.test.js

@@ -0,0 +1,46 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { createApp } from '../server.js';
+
+let root;
+before(() => {
+  root = mkdtempSync(join(tmpdir(), 'clidash-actsrv-'));
+  mkdirSync(join(root, 'ag-1', 'sess-1'), { recursive: true });
+  const mk = (p, t, ts) => { const db = new DatabaseSync(p); db.exec(`CREATE TABLE ${t}(id TEXT, timestamp TEXT)`); const i = db.prepare(`INSERT INTO ${t} VALUES (?,?)`); ts.forEach((x, n) => i.run(String(n), x)); db.close(); };
+  const today = new Date().toISOString().slice(0, 10);
+  mk(join(root, 'ag-1', 'sess-1', 'inbound.db'), 'messages_in', [`${today} 09:00:00`, `${today} 10:00:00`]);
+  mk(join(root, 'ag-1', 'sess-1', 'outbound.db'), 'messages_out', [`${today} 09:05:00`]);
+});
+after(() => rmSync(root, { recursive: true, force: true }));
+
+async function withServer(config, fn) {
+  const server = createApp({ port: 0, bind: '127.0.0.1', clis: {}, ...config });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
+}
+
+test('/api/activity: returns per-session totals + a daily series', async () => {
+  await withServer({ activity: { sessionsRoot: root, days: 14 } }, async (base) => {
+    const body = await (await fetch(`${base}/api/activity`)).json();
+    assert.equal(body.ok, true);
+    assert.equal(body.configured, true);
+    assert.equal(body.series.length, 14);
+    assert.equal(body.sessions[0].in, 2);
+    assert.equal(body.sessions[0].out, 1);
+    assert.equal(body.series.at(-1).in, 2); // today
+    assert.equal(body.series.at(-1).out, 1);
+  });
+});
+
+test('/api/activity: not configured → configured:false, no crash', async () => {
+  await withServer({}, async (base) => {
+    const body = await (await fetch(`${base}/api/activity`)).json();
+    assert.equal(body.ok, true);
+    assert.equal(body.configured, false);
+  });
+});

.claude/skills/add-clidash/add/tools/clidash/test/activity.test.js

@@ -0,0 +1,75 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { collectActivity } from '../activity.js';
+
+let root;
+const NOW = new Date('2026-06-14T12:00:00Z');
+
+function makeDb(path, table, timestamps) {
+  const db = new DatabaseSync(path);
+  db.exec(`CREATE TABLE ${table} (id TEXT, timestamp TEXT)`);
+  const ins = db.prepare(`INSERT INTO ${table} (id, timestamp) VALUES (?, ?)`);
+  timestamps.forEach((t, i) => ins.run(String(i), t));
+  db.close();
+}
+
+before(() => {
+  root = mkdtempSync(join(tmpdir(), 'clidash-act-'));
+  // session 1 (group ag-1): 3 inbound across 2 days, 2 outbound today
+  mkdirSync(join(root, 'ag-1', 'sess-1'), { recursive: true });
+  makeDb(join(root, 'ag-1', 'sess-1', 'inbound.db'), 'messages_in',
+    ['2026-06-14 09:01:23', '2026-06-14 10:00:00', '2026-06-13 08:00:00']);
+  makeDb(join(root, 'ag-1', 'sess-1', 'outbound.db'), 'messages_out',
+    ['2026-06-14 09:05:00', '2026-06-14 10:05:00']);
+  // session 2 (group ag-2): 1 inbound 20 days ago (outside 14d window), 0 outbound
+  mkdirSync(join(root, 'ag-2', 'sess-2'), { recursive: true });
+  makeDb(join(root, 'ag-2', 'sess-2', 'inbound.db'), 'messages_in', ['2026-05-25 08:00:00']);
+  makeDb(join(root, 'ag-2', 'sess-2', 'outbound.db'), 'messages_out', []);
+});
+
+after(() => rmSync(root, { recursive: true, force: true }));
+
+test('collectActivity: per-session in/out totals + last activity', () => {
+  const { sessions } = collectActivity(root, 14, NOW);
+  const s1 = sessions.find((s) => s.session_id === 'sess-1');
+  assert.equal(s1.agent_group_id, 'ag-1');
+  assert.equal(s1.in, 3);
+  assert.equal(s1.out, 2);
+  assert.equal(s1.lastActivity, '2026-06-14T10:05:00Z'); // normalized to ISO
+  const s2 = sessions.find((s) => s.session_id === 'sess-2');
+  assert.equal(s2.in, 1);
+  assert.equal(s2.out, 0);
+});
+
+test('collectActivity: series has one bucket per day for `days`, newest last', () => {
+  const { series } = collectActivity(root, 14, NOW);
+  assert.equal(series.length, 14);
+  assert.equal(series[0].date, '2026-06-01');
+  assert.equal(series[13].date, '2026-06-14');
+});
+
+test('collectActivity: counts land in the right day buckets', () => {
+  const { series } = collectActivity(root, 14, NOW);
+  const byDate = Object.fromEntries(series.map((d) => [d.date, d]));
+  assert.equal(byDate['2026-06-14'].in, 2);
+  assert.equal(byDate['2026-06-14'].out, 2);
+  assert.equal(byDate['2026-06-13'].in, 1);
+  assert.equal(byDate['2026-06-13'].out, 0);
+});
+
+test('collectActivity: messages outside the window are counted in totals but not the series', () => {
+  const { series, sessions } = collectActivity(root, 14, NOW);
+  const total = series.reduce((a, d) => a + d.in + d.out, 0);
+  assert.equal(total, 5);              // the 20-day-old message is excluded from series
+  assert.equal(sessions.find((s) => s.session_id === 'sess-2').in, 1); // but still in the total count
+});
+
+test('collectActivity: a dir with no message DBs is not a session (skipped)', () => {
+  mkdirSync(join(root, 'ag-1', '.claude-shared'), { recursive: true }); // scaffolding, no db files
+  const { sessions } = collectActivity(root, 14, NOW);
+  assert.ok(!sessions.some((s) => s.session_id === '.claude-shared'));
+});

.claude/skills/add-clidash/add/tools/clidash/test/cmd.test.js

@@ -0,0 +1,91 @@
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createApp } from '../server.js';
+
+const STUB = fileURLToPath(new URL('./fixtures/stub-cli.js', import.meta.url));
+const tmp = mkdtempSync(join(tmpdir(), 'clidash-cmd-'));
+after(() => rmSync(tmp, { recursive: true, force: true }));
+
+function cli(extra = {}) {
+  return {
+    bin: process.execPath,
+    discover: { args: [STUB, 'help'], parser: 'ncl-help' },
+    list: [STUB, '{resource}', 'list', '--json'],
+    output: 'json',
+    unwrap: 'data',
+    commands: {
+      get: [STUB, '{resource}', 'get', '{id}', '--json'],
+      'config-get': [STUB, 'groups', 'config', 'get', '--id', '{id}', '--json'],
+    },
+    ...extra,
+  };
+}
+
+async function withServer(clis, fn, extra = {}) {
+  const server = createApp({ port: 0, bind: '127.0.0.1', execTimeoutMs: 2000, clis, ...extra });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
+}
+
+test('/api/cmd: runs an allowlisted command with {resource} + {id}', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    const body = await (await fetch(`${base}/api/cmd/ncl/get?resource=sessions&id=sess-123`)).json();
+    assert.equal(body.ok, true);
+    assert.equal(body.data.id, 'sessions-detail');
+    assert.match(body.data.args, /sessions get sess-123/);
+  });
+});
+
+test('/api/cmd: config-get needs no resource', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    const body = await (await fetch(`${base}/api/cmd/ncl/config-get?id=ag-1`)).json();
+    assert.equal(body.ok, true);
+    assert.match(body.data.args, /groups config get --id ag-1/);
+  });
+});
+
+test('/api/cmd: unknown command name → 404 (allowlist)', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    const res = await fetch(`${base}/api/cmd/ncl/delete?resource=groups&id=ag-1`);
+    assert.equal(res.status, 404);
+  });
+});
+
+test('/api/cmd: a {resource} not in the discovered set is rejected without exec', async () => {
+  const countFile = join(tmp, 'cmd-count.txt');
+  const c = cli();
+  c.env = { STUB_COUNT_FILE: countFile };
+  await withServer({ ncl: c }, async (base) => {
+    const res = await fetch(`${base}/api/cmd/ncl/get?resource=evil&id=x`);
+    assert.equal(res.status, 404);
+    // only discovery ran, never a get for the bogus resource
+    const calls = readFileSync(countFile, 'utf8').trim().split('\n');
+    assert.deepEqual(calls, ['help']);
+  });
+});
+
+test('/api/cmd: an id with illegal characters is rejected', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    const res = await fetch(`${base}/api/cmd/ncl/get?resource=sessions&id=${encodeURIComponent('a b;rm -rf')}`);
+    assert.equal(res.status, 400);
+  });
+});
+
+test('/api/cmd: unknown cli → 404', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    assert.equal((await fetch(`${base}/api/cmd/nope/get?resource=sessions&id=x`)).status, 404);
+  });
+});
+
+test('/api/cmd: a cli without a commands map → 404', async () => {
+  const c = cli();
+  delete c.commands;
+  await withServer({ ncl: c }, async (base) => {
+    assert.equal((await fetch(`${base}/api/cmd/ncl/get?resource=sessions&id=x`)).status, 404);
+  });
+});

.claude/skills/add-clidash/add/tools/clidash/test/css.test.js

@@ -0,0 +1,20 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const css = readFileSync(fileURLToPath(new URL('../public/style.css', import.meta.url)), 'utf8');
+
+// Regression: the `hidden` attribute must override author `display` rules.
+// `.detail-overlay` and `.cli-switcher` set `display:flex`, which beats the
+// browser's default `[hidden]{display:none}` — without this reset a hidden
+// overlay stays on top of the page and silently eats every click.
+test('style.css forces [hidden] to display:none with !important', () => {
+  assert.match(css, /\[hidden\]\s*\{\s*display:\s*none\s*!important;?\s*\}/);
+});
+
+// Guard the premise: if these stop using display:flex the reset is less load-
+// bearing, but this documents WHY the reset exists.
+test('the overlays that motivated the reset still use display:flex', () => {
+  assert.match(css, /\.detail-overlay\s*\{[^}]*display:\s*flex/);
+});

.claude/skills/add-clidash/add/tools/clidash/test/docs-server.test.js

@@ -0,0 +1,111 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createApp } from '../server.js';
+
+let root;
+
+before(() => {
+  root = mkdtempSync(join(tmpdir(), 'clidash-docsrv-'));
+  const w = (rel, body) => {
+    const abs = join(root, rel);
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(abs, body);
+  };
+  w('groups/alpha/skills/tagger/SKILL.md', '# tagger\nhello');
+  w('container/skills/welcome/SKILL.md', '# welcome');
+  w('groups/alpha/profile.json', '{"name":"Alpha"}');
+  w('groups/alpha/.env', 'SECRET=nope');
+});
+
+after(() => rmSync(root, { recursive: true, force: true }));
+
+function docsConfig() {
+  return {
+    port: 0,
+    bind: '127.0.0.1',
+    clis: {},
+    docs: {
+      root,
+      deny: ['node_modules', '.env', '*token*', '*secret*', '*.pem', '*.key'],
+      collections: [
+        { name: 'skills', label: 'Skills', lang: 'markdown', patterns: ['groups/*/skills/*/SKILL.md', 'container/skills/*/SKILL.md'] },
+        { name: 'profiles', label: 'Profiles', lang: 'json', patterns: ['groups/*/profile.json'] },
+      ],
+    },
+  };
+}
+
+async function withServer(config, fn) {
+  const server = createApp(config);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try {
+    return await fn(base);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+}
+
+test('/api/docs: lists collections with their files', async () => {
+  await withServer(docsConfig(), async (base) => {
+    const body = await (await fetch(`${base}/api/docs`)).json();
+    const skills = body.collections.find((c) => c.name === 'skills');
+    assert.equal(skills.label, 'Skills');
+    assert.equal(skills.lang, 'markdown');
+    const paths = skills.files.map((f) => f.path);
+    assert.ok(paths.includes('groups/alpha/skills/tagger/SKILL.md'));
+    assert.ok(paths.includes('container/skills/welcome/SKILL.md'));
+    // each file carries a readable label + group
+    const f = skills.files.find((x) => x.path.includes('tagger'));
+    assert.equal(f.group, 'alpha');
+    assert.match(f.label, /tagger/);
+  });
+});
+
+test('/api/doc: returns file content + lang', async () => {
+  await withServer(docsConfig(), async (base) => {
+    const url = `${base}/api/doc?c=skills&p=${encodeURIComponent('groups/alpha/skills/tagger/SKILL.md')}`;
+    const body = await (await fetch(url)).json();
+    assert.equal(body.ok, true);
+    assert.equal(body.lang, 'markdown');
+    assert.match(body.content, /# tagger/);
+  });
+});
+
+test('/api/doc: a denied file is not readable even though it sits under root', async () => {
+  await withServer(docsConfig(), async (base) => {
+    // .env is excluded by the deny-list and not in any collection pattern
+    const coll = docsConfig();
+    coll.docs.collections.push({ name: 'all', label: 'All', lang: 'text', patterns: ['groups/*/*'] });
+    await withServer(coll, async (base2) => {
+      const res = await fetch(`${base2}/api/doc?c=all&p=${encodeURIComponent('groups/alpha/.env')}`);
+      assert.equal(res.status, 404);
+      assert.equal((await res.json()).ok, false);
+    });
+  });
+});
+
+test('/api/doc: path traversal is rejected', async () => {
+  await withServer(docsConfig(), async (base) => {
+    const res = await fetch(`${base}/api/doc?c=skills&p=${encodeURIComponent('../../../../etc/passwd')}`);
+    assert.equal(res.status, 404);
+    assert.equal((await res.json()).ok, false);
+  });
+});
+
+test('/api/doc: unknown collection → 404', async () => {
+  await withServer(docsConfig(), async (base) => {
+    const res = await fetch(`${base}/api/doc?c=nope&p=x`);
+    assert.equal(res.status, 404);
+  });
+});
+
+test('/api/docs: absent docs config → empty collections, no crash', async () => {
+  await withServer({ port: 0, bind: '127.0.0.1', clis: {} }, async (base) => {
+    const body = await (await fetch(`${base}/api/docs`)).json();
+    assert.deepEqual(body.collections, []);
+  });
+});

.claude/skills/add-clidash/add/tools/clidash/test/docs.test.js

@@ -0,0 +1,111 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { globFiles, describeFile, resolveDoc } from '../docs.js';
+
+let root;
+
+before(() => {
+  root = mkdtempSync(join(tmpdir(), 'clidash-docs-'));
+  const w = (rel, body = 'x') => {
+    const abs = join(root, rel);
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(abs, body);
+  };
+  w('groups/alpha/skills/example-skill/SKILL.md', '# example-skill\nbody');
+  w('groups/alpha/skills/tagger/SKILL.md');
+  w('groups/alpha/CLAUDE.md', '# Alpha');
+  w('groups/alpha/CLAUDE.local.md');
+  w('groups/alpha/profile.json', '{"name":"Alpha"}');
+  w('groups/alpha/conversations/2026-06-01.md');
+  w('groups/bravo/skills/tagger/SKILL.md');
+  w('groups/bravo/profile.json');
+  w('container/skills/agent-browser/SKILL.md');
+  w('container/skills/welcome/SKILL.md');
+  // things that must NEVER be served
+  w('groups/alpha/.env', 'SECRET=1');
+  w('groups/alpha/skills/example-skill/node_modules/dep/SKILL.md');
+  w('groups/alpha/notion-token.txt', 'ntn_xxx');
+});
+
+after(() => rmSync(root, { recursive: true, force: true }));
+
+const DENY = ['node_modules', '.env', '*token*', '*secret*', '*.pem', '*.key'];
+
+// --------------------------------------------------------------- globFiles
+
+test('globFiles: matches a nested *-segment pattern', () => {
+  const files = globFiles(root, ['groups/*/skills/*/SKILL.md'], DENY);
+  assert.deepEqual(files, [
+    'groups/alpha/skills/example-skill/SKILL.md',
+    'groups/alpha/skills/tagger/SKILL.md',
+    'groups/bravo/skills/tagger/SKILL.md',
+  ]);
+});
+
+test('globFiles: multiple patterns union, sorted', () => {
+  const files = globFiles(root, ['groups/*/skills/*/SKILL.md', 'container/skills/*/SKILL.md'], DENY);
+  assert.ok(files.includes('container/skills/agent-browser/SKILL.md'));
+  assert.ok(files.includes('groups/alpha/skills/example-skill/SKILL.md'));
+});
+
+test('globFiles: wildcard inside a filename segment', () => {
+  const files = globFiles(root, ['groups/*/CLAUDE*.md'], DENY);
+  assert.deepEqual(files, ['groups/alpha/CLAUDE.local.md', 'groups/alpha/CLAUDE.md']);
+});
+
+test('globFiles: deny list excludes node_modules and secret-ish files', () => {
+  const files = globFiles(root, ['groups/*/skills/*/**', 'groups/*/*'], DENY);
+  assert.ok(!files.some((f) => f.includes('node_modules')));
+  assert.ok(!files.some((f) => f.endsWith('.env')));
+  assert.ok(!files.some((f) => f.includes('token')));
+});
+
+test('globFiles: no match returns empty array', () => {
+  assert.deepEqual(globFiles(root, ['nope/*/x.md'], DENY), []);
+});
+
+// ------------------------------------------------------------- describeFile
+
+test('describeFile: per-group skill → group + readable label', () => {
+  const d = describeFile('groups/alpha/skills/tagger/SKILL.md');
+  assert.equal(d.group, 'alpha');
+  assert.match(d.label, /alpha/);
+  assert.match(d.label, /tagger/);
+});
+
+test('describeFile: container skill → shared', () => {
+  const d = describeFile('container/skills/agent-browser/SKILL.md');
+  assert.equal(d.group, 'shared');
+  assert.match(d.label, /agent-browser/);
+});
+
+// --------------------------------------------------------------- resolveDoc
+
+const SKILLS = { name: 'skills', patterns: ['groups/*/skills/*/SKILL.md', 'container/skills/*/SKILL.md'] };
+
+test('resolveDoc: returns an absolute path for an allowed file', () => {
+  const abs = resolveDoc(root, SKILLS, 'groups/alpha/skills/example-skill/SKILL.md', DENY);
+  assert.ok(abs.endsWith('/groups/alpha/skills/example-skill/SKILL.md'));
+  assert.ok(abs.startsWith(root));
+});
+
+test('resolveDoc: rejects a path not matching the collection patterns', () => {
+  assert.throws(() => resolveDoc(root, SKILLS, 'groups/alpha/profile.json', DENY), /not allowed/i);
+});
+
+test('resolveDoc: rejects path traversal', () => {
+  assert.throws(() => resolveDoc(root, SKILLS, '../../etc/passwd', DENY), /not allowed/i);
+  assert.throws(() => resolveDoc(root, SKILLS, 'groups/alpha/skills/../../../.env', DENY), /not allowed/i);
+});
+
+test('resolveDoc: rejects an absolute path', () => {
+  assert.throws(() => resolveDoc(root, SKILLS, '/etc/passwd', DENY), /not allowed/i);
+});
+
+test('resolveDoc: a denied file is not resolvable even if pattern-shaped', () => {
+  const coll = { name: 'all', patterns: ['groups/*/*'] };
+  assert.throws(() => resolveDoc(root, coll, 'groups/alpha/.env', DENY), /not allowed/i);
+});

.claude/skills/add-clidash/add/tools/clidash/test/fixtures/ncl-help.txt

@@ -0,0 +1,28 @@
+Resources:
+  approvals            Pending approval — in-flight approval cards waiting for an admin response. Created by requestApproval() (self-mod install_packages/add_mcp_server) and OneCLI credential approval flow. Rows are deleted after the admin approves/rejects or the request expires.
+                       verbs: list, get
+  destinations         Agent destination — per-agent routing entry and ACL. Each row authorizes an agent to send messages to a target (channel or another agent) and assigns a local name the agent uses to address it. Names are scoped to the source agent — two agents can have different local names for the same target. Created automatically when wiring channels or when agents create child agents.
+                       verbs: list, add, remove
+  dropped-messages     Dropped message log — tracks messages that were dropped by the router or access gate. Aggregates by (channel_type, platform_id) with a running count. Reasons include: no_agent_wired (no wiring exists), no_agent_engaged (wiring exists but engage rules didn't fire), unknown_sender_strict (sender not recognized, strict policy), unknown_sender_request_approval (sender not recognized, approval requested).
+                       verbs: list
+  groups               Agent group — a logical agent identity. Each group has its own workspace folder (CLAUDE.md, skills, container config), conversation history, and container image. Multiple messaging groups can be wired to one agent group.
+                       verbs: list, get, create, update, delete, restart, config get, config update, config add-mcp-server, config remove-mcp-server, config add-package, config remove-package
+  members              Agent group member — grants an unprivileged user permission to interact with an agent group. Users with admin or owner roles on the group are implicitly members and do not need a separate membership row. Membership is checked by the router when sender_scope is "known".
+                       verbs: list, add, remove
+  messaging-groups     Messaging group — one chat or channel on one platform (a Telegram DM, a Discord channel, a Slack thread root, an email address). Identity is the (channel_type, platform_id) pair, which must be unique.
+                       verbs: list, get, create, update, delete
+  roles                User role — privilege grant. "owner" is always global and has full control. "admin" can be global (agent_group_id null) or scoped to a specific agent group. Admin at a group implies membership. Approval routing prefers admins/owners reachable on the same messaging platform as the request origin (e.g. a Telegram request routes the approval card to an admin on Telegram when possible).
+                       verbs: list, grant, revoke
+  sessions             Session — the runtime unit. Maps one (agent_group, messaging_group, thread) combination to a container with its own inbound.db and outbound.db. Created automatically by the router when a message arrives.
+                       verbs: list, get
+  user-dms             User DM cache — maps (user, channel_type) to the messaging group used for DM delivery. Populated lazily by ensureUserDm() when the host needs to cold-DM a user (approvals, pairing). For direct-addressable channels (Telegram, WhatsApp) the handle IS the DM chat ID. For resolution-required channels (Discord, Slack) the adapter's openDM resolves it.
+                       verbs: list
+  users                User — a messaging-platform identity. Each row is one sender on one channel. A single human may have multiple user rows across channels (no cross-channel linking yet).
+                       verbs: list, get, create, update
+  wirings              Wiring — connects a messaging group to an agent group. Determines which agent handles messages from which chat. The same messaging group can be wired to multiple agents; the same agent can be wired to multiple messaging groups.
+                       verbs: list, get, create, update, delete
+
+Commands:
+  help                 List available resources and commands.
+
+Run `ncl <resource> help` for detailed field information.

.claude/skills/add-clidash/add/tools/clidash/test/fixtures/stub-cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Stub CLI for clidash tests. Impersonates ncl (envelope json) or a
+// jsonlines CLI, with failure/slowness/garbage modes driven by env vars.
+import { readFileSync, appendFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const args = process.argv.slice(2);
+
+if (process.env.STUB_COUNT_FILE) {
+  appendFileSync(process.env.STUB_COUNT_FILE, args.join(' ') + '\n');
+}
+
+const sleepMs = Number(process.env.STUB_SLEEP_MS || 0);
+
+setTimeout(() => {
+  if (process.env.STUB_FAIL) {
+    process.stderr.write('boom: socket down\n');
+    process.exit(2);
+  }
+  if (args[0] === 'help') {
+    process.stdout.write(
+      readFileSync(fileURLToPath(new URL('./ncl-help.txt', import.meta.url)), 'utf8'),
+    );
+    process.exit(0);
+  }
+  if (args[1] === 'help') { // `<resource> help` → raw per-resource help text
+    process.stdout.write(`${args[0]}: help for ${args[0]}\n\nVerbs:\n  list\n  get <id>\n`);
+    process.exit(0);
+  }
+  if (process.env.STUB_RAW) {
+    process.stdout.write(process.env.STUB_RAW + '\n');
+    process.exit(0);
+  }
+  const resource = args[0];
+  // `get`/detail commands → single-object envelope
+  if (args.includes('get') || args.includes('config')) {
+    process.stdout.write(JSON.stringify({
+      id: 'req-1', ok: true,
+      data: { id: `${resource}-detail`, args: args.join(' '), extra: 'field' },
+    }) + '\n');
+    process.exit(0);
+  }
+  if (process.env.STUB_JSONLINES) {
+    process.stdout.write(JSON.stringify({ id: `${resource}-1`, name: 'row one' }) + '\n');
+    process.stdout.write(JSON.stringify({ id: `${resource}-2`, name: 'row two' }) + '\n');
+    process.exit(0);
+  }
+  process.stdout.write(JSON.stringify({
+    id: 'req-1',
+    ok: true,
+    data: [
+      { id: `${resource}-1`, name: 'row one' },
+      { id: `${resource}-2`, name: 'row two' },
+    ],
+  }) + '\n');
+  process.exit(0);
+}, sleepMs);

.claude/skills/add-clidash/add/tools/clidash/test/help.test.js

@@ -0,0 +1,61 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { createApp } from '../server.js';
+
+const STUB = fileURLToPath(new URL('./fixtures/stub-cli.js', import.meta.url));
+
+function cli(extra = {}) {
+  return {
+    bin: process.execPath,
+    discover: { args: [STUB, 'help'], parser: 'ncl-help' },
+    list: [STUB, '{resource}', 'list', '--json'],
+    output: 'json', unwrap: 'data',
+    help: [STUB, '{resource}', 'help'],
+    ...extra,
+  };
+}
+
+async function withServer(clis, fn) {
+  const server = createApp({ port: 0, bind: '127.0.0.1', execTimeoutMs: 2000, clis });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
+}
+
+test('/api/help: returns raw per-resource help text', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    const body = await (await fetch(`${base}/api/help/ncl/sessions`)).json();
+    assert.equal(body.ok, true);
+    assert.match(body.text, /sessions: help for sessions/);
+    assert.match(body.text, /Verbs:/);
+  });
+});
+
+test('/api/help: undiscovered resource → 404', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    assert.equal((await fetch(`${base}/api/help/ncl/evil`)).status, 404);
+  });
+});
+
+test('/api/help: a cli without a help template → 404', async () => {
+  const c = cli(); delete c.help;
+  await withServer({ ncl: c }, async (base) => {
+    assert.equal((await fetch(`${base}/api/help/ncl/sessions`)).status, 404);
+  });
+});
+
+test('/api/help: unknown cli → 404', async () => {
+  await withServer({ ncl: cli() }, async (base) => {
+    assert.equal((await fetch(`${base}/api/help/nope/sessions`)).status, 404);
+  });
+});
+
+test('/api/clis: reports help availability per cli', async () => {
+  const noHelp = cli(); delete noHelp.help;
+  await withServer({ ncl: cli(), docker: noHelp }, async (base) => {
+    const body = await (await fetch(`${base}/api/clis`)).json();
+    assert.equal(body.clis.find((c) => c.name === 'ncl').help, true);
+    assert.equal(body.clis.find((c) => c.name === 'docker').help, false);
+  });
+});

.claude/skills/add-clidash/add/tools/clidash/test/logs.test.js

@@ -0,0 +1,75 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { tailFile } from '../logs.js';
+import { createApp } from '../server.js';
+
+let dir;
+before(() => {
+  dir = mkdtempSync(join(tmpdir(), 'clidash-logs-'));
+  // 10 lines, some with ANSI color codes
+  const lines = Array.from({ length: 10 }, (_, i) =>
+    `[12:00:0${i}] \x1b[32mINFO\x1b[39m line ${i}`);
+  writeFileSync(join(dir, 'app.log'), lines.join('\n') + '\n');
+  writeFileSync(join(dir, 'error.log'), 'boom\n');
+});
+after(() => rmSync(dir, { recursive: true, force: true }));
+
+test('tailFile: returns the last N lines, ANSI stripped, no trailing blank', async () => {
+  const { lines, text } = await tailFile(join(dir, 'app.log'), 3);
+  assert.equal(lines.length, 3);
+  assert.deepEqual(lines, ['[12:00:07] INFO line 7', '[12:00:08] INFO line 8', '[12:00:09] INFO line 9']);
+  assert.ok(!text.includes('\x1b'));
+});
+
+test('tailFile: maxLines larger than file returns all lines', async () => {
+  const { lines } = await tailFile(join(dir, 'app.log'), 100);
+  assert.equal(lines.length, 10);
+});
+
+// ---- server endpoints ----
+
+function cfg() {
+  return {
+    port: 0, bind: '127.0.0.1', clis: {},
+    logs: { dir, tailLines: 5, files: [{ name: 'app.log', label: 'app' }, { name: 'error.log', label: 'errors' }] },
+  };
+}
+async function withServer(config, fn) {
+  const server = createApp(config);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try { return await fn(base); } finally { await new Promise((r) => server.close(r)); }
+}
+
+test('/api/logs: lists the configured log files', async () => {
+  await withServer(cfg(), async (base) => {
+    const body = await (await fetch(`${base}/api/logs`)).json();
+    assert.deepEqual(body.files.map((f) => f.name), ['app.log', 'error.log']);
+  });
+});
+
+test('/api/logs: absent logs config → empty list', async () => {
+  await withServer({ port: 0, bind: '127.0.0.1', clis: {} }, async (base) => {
+    assert.deepEqual((await (await fetch(`${base}/api/logs`)).json()).files, []);
+  });
+});
+
+test('/api/log: returns the tail text + a tail command', async () => {
+  await withServer(cfg(), async (base) => {
+    const body = await (await fetch(`${base}/api/log/app.log`)).json();
+    assert.equal(body.ok, true);
+    assert.match(body.text, /line 9$/);
+    assert.equal(body.text.split('\n').length, 5); // tailLines
+    assert.match(body.command, /tail -n 5 .*app\.log/);
+  });
+});
+
+test('/api/log: a name not in the allowlist is rejected (no traversal)', async () => {
+  await withServer(cfg(), async (base) => {
+    assert.equal((await fetch(`${base}/api/log/${encodeURIComponent('../../etc/passwd')}`)).status, 404);
+    assert.equal((await fetch(`${base}/api/log/secrets.log`)).status, 404);
+  });
+});

.claude/skills/add-clidash/add/tools/clidash/test/md.test.js

@@ -0,0 +1,63 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { escapeHtml, mdToHtml } from '../public/md.js';
+
+// ---- escaping -------------------------------------------------------------
+
+test('escapeHtml: neutralizes all HTML metacharacters', () => {
+  assert.equal(escapeHtml(`<script>"&'`), '&lt;script&gt;&quot;&amp;&#39;');
+});
+
+test('mdToHtml: raw HTML in source is escaped, never passed through', () => {
+  const html = mdToHtml('a <script>alert(1)</script> b');
+  assert.ok(!html.includes('<script>'));
+  assert.ok(html.includes('&lt;script&gt;'));
+});
+
+// ---- the security-sensitive part: links -----------------------------------
+
+test('mdToHtml: link href comes from the URL, label from the text', () => {
+  const html = mdToHtml('see [the docs](https://example.com/x)');
+  assert.match(html, /<a href="https:\/\/example\.com\/x" target="_blank" rel="noopener noreferrer">the docs<\/a>/);
+});
+
+test('mdToHtml: javascript: smuggled in link TEXT stays inert (never an href)', () => {
+  const html = mdToHtml('[javascript:alert(1)](https://safe.com)');
+  // href is the safe URL; the js string is only visible label text
+  assert.match(html, /href="https:\/\/safe\.com"/);
+  assert.ok(!/href="javascript:/i.test(html));
+});
+
+test('mdToHtml: a non-http(s) URL is not turned into a link', () => {
+  // javascript:/data: never match the (https?:...) capture, so the literal
+  // (escaped) markdown is left as-is — no anchor, no executable href.
+  const html = mdToHtml('[click](javascript:alert(1))');
+  assert.ok(!/<a /.test(html));
+  assert.ok(!/href="javascript:/i.test(html));
+});
+
+test('mdToHtml: an attribute-breakout attempt in the URL cannot escape the href', () => {
+  // The double-quote is escaped to &quot; before the regex runs, so it can never
+  // close an attribute. (Here the URL also has a space, so no anchor even forms.)
+  // The security property: no REAL attribute (with a literal quote) is injected.
+  const html = mdToHtml('[x](https://a" onmouseover="alert(1))');
+  assert.ok(!/<a/.test(html), 'malformed link must not produce an anchor');
+  assert.ok(!/onmouseover="/.test(html), 'no real (unescaped-quote) attribute injected');
+});
+
+test('mdToHtml: an escaped quote inside a matched URL stays inside the href, inert', () => {
+  // Even when a URL matches, any " in it is already &quot; (an entity), which
+  // does not terminate an HTML attribute value — so no breakout.
+  const html = mdToHtml('[x](https://a"onmouseover=alert)');
+  assert.ok(!/onmouseover="/.test(html));
+  if (/<a/.test(html)) assert.match(html, /href="https:\/\/a&quot;onmouseover=alert"/);
+});
+
+// ---- basic rendering sanity ----------------------------------------------
+
+test('mdToHtml: headings, code fences, lists render', () => {
+  const html = mdToHtml('# Title\n\n```\ncode\n```\n\n- a\n- b');
+  assert.match(html, /<h1>Title<\/h1>/);
+  assert.match(html, /<pre class="code"><code>code<\/code><\/pre>/);
+  assert.match(html, /<ul><li>a<\/li><li>b<\/li><\/ul>/);
+});

.claude/skills/add-clidash/add/tools/clidash/test/ncl-overview.test.js

@@ -0,0 +1,70 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import overview from '../views/ncl-overview.js';
+
+const minutesAgo = (m) => new Date(Date.now() - m * 60_000).toISOString();
+
+// Shapes mirror real `ncl <resource> list --json` output.
+function makeFixtures({ alphaLastActive, bravoLastActive }) {
+  return {
+    groups: [
+      { id: 'ag-1', name: 'Alpha', folder: 'alpha', created_at: '2026-05-31T11:14:48.793Z' },
+      { id: 'ag-2', name: 'Bravo Team', folder: 'bravo', created_at: '2026-05-31T11:14:48.796Z' },
+      { id: 'ag-3', name: 'Orphan', folder: 'orphan', created_at: '2026-05-31T11:14:48.799Z' },
+    ],
+    sessions: [
+      { id: 'sess-1', agent_group_id: 'ag-1', messaging_group_id: 'mg-1', thread_id: null, status: 'active', container_status: 'stopped', last_active: alphaLastActive, created_at: '2026-05-31T11:14:51.911Z' },
+      { id: 'sess-2', agent_group_id: 'ag-2', messaging_group_id: 'mg-2', thread_id: null, status: 'active', container_status: 'running', last_active: bravoLastActive, created_at: '2026-05-31T11:14:51.973Z' },
+    ],
+    'messaging-groups': [
+      { id: 'mg-1', channel_type: 'telegram', platform_id: 'telegram:1', name: 'Alpha', is_group: 0 },
+      { id: 'mg-2', channel_type: 'telegram', platform_id: 'telegram:2', name: 'Bravo Team', is_group: 0 },
+    ],
+    wirings: [
+      { id: 'mga-1', messaging_group_id: 'mg-1', agent_group_id: 'ag-1', session_mode: 'shared' },
+      { id: 'mga-2', messaging_group_id: 'mg-2', agent_group_id: 'ag-2', session_mode: 'shared' },
+    ],
+  };
+}
+
+function fetchFrom(fixtures) {
+  return async (resource) => {
+    if (!(resource in fixtures)) throw new Error(`unexpected fetch: ${resource}`);
+    return fixtures[resource];
+  };
+}
+
+test('overview: one card per agent group with joined session + wiring data', async () => {
+  const fixtures = makeFixtures({ alphaLastActive: minutesAgo(5), bravoLastActive: minutesAgo(30) });
+  const result = await overview({ fetch: fetchFrom(fixtures) });
+  assert.equal(result.cards.length, 3);
+
+  const alpha = result.cards.find((c) => c.title === 'Alpha');
+  assert.equal(alpha.subtitle, 'alpha');
+  assert.equal(alpha.fields.container, 'stopped');
+  assert.equal(alpha.fields.sessions, 1);
+  assert.deepEqual(alpha.badges, ['telegram: Alpha']);
+
+  const bravo = result.cards.find((c) => c.title === 'Bravo Team');
+  assert.equal(bravo.fields.container, 'running');
+  assert.deepEqual(bravo.badges, ['telegram: Bravo Team']);
+});
+
+test('overview: staleness thresholds — green <15m, amber <2h, red older, gray never', async () => {
+  const fixtures = makeFixtures({ alphaLastActive: minutesAgo(5), bravoLastActive: minutesAgo(30) });
+  const result = await overview({ fetch: fetchFrom(fixtures) });
+  assert.equal(result.cards.find((c) => c.title === 'Alpha').status, 'green');
+  assert.equal(result.cards.find((c) => c.title === 'Bravo Team').status, 'amber');
+  assert.equal(result.cards.find((c) => c.title === 'Orphan').status, 'gray');
+
+  const stale = makeFixtures({ alphaLastActive: minutesAgo(300), bravoLastActive: minutesAgo(30) });
+  const result2 = await overview({ fetch: fetchFrom(stale) });
+  assert.equal(result2.cards.find((c) => c.title === 'Alpha').status, 'red');
+});
+
+test('overview: last_active is exposed for relative-time rendering', async () => {
+  const ts = minutesAgo(5);
+  const fixtures = makeFixtures({ alphaLastActive: ts, bravoLastActive: minutesAgo(30) });
+  const result = await overview({ fetch: fetchFrom(fixtures) });
+  assert.equal(result.cards.find((c) => c.title === 'Alpha').fields['last active'], ts);
+});

.claude/skills/add-clidash/add/tools/clidash/test/parsers.test.js

@@ -0,0 +1,111 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { discoveryParsers, parseOutput, unwrapPath } from '../parsers.js';
+
+const fixture = readFileSync(
+  fileURLToPath(new URL('./fixtures/ncl-help.txt', import.meta.url)),
+  'utf8',
+);
+
+// ---------------------------------------------------------------- ncl-help
+
+test('ncl-help: parses all listable resources from real captured output', () => {
+  const resources = discoveryParsers['ncl-help'](fixture);
+  assert.deepEqual(
+    resources.map((r) => r.name),
+    [
+      'approvals', 'destinations', 'dropped-messages', 'groups', 'members',
+      'messaging-groups', 'roles', 'sessions', 'user-dms', 'users', 'wirings',
+    ],
+  );
+});
+
+test('ncl-help: every parsed resource has a non-empty description and a list verb', () => {
+  const resources = discoveryParsers['ncl-help'](fixture);
+  for (const r of resources) {
+    assert.ok(r.description.length > 0, `${r.name} has empty description`);
+    assert.ok(r.verbs.includes('list'), `${r.name} missing list verb`);
+  }
+});
+
+test('ncl-help: parses verbs correctly, including multi-word verbs', () => {
+  const resources = discoveryParsers['ncl-help'](fixture);
+  const groups = resources.find((r) => r.name === 'groups');
+  assert.deepEqual(groups.verbs, [
+    'list', 'get', 'create', 'update', 'delete', 'restart',
+    'config get', 'config update', 'config add-mcp-server',
+    'config remove-mcp-server', 'config add-package', 'config remove-package',
+  ]);
+});
+
+test('ncl-help: excludes resources without a list verb', () => {
+  const input = [
+    'Resources:',
+    '  alpha                Has list.',
+    '                       verbs: list, get',
+    '  beta                 No list here.',
+    '                       verbs: grant, revoke',
+    '',
+  ].join('\n');
+  const resources = discoveryParsers['ncl-help'](input);
+  assert.deepEqual(resources.map((r) => r.name), ['alpha']);
+});
+
+test('ncl-help: ignores the Commands section (help is not a resource)', () => {
+  const resources = discoveryParsers['ncl-help'](fixture);
+  assert.ok(!resources.some((r) => r.name === 'help'));
+});
+
+test('ncl-help: throws loudly on unrecognized format', () => {
+  assert.throws(() => discoveryParsers['ncl-help']('totally not help output'), /Resources/);
+  assert.throws(() => discoveryParsers['ncl-help'](''), /Resources/);
+});
+
+// ------------------------------------------------------------- parseOutput
+
+test('parseOutput json: parses a single document', () => {
+  assert.deepEqual(parseOutput('{"a": 1}', 'json'), { a: 1 });
+});
+
+test('parseOutput json: throws on malformed input with raw output preserved', () => {
+  assert.throws(() => parseOutput('not json', 'json'), (err) => {
+    assert.match(err.message, /JSON/i);
+    assert.equal(err.raw, 'not json');
+    return true;
+  });
+});
+
+test('parseOutput jsonlines: one object per line, blank lines skipped', () => {
+  const text = '{"id":1}\n\n{"id":2}\n{"id":3}\n';
+  assert.deepEqual(parseOutput(text, 'jsonlines'), [{ id: 1 }, { id: 2 }, { id: 3 }]);
+});
+
+test('parseOutput jsonlines: throws on a malformed line', () => {
+  assert.throws(() => parseOutput('{"ok":1}\ngarbage\n', 'jsonlines'), /line 2/i);
+});
+
+test('parseOutput: rejects unknown format', () => {
+  assert.throws(() => parseOutput('{}', 'xml'), /format/i);
+});
+
+// -------------------------------------------------------------- unwrapPath
+
+test('unwrapPath: extracts the ncl {id, ok, data} envelope', () => {
+  const doc = { id: 'x', ok: true, data: [{ id: 'sess-1' }] };
+  assert.deepEqual(unwrapPath(doc, 'data'), [{ id: 'sess-1' }]);
+});
+
+test('unwrapPath: supports nested dot paths', () => {
+  assert.deepEqual(unwrapPath({ a: { b: [1, 2] } }, 'a.b'), [1, 2]);
+});
+
+test('unwrapPath: throws when the path is missing', () => {
+  assert.throws(() => unwrapPath({ ok: true }, 'data'), /data/);
+});
+
+test('unwrapPath: no path returns the value unchanged', () => {
+  const rows = [{ id: 1 }];
+  assert.equal(unwrapPath(rows, undefined), rows);
+});

.claude/skills/add-clidash/add/tools/clidash/test/server.test.js

@@ -0,0 +1,240 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createApp } from '../server.js';
+
+const STUB = fileURLToPath(new URL('./fixtures/stub-cli.js', import.meta.url));
+const tmp = mkdtempSync(join(tmpdir(), 'clidash-test-'));
+
+function stubCli(extra = {}) {
+  return {
+    bin: process.execPath,
+    discover: { args: [STUB, 'help'], parser: 'ncl-help' },
+    list: [STUB, '{resource}', 'list', '--json'],
+    output: 'json',
+    unwrap: 'data',
+    ...extra,
+  };
+}
+
+function makeConfig(clis, extra = {}) {
+  return { port: 0, bind: '127.0.0.1', execTimeoutMs: 2000, refreshSeconds: 10, clis, ...extra };
+}
+
+async function withServer(config, fn) {
+  const server = createApp(config);
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  try {
+    return await fn(base);
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}
+
+after(() => rmSync(tmp, { recursive: true, force: true }));
+
+// ----------------------------------------------------------------- /api/clis
+
+test('/api/clis: lists configured CLIs with discovered resources', async () => {
+  await withServer(makeConfig({ stub: stubCli() }), async (base) => {
+    const res = await fetch(`${base}/api/clis`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.clis.length, 1);
+    assert.equal(body.clis[0].name, 'stub');
+    assert.equal(body.clis[0].refreshSeconds, 10);
+    const names = body.clis[0].resources.map((r) => r.name);
+    assert.ok(names.includes('sessions'));
+    assert.ok(names.includes('groups'));
+    assert.equal(names.length, 11);
+  });
+});
+
+test('/api/clis: static resource list needs no discovery', async () => {
+  const cli = stubCli({ resources: ['alpha', 'beta'] });
+  delete cli.discover;
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const body = await (await fetch(`${base}/api/clis`)).json();
+    assert.deepEqual(body.clis[0].resources.map((r) => r.name), ['alpha', 'beta']);
+  });
+});
+
+test('/api/clis: discovery failure reports a loud error', async () => {
+  const cli = stubCli();
+  cli.env = { STUB_FAIL: '1' };
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const body = await (await fetch(`${base}/api/clis`)).json();
+    assert.equal(body.clis[0].resources.length, 0);
+    assert.match(body.clis[0].error, /boom/);
+  });
+});
+
+// ------------------------------------------------------------ /api/r/cli/res
+
+test('/api/r: returns unwrapped rows with fetchedAt', async () => {
+  await withServer(makeConfig({ stub: stubCli() }), async (base) => {
+    const res = await fetch(`${base}/api/r/stub/sessions`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.ok, true);
+    assert.deepEqual(body.rows.map((r) => r.id), ['sessions-1', 'sessions-2']);
+    assert.ok(body.fetchedAt);
+  });
+});
+
+test('/api/r: rejects a resource not in the discovered set without exec', async () => {
+  const countFile = join(tmp, 'count-reject.txt');
+  const cli = stubCli();
+  cli.env = { STUB_COUNT_FILE: countFile };
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const res = await fetch(`${base}/api/r/stub/evil%20--rm`);
+    assert.equal(res.status, 404);
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    // only the discovery exec ran — never a list exec for the bogus resource
+    const calls = readFileSync(countFile, 'utf8').trim().split('\n');
+    assert.deepEqual(calls, ['help']);
+  });
+});
+
+test('/api/r: unknown cli → 404', async () => {
+  await withServer(makeConfig({ stub: stubCli() }), async (base) => {
+    const res = await fetch(`${base}/api/r/nope/sessions`);
+    assert.equal(res.status, 404);
+  });
+});
+
+test('/api/r: jsonlines CLI with static resources works', async () => {
+  const cli = {
+    bin: process.execPath,
+    resources: ['ps'],
+    list: [STUB, '{resource}'],
+    output: 'jsonlines',
+    env: { STUB_JSONLINES: '1' },
+  };
+  await withServer(makeConfig({ docker: cli }), async (base) => {
+    const body = await (await fetch(`${base}/api/r/docker/ps`)).json();
+    assert.equal(body.ok, true);
+    assert.deepEqual(body.rows.map((r) => r.id), ['ps-1', 'ps-2']);
+  });
+});
+
+test('/api/r: exec failure returns ok:false with stderr', async () => {
+  const cli = stubCli({ resources: ['sessions'] });
+  delete cli.discover;
+  cli.env = { STUB_FAIL: '1' };
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const res = await fetch(`${base}/api/r/stub/sessions`);
+    assert.equal(res.status, 502);
+    const body = await res.json();
+    assert.equal(body.ok, false);
+    assert.match(body.error, /boom: socket down/);
+  });
+});
+
+test('/api/r: exec timeout returns ok:false naming the resource', async () => {
+  const cli = stubCli({ resources: ['sessions'] });
+  delete cli.discover;
+  cli.env = { STUB_SLEEP_MS: '5000' };
+  await withServer(makeConfig({ stub: cli }, { execTimeoutMs: 200 }), async (base) => {
+    const body = await (await fetch(`${base}/api/r/stub/sessions`)).json();
+    assert.equal(body.ok, false);
+    assert.match(body.error, /sessions/);
+    assert.match(body.error, /timed out/i);
+  });
+});
+
+test('/api/r: malformed CLI output returns the raw output', async () => {
+  const cli = stubCli({ resources: ['sessions'] });
+  delete cli.discover;
+  cli.env = { STUB_RAW: 'this is not json' };
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const body = await (await fetch(`${base}/api/r/stub/sessions`)).json();
+    assert.equal(body.ok, false);
+    assert.match(body.raw, /this is not json/);
+  });
+});
+
+test('/api/r: concurrent requests for the same resource coalesce into one exec', async () => {
+  const countFile = join(tmp, 'count-coalesce.txt');
+  const cli = stubCli({ resources: ['sessions'] });
+  delete cli.discover;
+  cli.env = { STUB_COUNT_FILE: countFile, STUB_SLEEP_MS: '150' };
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const bodies = await Promise.all(
+      Array.from({ length: 5 }, () => fetch(`${base}/api/r/stub/sessions`).then((r) => r.json())),
+    );
+    for (const body of bodies) assert.equal(body.ok, true);
+    const calls = readFileSync(countFile, 'utf8').trim().split('\n');
+    assert.equal(calls.length, 1);
+  });
+});
+
+// ------------------------------------------------------------- /api/view
+
+test('/api/view: runs a view plugin with a bound fetch helper', async () => {
+  const viewsDir = join(tmp, 'views');
+  writeFileSync(join(viewsDir, '..', 'placeholder'), ''); // ensure tmp exists
+  const { mkdirSync } = await import('node:fs');
+  mkdirSync(viewsDir, { recursive: true });
+  writeFileSync(
+    join(viewsDir, 'stub-overview.js'),
+    'export default async function ({ fetch }) {\n' +
+    '  const rows = await fetch("sessions");\n' +
+    '  return { count: rows.length, first: rows[0].id };\n' +
+    '}\n',
+  );
+  await withServer(makeConfig({ stub: stubCli() }, { viewsDir }), async (base) => {
+    const res = await fetch(`${base}/api/view/stub/overview`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.ok, true);
+    assert.deepEqual(body.result, { count: 2, first: 'sessions-1' });
+  });
+});
+
+test('/api/view: missing view → 404; bad view name → 404', async () => {
+  await withServer(makeConfig({ stub: stubCli() }, { viewsDir: join(tmp, 'views') }), async (base) => {
+    assert.equal((await fetch(`${base}/api/view/stub/nope`)).status, 404);
+    assert.equal((await fetch(`${base}/api/view/stub/..%2F..%2Fserver`)).status, 404);
+  });
+});
+
+// ------------------------------------------------------------- static files
+
+test('GET /: serves the dashboard index.html', async () => {
+  await withServer(makeConfig({ stub: stubCli() }), async (base) => {
+    const res = await fetch(`${base}/`);
+    assert.equal(res.status, 200);
+    assert.match(res.headers.get('content-type'), /text\/html/);
+    assert.match(await res.text(), /clidash/i);
+  });
+});
+
+test('static: path traversal outside public/ is rejected', async () => {
+  await withServer(makeConfig({ stub: stubCli() }), async (base) => {
+    const res = await fetch(`${base}/..%2Fserver.js`);
+    assert.notEqual(res.status, 200);
+  });
+});
+
+test('/api/r: {resource} substitutes inside a larger argv string (ssh-remote pattern)', async () => {
+  const cli = {
+    bin: process.execPath,
+    resources: ['sessions'],
+    list: [STUB, 'wrapped-{resource}-arg', 'list'],
+    output: 'json',
+    unwrap: 'data',
+    env: { STUB_COUNT_FILE: join(tmp, 'count-embed.txt') },
+  };
+  await withServer(makeConfig({ stub: cli }), async (base) => {
+    const body = await (await fetch(`${base}/api/r/stub/sessions`)).json();
+    assert.equal(body.ok, true);
+    const calls = readFileSync(join(tmp, 'count-embed.txt'), 'utf8').trim();
+    assert.equal(calls, 'wrapped-sessions-arg list');
+  });
+});

.claude/skills/add-clidash/add/tools/clidash/test/smoke.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Smoke test against a running clidash instance (run on the VM after deploy).
+# Usage: ./test/smoke.sh [base-url]   (default http://127.0.0.1:4690)
+set -euo pipefail
+BASE="${1:-http://127.0.0.1:4690}"
+
+check() {
+  local label="$1" url="$2" pattern="$3"
+  if curl -fsS --max-time 15 "$url" | grep -q "$pattern"; then
+    echo "OK   $label"
+  else
+    echo "FAIL $label ($url did not match $pattern)"
+    exit 1
+  fi
+}
+
+check "/api/clis"             "$BASE/api/clis"             '"resources"'
+check "/api/r/ncl/sessions"   "$BASE/api/r/ncl/sessions"   '"ok":true'
+check "/api/view/ncl/overview" "$BASE/api/view/ncl/overview" '"ok":true'
+check "GET / (static UI)"     "$BASE/"                     'clidash'
+echo "smoke: all good"

.claude/skills/add-clidash/add/tools/clidash/views/ncl-overview.js

@@ -0,0 +1,60 @@
+// Curated "Agents overview" view for ncl: joins groups + sessions +
+// messaging-groups + wirings into per-agent cards. Returns the generic
+// card shape the frontend renders, so the UI itself stays CLI-agnostic:
+//   { title, cards: [{ title, subtitle, status, fields, badges }] }
+// status: green <15m since last_active, amber <2h, red older, gray never.
+
+const GREEN_MAX_MIN = 15;
+const AMBER_MAX_MIN = 120;
+
+function staleness(lastActive) {
+  if (!lastActive) return 'gray';
+  const ageMin = (Date.now() - new Date(lastActive).getTime()) / 60_000;
+  if (ageMin < GREEN_MAX_MIN) return 'green';
+  if (ageMin < AMBER_MAX_MIN) return 'amber';
+  return 'red';
+}
+
+export default async function overview({ fetch }) {
+  const [groups, sessions, messagingGroups, wirings] = await Promise.all([
+    fetch('groups'),
+    fetch('sessions'),
+    fetch('messaging-groups'),
+    fetch('wirings'),
+  ]);
+
+  const mgById = new Map(messagingGroups.map((mg) => [mg.id, mg]));
+
+  const cards = groups.map((group) => {
+    const groupSessions = sessions.filter((s) => s.agent_group_id === group.id);
+    const lastActive = groupSessions
+      .map((s) => s.last_active)
+      .filter(Boolean)
+      .sort()
+      .at(-1) ?? null;
+    const container = groupSessions.some((s) => s.container_status === 'running')
+      ? 'running'
+      : groupSessions[0]?.container_status ?? 'none';
+
+    const badges = wirings
+      .filter((w) => w.agent_group_id === group.id)
+      .map((w) => {
+        const mg = mgById.get(w.messaging_group_id);
+        return mg ? `${mg.channel_type}: ${mg.name ?? mg.platform_id}` : w.messaging_group_id;
+      });
+
+    return {
+      title: group.name,
+      subtitle: group.folder,
+      status: staleness(lastActive),
+      fields: {
+        container,
+        sessions: groupSessions.length,
+        'last active': lastActive,
+      },
+      badges,
+    };
+  });
+
+  return { title: 'Agents overview', cards };
+}

.claude/skills/add-mnemon/SKILL.md

@@ -9,13 +9,13 @@ Installs [mnemon](https://github.com/mnemon-dev/mnemon) in the agent container i
 
 ## Provider Compatibility
 
-mnemon hooks fire only under `--target claude-code`. Use this skill on agent groups that run the default Claude provider (`AGENT_PROVIDER=claude`). Confirm the provider before applying:
+mnemon hooks fire only under `--target claude-code`. Use this skill on agent groups that run the default Claude provider. The provider is the materialized `provider` key in each group's `container.json` (absent or `claude` = default Claude provider). Confirm it before applying:
 
 ```bash
-grep AGENT_PROVIDER .env groups/*/container.json 2>/dev/null
+grep -H '"provider"' groups/*/container.json 2>/dev/null   # no match, or "provider": "claude" = Claude
 ```
 
-If a group uses a different provider (e.g. `AGENT_PROVIDER=opencode`), it spawns its own process and never invokes the `claude` CLI, so the hooks registered by `mnemon setup` do not run for that group.
+If a group sets a different provider (e.g. `"provider": "opencode"`), it spawns its own process and never invokes the `claude` CLI, so the hooks registered by `mnemon setup` do not run for that group.
 
 ## Phase 1: Pre-flight
 

.claude/skills/add-opencode/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: add-opencode
-description: Use OpenCode as an agent provider (AGENT_PROVIDER=opencode). OpenRouter, OpenAI, Google, DeepSeek, etc. via OpenCode config — not the Anthropic Agent SDK. Per-session and per-group via agent_provider; host passes OPENCODE_* and XDG mount when spawning containers.
+description: Use OpenCode as an agent provider. OpenRouter, OpenAI, Google, DeepSeek, etc. via OpenCode config — not the Anthropic Agent SDK. Per group via `ncl groups config update --provider opencode`; host passes OPENCODE_* and XDG mount when spawning containers.
 ---
 
 # OpenCode agent provider
 
-NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `mock`).
+NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected per agent group by the **`provider`** key in that group's `container.json` (materialized from the `container_configs` table) — set it with `ncl groups config update --provider opencode`. Default is `claude`.
 
 Trunk ships with only the `claude` provider baked in. This skill copies the OpenCode provider files in from the `providers` branch, wires them into the host and container barrels, installs dependencies, and rebuilds the image.
 
@@ -148,7 +148,7 @@ done
 
 Set model/provider strings in the form OpenCode expects (often `provider/model-id`). **Put comments on their own lines** — a `#` inside a value is kept verbatim and breaks model IDs.
 
-These variables are read **on the host** and passed into the container only when the effective provider is `opencode`. They do not switch the provider by themselves; the DB still needs `agent_provider` set (below).
+These variables are read **on the host** and passed into the container only when the effective provider is `opencode`. They do not switch the provider by themselves; the group still needs `provider` set to `opencode` (see [Select the provider](#select-the-provider) below).
 
 - `OPENCODE_PROVIDER` — OpenCode provider id, e.g. `openrouter`, `anthropic`, `deepseek`.
 - `OPENCODE_MODEL` — full model id in `provider/model` form, e.g. `deepseek/deepseek-chat`.
@@ -215,7 +215,7 @@ OPENCODE_SMALL_MODEL=anthropic/claude-haiku-4-5-20251001
 
 Zen's HTTP API (e.g. `POST …/zen/v1/messages`) expects the key in the **`x-api-key`** header. If OneCLI injects **`Authorization: Bearer …`** only, Zen often returns **401 / "Missing API key"** even though the gateway is working.
 
-**Naming:** NanoClaw **`AGENT_PROVIDER=opencode`** (DB `agent_provider`) means "run the **OpenCode agent provider**." Separately, **`OPENCODE_PROVIDER=opencode`** in `.env` is OpenCode's **Zen provider id** inside the OpenCode config (see [Zen docs](https://opencode.ai/docs/zen/)).
+**Naming:** NanoClaw's **`provider: opencode`** (the `container.json` key, set via `ncl groups config update --provider opencode`) means "run the **OpenCode agent provider**." Separately, **`OPENCODE_PROVIDER=opencode`** in `.env` is OpenCode's **Zen provider id** inside the OpenCode config (see [Zen docs](https://opencode.ai/docs/zen/)).
 
 **Host `.env` (typical Zen shape):**
 
@@ -236,9 +236,16 @@ onecli secrets create --name "OpenCode Zen" --type generic \
   --header-name "x-api-key" --value-format "{value}"
 ```
 
-### Per group / per session
+### Select the provider
 
-Set `"provider": "opencode"` in the group's **`container.json`** (`groups/<folder>/container.json`) — the in-container runner reads `provider` from there, not from the DB. The DB columns **`agent_groups.agent_provider`** and **`sessions.agent_provider`** (session overrides group) only drive host-side provider contribution — per-session XDG mount, `OPENCODE_*` env passthrough — and do not propagate into `container.json` at spawn time. Set both, or just edit `container.json`; if they disagree, the runner uses `container.json` and the host-side resolver falls back through session → group → `container.json` → `'claude'`.
+Per group, from the host:
+
+```bash
+ncl groups config update --id <group-id> --provider opencode
+ncl groups restart --id <group-id>
+```
+
+`ncl groups config update --provider` writes the `provider` value into the `container_configs` table; the host materializes it into `groups/<folder>/container.json` at spawn time and the in-container runner reads `provider` from there (defaulting to `claude`). The restart picks up the change. Switching is an operator action — run it from the host. Memory does NOT carry over automatically between providers — run `/migrate-memory` to carry it across.
 
 Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config.mcpServers` on the host; the runner merges them into the same `mcpServers` object passed to **both** Claude and OpenCode providers.
 
@@ -250,6 +257,6 @@ Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config
 
 ## Next Steps
 
-The registration and Dockerfile guards in step 7 verify the wiring. To confirm an end-to-end round-trip, set `agent_provider = 'opencode'` (or `"provider": "opencode"` in the group's `container.json`) on a test group, register the matching provider key in OneCLI, and send a message. A clean exchange returns the model's reply with no `Unknown provider: opencode` error and no UUID/session warnings in the logs.
+The registration and Dockerfile guards in step 7 verify the wiring. To confirm an end-to-end round-trip, switch a test group with `ncl groups config update --id <group-id> --provider opencode && ncl groups restart --id <group-id>`, register the matching provider key in OneCLI, and send a message. A clean exchange returns the model's reply with no `Unknown provider: opencode` error and no UUID/session warnings in the logs.
 
 To remove this provider, see [REMOVE.md](REMOVE.md).

.claude/skills/debug/SKILL.md

@@ -206,29 +206,6 @@ ncl groups restart --id <group-id> --message "on_wake test"
 
 Without `--message`, the container comes back on the next user message. From inside a container, `--id` is auto-filled and only the calling session restarts.
 
-## Runaway task
-
-A scheduled task (cron) that keeps firing is a `messages_in` row with `kind='task'` in a session's `inbound.db`. When an agent won't stop one — or you'd rather not ask the misbehaving agent — use the `ncl tasks` operator surface to inspect and stop it directly from the host:
-
-```bash
-# List every pending/paused task across all groups (one row per series).
-ncl tasks list
-
-# Scope to a single agent group.
-ncl tasks list --group <group-id>
-
-# Inspect one task by id or series id.
-ncl tasks get --id <task-id>
-
-# Stop it. cancel/pause/resume match by id OR series id, so a recurring
-# task's live next occurrence is caught, not just the row you looked up.
-ncl tasks cancel --id <task-id>
-ncl tasks pause  --id <task-id>
-ncl tasks resume --id <task-id>
-```
-
-The host is the legitimate writer of `inbound.db`, so these apply straight to the session DB without waking the container. `cancel` marks the series completed, `pause` holds a pending task, `resume` re-arms a paused one.
-
 ## Manual Container Probes
 
 The container's entry point is `exec bun run /app/src/index.ts`; it talks only to the mounted session DBs, so there is no JSON to pipe in. To probe the image directly:
@@ -281,14 +258,13 @@ docker builder prune -af
 
 ## Clearing a Session
 
-Conversation continuity lives in the container-owned `session_state` table in `outbound.db` (the provider's session/continuation id). The agent's `/clear` clears it. To reset a session from the host, just remove the session folder — it self-heals: the host re-creates the folder and re-initializes both DBs on the next inbound message, so you leave the central `sessions` row in place and don't need to restart the host.
+Conversation continuity lives in the container-owned `session_state` table in `outbound.db` (the provider's session/continuation id). The agent's `/clear` clears it. To reset a session from the host, remove the session folder so a fresh one is provisioned on the next message:
 
 ```bash
 # Inspect first
 ncl sessions get <session-id>
 
-# Remove a single session's folder — the host re-provisions it (both DBs)
-# on the next message. No row deletion or host restart needed.
+# Remove a single session's folder (host re-provisions both DBs on next message)
 rm -rf data/v2-sessions/<group>/<session>/
 ```
 

.claude/skills/manage-mounts/SKILL.md

@@ -13,18 +13,18 @@ Configure which host directories NanoClaw agent containers can access. The mount
 cat ~/.config/nanoclaw/mount-allowlist.json 2>/dev/null || echo "No mount allowlist configured"
 ```
 
-Show the current config to the user in a readable format: which directories are allowed, whether non-main agents are read-only.
+Show the current config to the user in a readable format: which directories are allowed, and whether each is read-only or read-write.
 
 ## Add Directories
 
 Ask which directories the user wants agents to access. For each path:
 - Validate the path exists
-- Ask if it should be read-only for non-main agents (default: yes)
+- Ask if it should be read-write (`allowReadWrite: true`) or read-only (`allowReadWrite: false`, the safer default)
 
 Build the JSON config and write it:
 
 ```bash
-pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[{"path":"/path/to/dir","readOnly":false}],"blockedPatterns":[],"nonMainReadOnly":true}'
+pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[{"path":"/path/to/dir","allowReadWrite":true}],"blockedPatterns":[]}'
 ```
 
 Use `--force` to overwrite the existing config.
@@ -34,7 +34,7 @@ Use `--force` to overwrite the existing config.
 Read the current config, show it, ask which entry to remove, then write the updated config through the same write path (build the trimmed JSON and pass it to `--step mounts --force -- --json`):
 
 ```bash
-pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[],"blockedPatterns":[],"nonMainReadOnly":true}'
+pnpm exec tsx setup/index.ts --step mounts --force -- --json '{"allowedRoots":[],"blockedPatterns":[]}'
 ```
 
 ## Reset to Empty
@@ -45,12 +45,10 @@ pnpm exec tsx setup/index.ts --step mounts --force -- --empty
 
 ## After Changes
 
-Restart the service so containers pick up the new config (the unit/label names are per-install — see `setup/lib/install-slug.sh`).
+The allowlist is read fresh when a container is spawned, so new mounts apply to newly spawned containers automatically — no service restart needed.
 
-Run from your NanoClaw project root:
+To apply the new config to a group that already has a running container, restart just that group:
 
 ```bash
-source setup/lib/install-slug.sh
-launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
-systemctl --user restart $(systemd_unit)              # Linux
+ncl groups restart --id <group-id>
 ```

.github/workflows/label-pr.yml

@@ -14,6 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
+      issues: write # createLabel — auto-provisions the core-team label
     steps:
       - uses: actions/github-script@v7
         with:
@@ -30,6 +31,24 @@ jobs:
 
             if (body.includes('contributing-guide: v1')) labels.push('follows-guidelines');
 
+            // Lowercase GitHub logins; keep in sync with the core team roster.
+            const CORE_TEAM = ['gavrielc', 'koshkoshinsk', 'glifocat', 'gabi-simons', 'omri-maya', 'amit-shafnir', 'moshe-nanoco'];
+            const author = context.payload.pull_request.user.login.toLowerCase();
+            if (CORE_TEAM.includes(author)) {
+              labels.push('core-team');
+              try {
+                await github.rest.issues.createLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name: 'core-team',
+                  color: '1D76DB',
+                  description: 'PR opened by a core team member',
+                });
+              } catch (e) {
+                if (e.status !== 422) throw e; // 422: label already exists
+              }
+            }
+
             if (labels.length > 0) {
               await github.rest.issues.addLabels({
                 owner: context.repo.owner,

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to NanoClaw will be documented in this file.
 
 ## [Unreleased]
 
+- **New skill: `/add-audit` — opt-in local audit log for the `ncl` surface.** Installs an append-only, SIEM-shaped audit log: every command through the dispatcher (both transports — host socket and container — including scope denials, approval holds, and approved replays) becomes one canonical NDJSON event under `data/audit/<UTC-day>.ndjson`. Gated chains share a `correlation_id` (the approval id: the hold's `pending` event and the replay's terminal event carry the same one); `details` pass a recursive secret-key redactor (~2 KB value cap). `AUDIT_RETENTION_DAYS` (default 90; `0` = keep forever) hard-deletes day-files past the horizon at boot and once per UTC day. Read back with `ncl audit list [--actor --action --resource --outcome --since --until --correlation --limit] [--format ndjson]` — host + global-scope callers only (the resource stays off the group-scope allowlist, so group-scoped agents fail closed). In-process exporters plug in via `registerAuditHook` — post-write hooks that fire only after the local append succeeds. Off by default: nothing is persisted (and `data/audit/` is never created) until `AUDIT_ENABLED=true`, an enabled box refuses to boot if the directory isn't writable, and a disabled box answers `ncl audit list` with a clear error instead of an empty list. The skill's whole core footprint is the dispatch composition (`export const dispatch = withAudit(dispatchInner)`) plus the resource-barrel import, both guarded by a shipped wiring test. Approval-lifecycle events (request/decision as their own events), OneCLI credential holds, and channel/sender events are later increments on the same schema.
+- **The guard seam (guarded-actions phase 2).** Every privileged action crossing the container or channel boundary now passes ONE decision function — `guard()` in the new `src/guard/` leaf — before it executes: `allow`, `hold` (through the flow's existing approval mechanics), or `deny`. The four handler registries (ncl commands, delivery actions, response handlers, message interceptors) wrap their handlers at registration, so the guarded path is the only path by construction, and a registry-walking conformance test fails CI on any unmapped mutating entry. The structural baseline is today's checks verbatim (cli_scope enforcement, create_agent's scope branch, a2a destination ACL + `agent_message_policies` hold, self-mod unconditional hold, unknown_sender_policy, channel-registration click auth, host-as-trusted-caller in code). Policy-as-data (tighten-only rule sources composing with the baseline) is deferred to phase 3, where the generalized rules table arrives with its first operator-visible consumer. Approved replays now carry the verified approval row as a **grant** — the `approved: true` boolean is deleted — and the guard re-runs the structural baseline on every replay. Three outcome changes are inherent to that replay semantics and ship deliberately: **(a)** approving a held a2a message after its destination was revoked no longer delivers it (the live baseline re-check); **(b)** a forged, already-consumed, or wrong-action/wrong-payload grant refuses the replay instead of executing (previously any in-process caller passing `approved: true` executed); **(c)** the channel-registration free-text name reply re-checks approver eligibility at reply time — a privilege revoked between the click and the reply, or a registration that vanished meanwhile, now refuses instead of acting. Zero rules ship by default — the seeded posture is today's behavior. (The D1/D2/D4 click-auth fixes from the guarded-actions defect inventory are NOT in this change — they belong to the approval-contract PR.)
+- **Guard conformance is now a boot invariant, not just a CI test.** The host refuses to start (upgrade-tripwire posture: clear banner + exit 1) if any privileged command or delivery action is registered without a guard-catalog mapping. CI can't see skill-installed code — `/add-*` skills register handlers on machines where the test suite never runs — so the same registry walk the conformance test uses (`src/guard-conformance.ts`, one shared exemption list) now runs in `main()` before the host accepts a message, and a bad registration crashes at skill-install time instead of running unguarded. Companion hardening: re-registering a guard-wrapped delivery action *without* a guard spec now throws at registration — previously that silently replaced the guarded handler while the catalog still reported the action as guarded.
 - **Optional per-container resource caps.** `CONTAINER_CPU_LIMIT` and `CONTAINER_MEMORY_LIMIT` pass through to `docker run` as `--cpus` / `--memory` (`container-runner.ts`). Both empty by default — no flag added, spawn args byte-identical to today — so existing installs are unaffected. Set them to cap an agent container's CPU/memory so one agent can't monopolize the host (e.g. `CONTAINER_CPU_LIMIT=2`, `CONTAINER_MEMORY_LIMIT=8g`). Swap is intentionally not managed here: `--memory` is a hard cap on a swapless host.
 - [BREAKING] **Chat SDK pinned to `4.29.0` (was `4.26.0` via `^4.24.0`).** `chat` and the `@chat-adapter/*` channel adapters are version-locked — the adapter's `ChatInstance` must match the bridge's, so a mismatched pair fails to typecheck at `createChatSdkBridge(...)`. `chat` is therefore pinned exactly, and the channel-adapter install pins move with it — the `/add-<channel>` SKILL.md steps and `setup/*.sh` scripts on `main`, plus the adapter code on the `channels` branch. Core installs with no channel (only `cli`) are unaffected. **Migration:** if any channel is installed (Slack, Discord, Telegram, Teams, …), re-run its `/add-<channel>` skill to pull the matching `4.29.0` adapter.
 - **Budget/billing-exhausted LLM turns now reach the user instead of being silently dropped.** When a turn ends in a non-retryable provider error (e.g. an Anthropic `403 billing_error`) with no `<message>` wrapping, the agent-runner delivers the provider's notice to the originating channel and stops re-nudging the failing gateway. `providers/claude.ts` now surfaces the SDK's `is_error` flag (and the error subtype's `errors[]` text); `poll-loop.ts` delivers that text and skips the re-wrap retry. Fixes the case where a spend-limit notice produced silence plus a turn-after-turn retry loop.

CLAUDE.md

@@ -15,11 +15,11 @@ If you are a fresh install (you ran `git clone`, not `git pull`) and there are n
 
 # NanoClaw
 
-Personal Claude assistant. See [README.md](README.md) for philosophy and setup. Architecture lives in `docs/`.
+Personal AI assistant. See [README.md](README.md) for philosophy and setup. Architecture lives in `docs/`.
 
 ## Quick Context
 
-The host is a single Node process that orchestrates per-session agent containers. Platform messages land via channel adapters, route through an entity model (users → messaging groups → agent groups → sessions), get written into the session's inbound DB, and wake a container. The agent-runner inside the container polls the DB, calls Claude, and writes back to the outbound DB. The host polls the outbound DB and delivers through the same adapter.
+The host is a single Node process that orchestrates per-session agent containers. Platform messages land via channel adapters, route through an entity model (users → messaging groups → agent groups → sessions), get written into the session's inbound DB, and wake a container. The agent-runner inside the container polls the DB, calls the agent, and writes back to the outbound DB. The host polls the outbound DB and delivers through the same adapter.
 
 **Everything is a message.** There is no IPC, no file watcher, no stdin piping between host and container. The two session DBs are the sole IO surface.
 
@@ -32,7 +32,7 @@ agent_group_members (user_id, agent_group_id)    — unprivileged access gate
 user_dms (user_id, channel_type, messaging_group_id) — cold-DM cache
 
 agent_groups (workspace, memory, CLAUDE.md, personality, container config)
-    ↕ many-to-many via messaging_group_agents (session_mode, trigger_rules, priority)
+    ↕ many-to-many via messaging_group_agents (session_mode, engage_mode/engage_pattern, sender_scope, priority)
 messaging_groups (one chat/channel on one platform; instance = adapter-instance name, defaults to channel_type; unknown_sender_policy)
 
 sessions (agent_group_id + messaging_group_id + thread_id → per-session container)
@@ -44,8 +44,8 @@ Privilege is user-level (owner/admin), not agent-group-level. See [docs/isolatio
 
 Each session has **two** SQLite files under `data/v2-sessions/<session_id>/`:
 
-- `inbound.db` — host writes, container reads. `messages_in`, routing, destinations, pending_questions, processing_ack.
-- `outbound.db` — container writes, host reads. `messages_out`, session_state.
+- `inbound.db` — host writes, container reads. `messages_in`, delivered, destinations, session_routing.
+- `outbound.db` — container writes, host reads. `messages_out`, processing_ack, session_state, container_state.
 
 Exactly one writer per file — no cross-mount lock contention. Heartbeat is a file touch at `/workspace/.heartbeat`, not a DB update. Host uses even `seq` numbers, container uses odd.
 
@@ -65,13 +65,14 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
 | `src/host-sweep.ts` | 60s sweep: `processing_ack` sync, stale detection, due-message wake, recurrence |
 | `src/session-manager.ts` | Resolves sessions; opens `inbound.db` / `outbound.db`; manages heartbeat path |
 | `src/container-runner.ts` | Spawns per-agent-group Docker containers with session DB + outbox mounts, OneCLI `ensureAgent` |
-| `src/container-runtime.ts` | Runtime selection (Docker vs Apple containers), orphan cleanup |
+| `src/container-runtime.ts` | Docker CLI wrapper (runtime binary, host-gateway args, mount args), orphan cleanup |
+| `src/guard/` | Privileged-action decision seam: `guard(action, input)` → allow \| hold \| deny. Domain-free leaf; domain baselines are `defineGuardedAction` values exported from module-edge `guard.ts` adapters (cli, agent-to-agent, self-mod, permissions) — consults hold the value, so a missing/typo'd wiring is a compile error, never a fail-open. All four handler registries require a guard spec or an explicit `unguarded(<reason>)` declaration at the registration site. Approved replays carry the approval row as a grant and re-check the structural baseline. Boot check = grant continuations only (`src/guard-conformance.ts`); Policy-as-data is deferred to guarded-actions phase 3. Conformance test: `src/guard/conformance.test.ts` |
 | `src/modules/permissions/access.ts` | `canAccessAgentGroup` — owner / global admin / scoped admin / member resolution against `user_roles` + `agent_group_members` |
 | `src/modules/approvals/primitive.ts` | `pickApprover`, `pickApprovalDelivery`, `requestApproval`, approval-handler registry |
 | `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/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills, agent-runner-src overlay) |
+| `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/container-restart.ts` | Kill + on-wake respawn for agent group containers |
@@ -79,8 +80,8 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
 | `src/channels/` | Channel adapter infra (registry, Chat SDK bridge); specific channel adapters are skill-installed from the `channels` branch |
 | `src/providers/` | Host-side provider container-config (`claude` baked in; `opencode` etc. installed from the `providers` branch) |
 | `container/agent-runner/src/` | Agent-runner: poll loop, formatter, provider abstraction, MCP tools, destinations |
-| `container/skills/` | Container skills mounted into every agent session (`onecli-gateway`, `welcome`, `self-customize`, `agent-browser`, `slack-formatting`) |
-| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills, per-group `agent-runner-src/` overlay) |
+| `container/skills/` | Container skills mounted into every agent session (`agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `slack-formatting`, `vercel-cli`, `welcome`, `whatsapp-formatting`) |
+| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills) — agent-runner source is a shared read-only mount, not copied per group |
 | `scripts/init-first-agent.ts` | Bootstrap the first DM-wired agent (used by `/init-first-agent` skill) |
 | `migrate-v2.sh` + `setup/migrate-v2/` | v1→v2 migration. Standalone script: `bash migrate-v2.sh`. Seeds DB, copies groups/sessions, installs channels, builds container, offers service switchover, then hands off to `/migrate-from-v1` skill for owner setup and CLAUDE.md cleanup. See [docs/migration-dev.md](docs/migration-dev.md). |
 | `nanoclaw.sh --uninstall` + `setup/uninstall/` | Uninstall this copy only (slug-scoped): service, containers + image, `data/`, `logs/`, `groups/`, this copy's OneCLI agents. Confirms per group; `--dry-run` previews, `--yes` skips prompts. Other copies and the shared OneCLI app are untouched. Bypasses bootstrap entirely; `uninstall.sh` is a pointer that execs it. |
@@ -105,7 +106,6 @@ ncl help
 | members | list, add, remove | Unprivileged access gate for an agent group |
 | destinations | list, add, remove | Where an agent group can send messages |
 | sessions | list, get | Active sessions (read-only) |
-| tasks | list, get, cancel, pause, resume | Scheduled tasks (cron jobs) in a group's sessions — operator surface to stop a runaway task |
 | user-dms | list | Cold-DM cache (read-only) |
 | dropped-messages | list | Messages from unregistered senders (read-only) |
 | approvals | list, get | Pending approval requests (read-only) |
@@ -116,7 +116,7 @@ Key files: `src/cli/dispatch.ts` (dispatcher + approval handler), `src/cli/crud.
 
 Trunk does not ship any specific channel adapter or non-default agent provider. The codebase is the registry/infra; the actual adapters and providers live on long-lived sibling branches and get copied in by skills:
 
-- **`channels` branch** — Discord, Slack, Telegram, WhatsApp, Teams, Linear, GitHub, iMessage, Webex, Resend, Matrix, Google Chat, WhatsApp Cloud (+ helpers, tests, channel-specific setup steps). Installed via `/add-<channel>` skills.
+- **`channels` branch** — Discord, Slack, Telegram, WhatsApp, Teams, Linear, GitHub, iMessage, Webex, Resend, Matrix, Google Chat, WhatsApp Cloud, Signal, WeChat, DeltaChat, Emacs (+ helpers, tests, channel-specific setup steps). Installed via `/add-<channel>` skills.
 - **`providers` branch** — OpenCode (and any future non-default agent providers). Installed via `/add-opencode`.
 
 Each `/add-<name>` skill is idempotent: `git fetch origin <branch>` → copy module(s) into the standard paths → append a self-registration import to the relevant barrel → `pnpm install <pkg>@<pinned-version>` → build.
@@ -171,7 +171,7 @@ No container restart needed — the gateway looks up secrets per request.
 
 Approval-gating credentialed actions is a **two-sided** flow:
 
-- **Server-side** (OneCLI gateway): decides *when* to hold a request and emit a pending approval. As of `onecli@1.3.0`, the CLI does **not** expose this — `rules create --action` only accepts `block` or `rate_limit`, and `secrets create` has no approval flag. Approval policies must be configured via the OneCLI web UI at `http://127.0.0.1:10254`. If/when the CLI grows an `approve` action, this section needs updating.
+- **Server-side** (OneCLI gateway): decides *when* to hold a request and emit a pending approval. As of `onecli@2.2.5`, the CLI does **not** expose this — `rules create --action` only accepts `block` or `rate_limit`, and `secrets create` has no approval flag. Approval policies must be configured via the OneCLI web UI at `http://127.0.0.1:10254`. If/when the CLI grows an `approve` action, this section needs updating.
 - **Host-side** (nanoclaw): receives pending approvals and routes them to a human. `src/modules/approvals/onecli-approvals.ts` registers a callback via `onecli.configureManualApproval(cb)` (long-polls `GET /api/approvals/pending`). The callback uses `pickApprover` + `pickApprovalDelivery` from `src/modules/approvals/primitive.ts` to DM an approver. Approvers are resolved from the `user_roles` table — preference order: scoped admins for the agent group → global admins → owners. There is no env var like `NANOCLAW_ADMIN_USER_IDS`; roles are persisted in the central DB only.
 
 If approvals are configured server-side but the host callback isn't running (or throws), every credentialed call hangs until the gateway times out. Conversely, if the gateway has no rule asking for approval, the host callback never fires regardless of how it's wired.
@@ -183,7 +183,7 @@ Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxono
 - **Channel/provider install skills** — copy the relevant module(s) in from the `channels` or `providers` branch, wire imports, install pinned deps (e.g. `/add-discord`, `/add-slack`, `/add-whatsapp`, `/add-opencode`).
 - **Utility skills** — ship code files alongside `SKILL.md` (e.g. a `scripts/` CLI or helper).
 - **Operational skills** — instruction-only workflows (`/setup`, `/debug`, `/customize`, `/init-first-agent`, `/manage-channels`, `/init-onecli`, `/update-nanoclaw`).
-- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `onecli-gateway`, `welcome`, `self-customize`, `agent-browser`, `slack-formatting`).
+- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `agent-browser`, `frontend-engineer`, `onecli-gateway`, `self-customize`, `slack-formatting`, `vercel-cli`, `welcome`, `whatsapp-formatting`).
 
 | Skill | When to Use |
 |-------|-------------|
@@ -217,7 +217,7 @@ Run commands directly — don't tell the user to run them.
 
 ```bash
 # Host (Node + pnpm)
-pnpm run dev          # Host with hot reload
+pnpm run dev          # Host via tsx (no watch)
 pnpm run build        # Compile host TypeScript (src/)
 ./container/build.sh  # Rebuild agent container image (nanoclaw-agent:latest)
 pnpm test             # Host tests (vitest)
@@ -298,7 +298,7 @@ The agent container runs on **Bun**; the host runs on **Node** (pnpm). They comm
 - **Writing a new named-param SQL insert/update in the container** → use `$name` in both SQL and JS keys: `.run({ $id: msg.id })`. `bun:sqlite` does not auto-strip the prefix the way `better-sqlite3` does on the host. Positional `?` params work normally.
 - **Adding a test in `container/agent-runner/src/`** → import from `bun:test`, not `vitest`. Vitest runs on Node and can't load `bun:sqlite`. `vitest.config.ts` excludes this tree.
 - **Adding a Node CLI the agent invokes at runtime** (like `agent-browser`, `claude-code`, `vercel`) → put it in the Dockerfile's pnpm global-install block, pinned to an exact version via a new `ARG`. Don't use `bun install -g` — that bypasses the pnpm supply-chain policy.
-- **Changing the Dockerfile entrypoint or the dynamic-spawn command** (`src/container-runner.ts` line ~301) → keep `exec bun ...` so signals forward cleanly. The image has no `/app/dist`; don't reintroduce a tsc build step.
+- **Changing the Dockerfile entrypoint or the dynamic-spawn command** (`src/container-runner.ts` line ~503) → keep `exec bun ...` so signals forward cleanly. The image has no `/app/dist`; don't reintroduce a tsc build step.
 - **Changing session-DB pragmas** (`container/agent-runner/src/db/connection.ts`) → `journal_mode=DELETE` is load-bearing for cross-mount visibility. Read the comment block at the top of the file first.
 
 ## CJK font support

CONTRIBUTING.md

@@ -75,7 +75,7 @@ Standalone tools that ship code files alongside the SKILL.md. The SKILL.md tells
 
 #### 3. Operational skills (instruction-only)
 
-Workflows and guides with no code changes. The SKILL.md is the entire skill — Claude follows the instructions to perform a task.
+Workflows and guides with no code changes. The SKILL.md is the entire skill — the coding agent follows the instructions to perform a task.
 
 **Location:** `.claude/skills/` on `main`
 
@@ -88,13 +88,13 @@ Workflows and guides with no code changes. The SKILL.md is the entire skill —
 
 #### 4. Container skills (agent runtime)
 
-Skills that run inside the agent container, not on the host. These teach the container agent how to use tools, format output, or perform tasks. They are synced into each group's `.claude/skills/` directory when a container starts.
+Skills that run inside the agent container, not on the host. These teach the NanoClaw agent how to use tools, format output, or perform tasks. They are synced into each group's `.claude/skills/` directory when a container starts.
 
 **Location:** `container/skills/<name>/`
 
-**Examples:** `agent-browser` (web browsing), `capabilities` (/capabilities command), `status` (/status command), `slack-formatting` (Slack mrkdwn syntax)
+**Examples:** `agent-browser` (web browsing), `frontend-engineer`, `onecli-gateway` (OneCLI proxy usage), `self-customize`, `slack-formatting` (Slack mrkdwn syntax), `vercel-cli`, `welcome`, `whatsapp-formatting`
 
-**Key difference:** These are NOT invoked by the user on the host. They're loaded by Claude Code inside the container and influence how the agent behaves.
+**Key difference:** You never invoke these from a coding-agent session on the host, the way you run `/setup` or `/update-nanoclaw` in Claude Code/Codex/OpenCode. They're mounted into the sandbox and loaded by the NanoClaw agent itself, shaping how it behaves when you chat with it.
 
 **Guidelines:**
 - Follow the same SKILL.md + frontmatter format

README.md

@@ -22,7 +22,7 @@
 
 [OpenClaw](https://github.com/openclaw/openclaw) is an impressive project, but I wouldn't have been able to sleep if I had given complex software I didn't understand full access to my life. OpenClaw has nearly half a million lines of code, 53 config files, and 70+ dependencies. Its security is at the application level (allowlists, pairing codes) rather than true OS-level isolation. Everything runs in one Node process with shared memory.
 
-NanoClaw provides that same core functionality, but in a codebase small enough to understand: one process and a handful of files. Claude agents run in their own Linux containers with filesystem isolation, not merely behind permission checks.
+NanoClaw provides that same core functionality, but in a codebase small enough to understand: one process and a handful of files. Agents run in their own Linux containers with filesystem isolation, not merely behind permission checks.
 
 ## Quick Start
 
@@ -49,7 +49,7 @@ bash migrate-v2.sh
 
 Run the script directly, not from inside a Claude session — the deterministic side needs interactive prompts and real shell I/O for Node/pnpm bootstrap, Docker, OneCLI, and the container build.
 
-**What it does:** merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders + session data + scheduled tasks, installs the channel adapters you select, copies channel auth state (including Baileys keystore + LID mappings for WhatsApp), builds the agent container.
+**What it does:** merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders + session data + scheduled tasks, installs the channel adapters you select, copies channel auth state (including the Baileys keystore for WhatsApp — LID mapping is now resolved per-message by the Baileys v7 adapter, not migrated), builds the agent container.
 
 **What it doesn't:** flip the system service. Pick *"switch to v2"* at the prompt, or do it manually after testing — your v1 install is left untouched.
 
@@ -78,11 +78,11 @@ See [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md) for what's different an
 - **Multi-channel messaging** — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email via Resend. Installed on demand with `/add-<channel>` skills. Run one or many at the same time.
 - **Flexible isolation** — connect each channel to its own agent for full privacy, share one agent across many channels for unified memory with separate conversations, or fold multiple channels into a single shared session so one conversation spans many surfaces. Pick per channel via `/manage-channels`. See [docs/isolation-model.md](docs/isolation-model.md).
 - **Per-agent workspace** — each agent group has its own `CLAUDE.md`, its own memory, its own container, and only the mounts you allow. Nothing crosses the boundary unless you wire it to.
-- **Scheduled tasks** — recurring jobs that run Claude and can message you back
+- **Scheduled tasks** — recurring jobs executed by the agent, which can message you the results
 - **Web access** — search and fetch content from the web
-- **Container isolation** — agents are sandboxed in Docker (macOS/Linux/WSL2), with optional [Docker Sandboxes](docs/docker-sandboxes.md) micro-VM isolation or Apple Container as a macOS-native opt-in
+- **Container isolation** — agents are sandboxed in Docker containers (macOS/Linux/WSL2)
 - **Credential security** — agents never hold raw API keys. Outbound requests route through [OneCLI's Agent Vault](https://github.com/onecli/onecli), which injects credentials at request time and enforces per-agent policies and rate limits.
-- **Agent templates**: stamp a ready-to-run agent (instructions + MCP tools + skills, no secrets) from a reusable bundle, via the setup wizard or `ncl groups create --template <ref>`. Load from the [public library](https://github.com/nanocoai/nanoclaw-templates), a local folder, or any git repo. See [docs/templates.md](docs/templates.md).
+- **Agent templates**: stamp a ready-to-run agent (instructions + MCP tools + skills, no secrets) from a reusable bundle via `ncl groups create --template <ref>`. Templates load from the local `templates/` folder; populate it by hand or by copying from the [public library](https://github.com/nanocoai/nanoclaw-templates). See [docs/templates.md](docs/templates.md).
 
 ## Usage
 
@@ -124,10 +124,7 @@ This keeps trunk as pure registry and infra, and every fork stays lean — users
 
 ### RFS (Request for Skills)
 
-Skills we'd like to see:
-
-**Communication Channels**
-- `/add-signal` — Add Signal as a channel
+No channel or provider skills are currently requested — propose one via an issue.
 
 ## Requirements
 
@@ -142,7 +139,7 @@ Skills we'd like to see:
 messaging apps → host process (router) → inbound.db → container (Bun, Claude Agent SDK) → outbound.db → host process (delivery) → messaging apps
 ```
 
-A single Node host orchestrates per-session agent containers. When a message arrives, the host routes it via the entity model (user → messaging group → agent group → session), writes it to the session's `inbound.db`, and wakes the container. The agent-runner inside the container polls `inbound.db`, runs Claude, and writes responses to `outbound.db`. The host polls `outbound.db` and delivers back through the channel adapter.
+A single Node host orchestrates per-session agent containers. When a message arrives, the host routes it via the entity model (user → messaging group → agent group → session), writes it to the session's `inbound.db`, and wakes the container. The agent-runner inside the container polls `inbound.db`, runs the agent, and writes responses to `outbound.db`. The host polls `outbound.db` and delivers back through the channel adapter.
 
 Two SQLite files per session, each with exactly one writer — no cross-mount contention, no IPC, no stdin piping. Channels and alternative providers self-register at startup; trunk ships the registry and the Chat SDK bridge, while the adapters themselves are skill-installed per fork.
 
@@ -165,7 +162,7 @@ Key files:
 
 **Why Docker?**
 
-Docker provides cross-platform support (macOS, Linux and Windows via WSL2) and a mature ecosystem. On macOS, Apple Container is also supported as a lighter-weight native runtime. For additional isolation, [Docker Sandboxes](docs/docker-sandboxes.md) run each container inside a micro VM.
+Docker provides cross-platform support (macOS, Linux and Windows via WSL2) and a mature ecosystem.
 
 **Can I run this on Linux or Windows?**
 

container/agent-runner/src/cli/ncl.ts

@@ -22,7 +22,9 @@ type RequestFrame = {
 };
 
 type ResponseFrame =
-  | { id: string; ok: true; data: unknown }
+  // `human` mirrors src/cli/frame.ts: an optional server-rendered string we
+  // print verbatim instead of running our own (drift-prone) formatter.
+  | { id: string; ok: true; data: unknown; human?: string }
   | { id: string; ok: false; error: { code: string; message: string } };
 
 // ---------------------------------------------------------------------------
@@ -244,6 +246,9 @@ if (!resp) {
 
 if (json) {
   process.stdout.write(JSON.stringify(resp, null, 2) + '\n');
+} else if (resp.ok && resp.human !== undefined) {
+  // Server-rendered view — print verbatim.
+  process.stdout.write(resp.human + '\n');
 } else {
   const output = formatHuman(resp);
   if (!resp.ok) {

container/agent-runner/src/current-batch.ts

@@ -1,29 +0,0 @@
-/**
- * Per-batch context the poll loop publishes for downstream consumers
- * (MCP tools, etc.) that don't sit on the poll-loop's call stack.
- *
- * Today the only field is `inReplyTo` — the id of the first inbound
- * message in the batch the agent is currently processing. MCP tools like
- * `send_message` and `send_file` read this and stamp it onto the outbound
- * row so the host's a2a return-path routing can correlate replies back to
- * the originating session.
- *
- * This is module-level state on purpose: the agent-runner is single-process
- * and processes one batch at a time. Poll-loop calls `setCurrentInReplyTo`
- * before invoking the provider and `clearCurrentInReplyTo` after the batch
- * completes (or errors out).
- */
-let currentInReplyTo: string | null = null;
-
-export function setCurrentInReplyTo(id: string | null): void {
-  currentInReplyTo = id;
-}
-
-export function clearCurrentInReplyTo(): void {
-  currentInReplyTo = null;
-}
-
-export function getCurrentInReplyTo(): string | null {
-  return currentInReplyTo;
-}
-

container/agent-runner/src/db/connection.ts

@@ -48,7 +48,11 @@ export function openInboundDb(): Database {
   // so the singleton survives for the rest of the test.
   if (_testMode && _inbound) {
     const db = _inbound;
-    return { prepare: (sql: string) => db.prepare(sql), exec: (sql: string) => db.exec(sql), close: () => {} } as unknown as Database;
+    return {
+      prepare: (sql: string) => db.prepare(sql),
+      exec: (sql: string) => db.exec(sql),
+      close: () => {},
+    } as unknown as Database;
   }
   const db = new Database(DEFAULT_INBOUND_PATH, { readonly: true });
   db.exec('PRAGMA busy_timeout = 5000');
@@ -260,11 +264,3 @@ export function closeSessionDb(): void {
   _outbound?.close();
   _outbound = null;
 }
-
-/**
- * @deprecated Use getInboundDb() / getOutboundDb() instead.
- * Kept for backward compatibility during migration.
- */
-export function getSessionDb(): Database {
-  return getInboundDb();
-}

container/agent-runner/src/db/index.ts

@@ -1,7 +1,6 @@
 export {
   getInboundDb,
   getOutboundDb,
-  getSessionDb,
   initTestSessionDb,
   closeSessionDb,
   touchHeartbeat,

container/agent-runner/src/db/messages-in.ts

@@ -56,7 +56,7 @@ function getMaxMessagesPerPrompt(): number {
  * Reads from inbound.db (read-only), filters against processing_ack in outbound.db
  * to skip messages already picked up by this or a previous container run.
  *
- * Returns the most recent `MAX_MESSAGES_PER_PROMPT` pending rows in
+ * Returns the most recent `maxMessagesPerPrompt` pending rows in
  * chronological order, regardless of their `trigger` flag: accumulated
  * context (trigger=0) rides along with the wake-eligible rows so the agent
  * sees the prior context it missed. Host's countDueMessages gates waking on
@@ -163,4 +163,3 @@ export function findQuestionResponse(questionId: string): MessageInRow | undefin
     inbound.close();
   }
 }
-

container/agent-runner/src/db/session-state.ts

@@ -77,3 +77,47 @@ export function setContinuation(providerName: string, id: string): void {
 export function clearContinuation(providerName: string): void {
   deleteValue(continuationKey(providerName));
 }
+
+/**
+ * The a2a reply stamp: the id of the first inbound message in the batch the
+ * agent is currently processing. The poll loop publishes it at batch start;
+ * MCP tools (`send_message`, `send_file`) read it and stamp it onto outbound
+ * rows so the host's a2a return-path routing can correlate replies back to
+ * the originating session.
+ *
+ * This lives in outbound.db rather than module state because the MCP server
+ * runs as a separate stdio subprocess from the poll loop — module state set
+ * by the poll loop is invisible to it. Both processes open outbound.db
+ * (journal_mode=DELETE + busy_timeout make intra-container access safe).
+ */
+const IN_REPLY_TO_KEY = 'current_in_reply_to';
+
+/**
+ * Ignore a stamp older than this. The poll loop clears the stamp in a
+ * finally, but a container killed mid-batch (SIGKILL) can leave one behind;
+ * the guard stops a later out-of-batch read from picking up a dead stamp.
+ * Generous so a long-running batch's late sends still stamp correctly.
+ */
+const IN_REPLY_TO_MAX_AGE_MS = 30 * 60 * 1000;
+
+export function setCurrentInReplyTo(id: string | null): void {
+  if (id === null) {
+    clearCurrentInReplyTo();
+    return;
+  }
+  setValue(IN_REPLY_TO_KEY, id);
+}
+
+export function clearCurrentInReplyTo(): void {
+  deleteValue(IN_REPLY_TO_KEY);
+}
+
+export function getCurrentInReplyTo(): string | null {
+  const row = getOutboundDb()
+    .prepare('SELECT value, updated_at FROM session_state WHERE key = ?')
+    .get(IN_REPLY_TO_KEY) as { value: string; updated_at: string } | undefined;
+  if (!row) return null;
+  const age = Date.now() - new Date(row.updated_at).getTime();
+  if (!Number.isFinite(age) || age > IN_REPLY_TO_MAX_AGE_MS) return null;
+  return row.value;
+}

container/agent-runner/src/mcp-tools/core.test.ts

@@ -4,14 +4,31 @@
  * batch in poll-loop, and outbound writes from MCP tools (send_message,
  * send_file) must pick it up so a2a return-path routing on the host can
  * correlate replies back to the originating session.
+ *
+ * The stamp is published through session_state in outbound.db, not module
+ * state — the MCP server runs as a separate stdio subprocess from the poll
+ * loop, so it can only see the stamp through the shared DB. These tests seed
+ * it the same way the poll-loop process does (a direct DB write) rather than
+ * via any in-memory helper, so they exercise the real process boundary.
  */
 import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
 
-import { initTestSessionDb, closeSessionDb, getInboundDb } from '../db/connection.js';
+import { initTestSessionDb, closeSessionDb, getInboundDb, getOutboundDb } from '../db/connection.js';
 import { getUndeliveredMessages } from '../db/messages-out.js';
-import { setCurrentInReplyTo, clearCurrentInReplyTo } from '../current-batch.js';
 import { sendMessage } from './core.js';
 
+/**
+ * Publish the a2a reply stamp the way the poll loop does: a direct write to
+ * session_state in outbound.db. `ageMs` back-dates updated_at to exercise the
+ * staleness guard MCP tools apply when reading it.
+ */
+function publishInReplyTo(id: string, ageMs = 0): void {
+  const updatedAt = new Date(Date.now() - ageMs).toISOString();
+  getOutboundDb()
+    .prepare('INSERT OR REPLACE INTO session_state (key, value, updated_at) VALUES (?, ?, ?)')
+    .run('current_in_reply_to', id, updatedAt);
+}
+
 beforeEach(() => {
   initTestSessionDb();
   // Seed a peer agent destination
@@ -24,13 +41,12 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  clearCurrentInReplyTo();
   closeSessionDb();
 });
 
 describe('send_message MCP tool — in_reply_to plumbing', () => {
-  it('stamps current batch in_reply_to on outbound rows', async () => {
-    setCurrentInReplyTo('inbound-msg-1');
+  it('stamps the batch in_reply_to (published via the DB) on outbound rows', async () => {
+    publishInReplyTo('inbound-msg-1');
 
     await sendMessage.handler({ to: 'peer', text: 'hello' });
 
@@ -40,7 +56,17 @@ describe('send_message MCP tool — in_reply_to plumbing', () => {
   });
 
   it('writes null when no batch is active', async () => {
-    // No setCurrentInReplyTo before this call — simulates ad-hoc / out-of-batch invocation.
+    // Nothing published to session_state — simulates ad-hoc / out-of-batch invocation.
+    await sendMessage.handler({ to: 'peer', text: 'hello' });
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(out[0].in_reply_to).toBeNull();
+  });
+
+  it('ignores a stale stamp left behind by a killed container', async () => {
+    publishInReplyTo('inbound-msg-1', 60 * 60 * 1000); // an hour old
+
     await sendMessage.handler({ to: 'peer', text: 'hello' });
 
     const out = getUndeliveredMessages();

container/agent-runner/src/mcp-tools/core.ts

@@ -9,9 +9,9 @@
 import fs from 'fs';
 import path from 'path';
 
-import { getCurrentInReplyTo } from '../current-batch.js';
 import { findByName, getAllDestinations } from '../destinations.js';
 import { getMessageIdBySeq, getRoutingBySeq, writeMessageOut } from '../db/messages-out.js';
+import { getCurrentInReplyTo } from '../db/session-state.js';
 import { getSessionRouting } from '../db/session-routing.js';
 import { registerTools } from './server.js';
 import type { McpToolDefinition } from './types.js';

container/agent-runner/src/poll-loop.ts

@@ -2,8 +2,13 @@ import { findByName, getAllDestinations, type DestinationEntry } from './destina
 import { getPendingMessages, markProcessing, markCompleted, type MessageInRow } from './db/messages-in.js';
 import { writeMessageOut } from './db/messages-out.js';
 import { getInboundDb, touchHeartbeat, clearStaleProcessingAcks } from './db/connection.js';
-import { clearContinuation, migrateLegacyContinuation, setContinuation } from './db/session-state.js';
-import { clearCurrentInReplyTo, setCurrentInReplyTo } from './current-batch.js';
+import {
+  clearContinuation,
+  clearCurrentInReplyTo,
+  migrateLegacyContinuation,
+  setContinuation,
+  setCurrentInReplyTo,
+} from './db/session-state.js';
 import {
   formatMessages,
   extractRouting,

container/agent-runner/src/providers/claude.ts

@@ -449,7 +449,7 @@ export class ClaudeProvider implements AgentProvider {
           yield { type: 'result', text, isError: m.is_error === true };
         } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'api_retry') {
           yield { type: 'error', message: 'API retry', retryable: true };
-        } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'rate_limit_event') {
+        } else if (message.type === 'rate_limit_event') {
           yield { type: 'error', message: 'Rate limit', retryable: false, classification: 'quota' };
         } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'compact_boundary') {
           const meta = (message as { compact_metadata?: { pre_tokens?: number } }).compact_metadata;

container/agent-runner/src/providers/index.ts

@@ -3,4 +3,3 @@
 // level. Skills add a new provider by appending one import line below.
 
 import './claude.js';
-import './mock.js';

docs/APPLE-CONTAINER-NETWORKING.md

@@ -1,90 +0,0 @@
-# Apple Container Networking Setup (macOS 26)
-
-Apple Container's vmnet networking requires manual configuration for containers to access the internet. Without this, containers can communicate with the host but cannot reach external services (DNS, HTTPS, APIs).
-
-## Quick Setup
-
-Run these two commands (requires `sudo`):
-
-```bash
-# 1. Enable IP forwarding so the host routes container traffic
-sudo sysctl -w net.inet.ip.forwarding=1
-
-# 2. Enable NAT so container traffic gets masqueraded through your internet interface
-echo "nat on en0 from 192.168.64.0/24 to any -> (en0)" | sudo pfctl -ef -
-```
-
-> **Note:** Replace `en0` with your active internet interface. Check with: `route get 8.8.8.8 | grep interface`
-
-## Making It Persistent
-
-These settings reset on reboot. To make them permanent:
-
-**IP Forwarding** — add to `/etc/sysctl.conf`:
-```
-net.inet.ip.forwarding=1
-```
-
-**NAT Rules** — add to `/etc/pf.conf` (before any existing rules):
-```
-nat on en0 from 192.168.64.0/24 to any -> (en0)
-```
-
-Then reload: `sudo pfctl -f /etc/pf.conf`
-
-## IPv6 DNS Issue
-
-By default, DNS resolvers return IPv6 (AAAA) records before IPv4 (A) records. Since our NAT only handles IPv4, Node.js applications inside containers will try IPv6 first and fail.
-
-The container image and runner are configured to prefer IPv4 via:
-```
-NODE_OPTIONS=--dns-result-order=ipv4first
-```
-
-This is set both in the `Dockerfile` and passed via `-e` flag in `container-runner.ts`.
-
-## Verification
-
-```bash
-# Check IP forwarding is enabled
-sysctl net.inet.ip.forwarding
-# Expected: net.inet.ip.forwarding: 1
-
-# Test container internet access
-container run --rm --entrypoint curl nanoclaw-agent:latest \
-  -s4 --connect-timeout 5 -o /dev/null -w "%{http_code}" https://api.anthropic.com
-# Expected: 404
-
-# Check bridge interface (only exists when a container is running)
-ifconfig bridge100
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `curl: (28) Connection timed out` | IP forwarding disabled | `sudo sysctl -w net.inet.ip.forwarding=1` |
-| HTTP works, HTTPS times out | IPv6 DNS resolution | Add `NODE_OPTIONS=--dns-result-order=ipv4first` |
-| `Could not resolve host` | DNS not forwarded | Check bridge100 exists, verify pfctl NAT rules |
-| Container hangs after output | Missing `process.exit(0)` in agent-runner | Rebuild container image |
-
-## How It Works
-
-```
-Container VM (192.168.64.x)
-    │
-    ├── eth0 → gateway 192.168.64.1
-    │
-bridge100 (192.168.64.1) ← host bridge, created by vmnet when container runs
-    │
-    ├── IP forwarding (sysctl) routes packets from bridge100 → en0
-    │
-    ├── NAT (pfctl) masquerades 192.168.64.0/24 → en0's IP
-    │
-en0 (your WiFi/Ethernet) → Internet
-```
-
-## References
-
-- [apple/container#469](https://github.com/apple/container/issues/469) — No network from container on macOS 26
-- [apple/container#656](https://github.com/apple/container/issues/656) — Cannot access internet URLs during building

docs/README.md

@@ -6,8 +6,5 @@ The files in this directory are original design documents and developer referenc
 
 | This directory | Documentation site |
 |---|---|
-| [SPEC.md](SPEC.md) | [Architecture](https://docs.nanoclaw.dev/concepts/architecture) |
 | [SECURITY.md](SECURITY.md) | [Security model](https://docs.nanoclaw.dev/concepts/security) |
 | [REQUIREMENTS.md](REQUIREMENTS.md) | [Introduction](https://docs.nanoclaw.dev/introduction) |
-| [docker-sandboxes.md](docker-sandboxes.md) | [Docker Sandboxes](https://docs.nanoclaw.dev/advanced/docker-sandboxes) |
-| [APPLE-CONTAINER-NETWORKING.md](APPLE-CONTAINER-NETWORKING.md) | [Container runtime](https://docs.nanoclaw.dev/advanced/container-runtime) |

docs/REQUIREMENTS.md

@@ -20,7 +20,7 @@ The entire codebase should be something you can read and understand. One Node.js
 
 ### Security Through True Isolation
 
-Instead of application-level permission systems trying to prevent agents from accessing things, agents run in actual Linux containers. The isolation is at the OS level. Agents can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your Mac.
+Instead of application-level permission systems trying to prevent agents from accessing things, agents run in actual Linux containers. The isolation is at the OS level. Agents can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host.
 
 ### Built for the Individual User
 
@@ -47,23 +47,23 @@ When people contribute, they shouldn't add "Telegram support alongside WhatsApp.
 Skills we'd like to see contributed:
 
 ### Communication Channels
-- `/add-signal` - Add Signal as a channel
-- `/add-matrix` - Add Matrix integration
 
-> **Note:** Telegram, Slack, Discord, Gmail, and Apple Container skills already exist. See the [skills documentation](https://docs.nanoclaw.dev/integrations/skills-system) for the full list.
+None currently — Signal and Matrix have since shipped as skills.
+
+> **Note:** Telegram, Slack, Discord, Gmail, Signal, and Matrix skills already exist. See the [skills documentation](https://docs.nanoclaw.dev/integrations/skills-system) for the full list.
 
 ---
 
 ## Vision
 
-A personal Claude assistant accessible via messaging, with minimal custom code.
+A personal AI assistant accessible via messaging, with minimal custom code.
 
 **Core components:**
 - **Claude Agent SDK** as the core agent
-- **Containers** for isolated agent execution (Linux VMs)
+- **Containers** for isolated agent execution (Docker)
 - **Multi-channel messaging** (WhatsApp, Telegram, Discord, Slack, Gmail) — add exactly the channels you need
 - **Persistent memory** per conversation and globally
-- **Scheduled tasks** that run Claude and can message back
+- **Scheduled tasks** executed by the agent, which can message back
 - **Web access** for search and browsing
 - **Browser automation** via agent-browser
 
@@ -93,14 +93,14 @@ A personal Claude assistant accessible via messaging, with minimal custom code.
 - Sessions auto-compact when context gets too long, preserving critical information
 
 ### Container Isolation
-- All agents run inside containers (lightweight Linux VMs)
+- All agents run inside Docker containers
 - Each agent invocation spawns a container with mounted directories
 - Containers provide filesystem isolation - agents can only see mounted paths
 - Bash access is safe because commands run inside the container, not on the host
 - Browser automation via agent-browser with Chromium in the container
 
 ### Scheduled Tasks
-- Users can ask Claude to schedule recurring or one-time tasks from any group
+- Users can ask the agent to schedule recurring or one-time tasks from any group
 - Tasks run as full agents in the context of the group that created them
 - Tasks have access to all tools including Bash (safe in container)
 - Tasks can optionally send messages to their group via `send_message` tool, or complete silently

docs/SECURITY.md

@@ -1,70 +1,106 @@
 # NanoClaw Security Model
 
+> The canonical, continuously-verified version of this model lives at
+> [docs.nanoclaw.dev/concepts/security](https://docs.nanoclaw.dev/concepts/security).
+> This in-repo copy can drift; if the two disagree, verify against
+> `src/container-runner.ts` (`buildMounts`).
+
 ## Trust Model
 
+Privilege is **user-level**, persisted in the `user_roles` table (owner /
+admin, global or scoped to an agent group) plus `agent_group_members` (the
+unprivileged access gate).
+
 | Entity | Trust Level | Rationale |
 |--------|-------------|-----------|
-| Main group | Trusted | Private self-chat, admin control |
-| Non-main groups | Untrusted | Other users may be malicious |
-| Container agents | Sandboxed | Isolated execution environment |
-| Incoming messages | User input | Potential prompt injection |
+| Owners / admins (`user_roles`) | Trusted | Hold owner/admin roles; gate admin commands and approve credentialed actions |
+| Group members (`agent_group_members`) | Access-gated | Membership grants access to an agent group, but their messages are still untrusted input |
+| Unregistered senders | Untrusted | Subject to each messaging group's `unknown_sender_policy` |
+| Agent containers | Sandboxed | Long-lived per-session container; isolated by mounts, non-root, no host reach |
+| Incoming messages | User input | Potential prompt injection regardless of who sent them |
 
 ## Security Boundaries
 
 ### 1. Container Isolation (Primary Boundary)
 
-Agents execute in containers (lightweight Linux VMs), providing:
-- **Process isolation** - Container processes cannot affect the host
-- **Filesystem isolation** - Only explicitly mounted directories are visible
-- **Non-root execution** - Runs as unprivileged `node` user (uid 1000)
-- **Ephemeral containers** - Fresh environment per invocation (`--rm`)
+Agents execute in containers (Docker), providing:
+- **Process isolation** — container processes cannot affect the host
+- **Filesystem isolation** — only explicitly mounted directories are visible
+- **Non-root execution** — runs as an unprivileged user (`node`, uid 1000, or the host uid remapped in)
+- **Per-session containers** — one long-lived container per session polls that session's DBs and handles many messages, then is torn down (`--rm`) when the session goes idle.
 
-This is the primary security boundary. Rather than relying on application-level permission checks, the attack surface is limited by what's mounted.
+This is the primary security boundary. Rather than relying on application-level
+permission checks, the attack surface is limited by what's mounted.
 
 ### 2. Mount Security
 
-**External Allowlist** - Mount permissions stored at `~/.config/nanoclaw/mount-allowlist.json`, which is:
-- Outside project root
-- Never mounted into containers
-- Cannot be modified by agents
+`buildMounts` (`src/container-runner.ts`) composes a fixed set of mounts per
+spawn. For the default (Claude) provider these are:
 
-**Default Blocked Patterns:**
+| Container path | Host source | Mode | Purpose |
+|---|---|---|---|
+| `/workspace` | `data/v2-sessions/<group>/<session>/` | RW | Session folder — `inbound.db`, `outbound.db`, `outbox/`, `.claude/` |
+| `/workspace/agent` | `groups/<folder>/` | RW | Agent group working files + `CLAUDE.local.md` |
+| `/workspace/agent/container.json` | group `container.json` | RO | Container config — readable, not writable |
+| `/workspace/agent/CLAUDE.md` | composed `CLAUDE.md` | RO | Regenerated every spawn; agent edits would be clobbered |
+| `/workspace/agent/.claude-fragments` | group `.claude-fragments/` | RO | Composer skill/MCP fragments |
+| `/app/CLAUDE.md` | `container/CLAUDE.md` | RO | Shared base doc imported by the composed entry point |
+| `/home/node/.claude` | `data/v2-sessions/<group>/.claude-shared/` | RW | Claude state, settings, skill symlinks |
+| `/app/src` | `container/agent-runner/src/` | RO | Shared agent-runner source (same for all groups) |
+| `/app/skills` | `container/skills/` | RO | Shared container skills |
+| `/workspace/extra/<name>` | allowlisted host dir | RO (RW only if allowed) | Operator-configured additional mounts |
+
+The config mounts (`container.json`, `CLAUDE.md`, `.claude-fragments`) are
+**nested read-only mounts on top of the read-write group dir** — the agent can
+read its config but cannot modify it. The project root is **never mounted**: the
+container only ever sees the paths above plus any provider-contributed mounts
+(e.g. an OpenCode XDG dir). Host application source (`src/`, `dist/`,
+`package.json`) is not reachable.
+
+**Additional-mount allowlist** — extra mounts from a group's container config
+are validated against an allowlist at `~/.config/nanoclaw/mount-allowlist.json`,
+which is:
+- Outside the project root
+- Never mounted into containers
+- Not modifiable by agents
+
+Its schema:
+
+```json
+{
+  "allowedRoots": [
+    { "path": "~/projects", "allowReadWrite": true, "description": "Dev projects" },
+    { "path": "~/Documents/work", "allowReadWrite": false, "description": "Read-only" }
+  ],
+  "blockedPatterns": ["password", "secret", "token"]
+}
 ```
-.ssh, .gnupg, .aws, .azure, .gcloud, .kube, .docker,
-credentials, .env, .netrc, .npmrc, id_rsa, id_ed25519,
+
+**Default blocked patterns** (merged with any in the file):
+```
+.ssh, .gnupg, .gpg, .aws, .azure, .gcloud, .kube, .docker,
+credentials, .env, .netrc, .npmrc, .pypirc, id_rsa, id_ed25519,
 private_key, .secret
 ```
 
-**Protections:**
-- Symlink resolution before validation (prevents traversal attacks)
-- Container path validation (rejects `..` and absolute paths)
-- `nonMainReadOnly` option forces read-only for non-main groups
-
-**Read-Only Project Root:**
-
-The main group's project root is mounted read-only. Writable paths the agent needs (store, group folder, IPC, `.claude/`) are mounted separately. This prevents the agent from modifying host application code (`src/`, `dist/`, `package.json`, etc.) which would bypass the sandbox entirely on next restart. The `store/` directory is mounted read-write so the main agent can access the SQLite database directly.
+**Enforcement** (`src/modules/mount-security/index.ts`):
+- **No allowlist file ⇒ every additional mount is blocked** — the fixed mounts above are unaffected, but nothing extra is granted until the operator creates the file.
+- Symlinks are resolved to their real path (`realpathSync`) before any check, defeating traversal via symlink.
+- The real path is rejected if it matches a blocked pattern, and rejected unless it sits under one of `allowedRoots`.
+- The container path is validated: relative, non-empty, no `..`, no leading `/`, no `:` (blocks Docker `-v` option injection). It is mounted under `/workspace/extra/`.
+- **Read-write is granted only when the mount requests it (`readonly: false`) *and* the matched root has `allowReadWrite: true`.** Otherwise the mount is forced read-only.
 
 ### 3. Session Isolation
 
-Each group has isolated Claude sessions at `data/sessions/{group}/.claude/`:
-- Groups cannot see other groups' conversation history
-- Session data includes full message history and file contents read
-- Prevents cross-group information disclosure
+Per-session state lives under `data/v2-sessions/<agent-group>/<session>/`
+(`inbound.db`, `outbound.db`, `outbox/`, `.claude/`). Claude state
+(`.claude-shared`) and the working folder are scoped to the agent group, so:
+- Different agent groups cannot see each other's conversation history or files.
+- A group's sessions share that group's memory but keep separate message DBs.
 
-### 4. IPC Authorization
+This prevents cross-group information disclosure.
 
-Messages and task operations are verified against group identity:
-
-| Operation | Main Group | Non-Main Group |
-|-----------|------------|----------------|
-| Send message to own chat | ✓ | ✓ |
-| Send message to other chats | ✓ | ✗ |
-| Schedule task for self | ✓ | ✓ |
-| Schedule task for others | ✓ | ✗ |
-| View all tasks | ✓ | Own only |
-| Manage other groups | ✓ | ✗ |
-
-### 5. Credential Isolation (OneCLI Agent Vault)
+### 4. Credential Isolation (OneCLI Agent Vault)
 
 Real API credentials **never enter containers**. NanoClaw uses [OneCLI's Agent Vault](https://github.com/onecli/onecli) to proxy outbound requests and inject credentials at the gateway level.
 
@@ -77,13 +113,12 @@ Real API credentials **never enter containers**. NanoClaw uses [OneCLI's Agent V
 **Per-agent policies:**
 Each NanoClaw group gets its own OneCLI agent identity. This allows different credential policies per group (e.g. your sales agent vs. support agent). OneCLI supports rate limits, and time-bound access and approval flows are on the roadmap.
 
-**NOT Mounted:**
-- Channel auth sessions (`store/auth/`) — host only
-- Mount allowlist — external, never mounted
-- Any credentials matching blocked patterns
-- `.env` is shadowed with `/dev/null` in the project root mount
+**Never on the container filesystem:**
+- The project root and `.env` — never mounted; the container only receives the paths in the mount table above.
+- The mount allowlist — external (`~/.config/nanoclaw/…`), never mounted.
+- Real credentials — injected per request by the OneCLI gateway, never written into any mount.
 
-### 6. Egress Lockdown (Forced Proxy)
+### 5. Egress Lockdown (Forced Proxy)
 
 The `HTTPS_PROXY` env var only redirects *proxy-aware* clients — a tool that
 ignores it (or a raw socket) could reach the internet directly and bypass
@@ -111,31 +146,42 @@ no `host-gateway` route).
   exception: a heal failure there is logged but not fatal, since already-running
   agents stay on the internal net (no leak) until the gateway returns.
 
+**Default: egress is open.** Lockdown is **off** unless you opt in; by default
+the agent reaches the OneCLI gateway over the host-gateway path and outbound
+traffic is not confined to the internal network.
+
 **Configuration:**
 
 | Env | Default | Meaning |
 | --- | --- | --- |
-| `NANOCLAW_EGRESS_LOCKDOWN` | `false` | Set `true` to opt in (otherwise the host-gateway path is used). Enabled automatically by `/add-golden-registry`. |
+| `NANOCLAW_EGRESS_LOCKDOWN` | `false` | Set `true` to opt in (otherwise the host-gateway path is used). |
 | `NANOCLAW_EGRESS_NETWORK` | `nanoclaw-egress` | Network name. |
 | `ONECLI_GATEWAY_CONTAINER` | `onecli` | Gateway container to attach. |
 
+These variables are read from the **host process** environment (the service's
+environment / `.env`), not from inside the container. The agent container is
+started with only `TZ` and any provider-declared variables — host environment
+variables, including secrets, are never forwarded into the agent.
+
 **⚠ Behavior when enabled:** with lockdown on, agents have **no direct
 internet** — all traffic must go through OneCLI. Proxy-aware clients (npm, pnpm,
 pip, curl, node/bun with the proxy env) are unaffected. Any workflow that relies
 on a **non-proxy-aware** tool reaching the internet directly will fail by design.
 Lockdown is **off by default**; opt in with `NANOCLAW_EGRESS_LOCKDOWN=true`.
 
-## Privilege Comparison
+## Resource Limits
 
-| Capability | Main Group | Non-Main Group |
-|------------|------------|----------------|
-| Project root access | `/workspace/project` (ro) | None |
-| Store (SQLite DB) | `/workspace/project/store` (rw) | None |
-| Group folder | `/workspace/group` (rw) | `/workspace/group` (rw) |
-| Global memory | Implicit via project | `/workspace/global` (ro) |
-| Additional mounts | Configurable | Read-only unless allowed |
-| Network access | Unrestricted | Unrestricted |
-| MCP tools | All | All |
+Per-container CPU and memory caps are **opt-in and unset by default** — a runaway
+agent is not throttled unless the operator configures a limit:
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `CONTAINER_CPU_LIMIT` | *(empty — unbounded)* | Passed to `--cpus` when set (e.g. `2`). |
+| `CONTAINER_MEMORY_LIMIT` | *(empty — unbounded)* | Passed to `--memory` when set (e.g. `8g`). |
+
+Only `--memory` is a container-level cap; whether it's a *hard* cap depends on
+the host having no swap (a deployment concern). On a swapless host a runaway is
+OOM-killed at the limit.
 
 ## Security Architecture Diagram
 
@@ -149,7 +195,7 @@ Lockdown is **off by default**; opt in with `NANOCLAW_EGRESS_LOCKDOWN=true`.
 ┌──────────────────────────────────────────────────────────────────┐
 │                     HOST PROCESS (TRUSTED)                        │
 │  • Message routing                                                │
-│  • IPC authorization                                              │
+│  • Role / access checks (user_roles, agent_group_members)        │
 │  • Mount validation (external allowlist)                          │
 │  • Container lifecycle                                            │
 │  • OneCLI Agent Vault (injects credentials, enforces policies)   │

docs/SPEC.md

@@ -1,5 +1,7 @@
 # NanoClaw Specification
 
+> **⚠️ Historical v1 spec.** This document describes the original NanoClaw v1 architecture — the single `store/messages.db`, the file-based IPC watcher, the `task-scheduler.ts` loop, the `MAX_CONCURRENT_CONTAINERS` cap, and the `groups/{channel}_{name}/` folder convention. **None of these exist in v2.** v2 replaced them with the two-DB session split (`inbound.db`/`outbound.db`), the entity model (users → messaging groups → agent groups → sessions), and the system-action delivery path. Kept for reference only. For the current architecture start at [architecture.md](architecture.md) and the root [CLAUDE.md](../CLAUDE.md); the v1→v2 diff is in [v1-to-v2-changes.md](v1-to-v2-changes.md).
+
 A personal Claude assistant with multi-channel support, persistent memory per conversation, scheduled tasks, and container-isolated agent execution.
 
 ---

docs/agent-runner-details.md

@@ -14,37 +14,62 @@ The boundary: the agent-runner decides **what** to send and **what to do** with
 
 ## AgentProvider Interface
 
+Provider-wide settings (MCP servers, env, additional directories, model, effort,
+assistant name) are passed to the provider **constructor** via `ProviderOptions`, not
+per query. `QueryInput` carries only what changes turn to turn: the prompt, the
+continuation token to resume, the working directory, and system context to inject.
+
 ```typescript
 interface AgentProvider {
+  /** True if the SDK handles slash commands natively and wants them passed
+   *  through raw. When false, the poll-loop formats them like any chat message. */
+  readonly supportsNativeSlashCommands: boolean;
+
+  /** Opt-in: scaffold a persistent memory/ tree at boot. Providers with native
+   *  memory (Claude's CLAUDE.local.md) omit it. Never gated on a provider name. */
+  readonly usesMemoryScaffold?: boolean;
+
+  /** Optional. Called after each completed exchange so providers whose harness
+   *  keeps no on-disk transcript can persist it themselves. Claude (the SDK
+   *  writes its own .jsonl) omits this. */
+  onExchangeComplete?(exchange: ProviderExchange): void;
+
   /** Start a new query. Returns a handle for streaming input and output. */
   query(input: QueryInput): AgentQuery;
+
+  /** True if the error means the stored continuation is invalid (missing
+   *  transcript, unknown session) and should be cleared. */
+  isSessionInvalid(err: unknown): boolean;
+
+  /** Optional pre-resume maintenance: given the stored continuation, return a
+   *  reason string to drop it and start fresh (e.g. transcript too large/old to
+   *  cold-resume before the host idle ceiling), or null to keep resuming. */
+  maybeRotateContinuation?(continuation: string, cwd: string): string | null;
+}
+
+interface ProviderOptions {
+  assistantName?: string;
+  mcpServers?: Record<string, McpServerConfig>;
+  env?: Record<string, string | undefined>;
+  additionalDirectories?: string[];
+  model?: string;   // alias (sonnet/opus/haiku) or full model ID
+  effort?: string;  // low | medium | high | xhigh | max
 }
 
 interface QueryInput {
-  /** Initial prompt (already formatted by agent-runner).
-   *  String for text-only. ContentBlock[] for multimodal (images, PDFs, audio). */
-  prompt: string | ContentBlock[];
+  /** Initial prompt, already formatted by the agent-runner into a string. */
+  prompt: string;
 
-  /** Session ID to resume, if any */
-  sessionId?: string;
+  /** Opaque continuation token from a previous query. The provider decides
+   *  what it means (session ID, thread ID, or nothing). */
+  continuation?: string;
 
-  /** Resume from a specific point in the session (provider-specific, may be ignored) */
-  resumeAt?: string;
-
-  /** Working directory inside the container */
+  /** Working directory inside the container. */
   cwd: string;
 
-  /** MCP server configurations (normalized format — provider translates) */
-  mcpServers: Record<string, McpServerConfig>;
-
-  /** System prompt / developer instructions */
-  systemPrompt?: string;
-
-  /** Environment variables for the SDK process */
-  env: Record<string, string | undefined>;
-
-  /** Additional directories the agent can access */
-  additionalDirectories?: string[];
+  /** System context to inject; the provider translates it into whatever its
+   *  SDK expects (preset append, full system prompt, per-turn injection). */
+  systemContext?: { instructions?: string };
 }
 
 interface McpServerConfig {
@@ -54,40 +79,42 @@ interface McpServerConfig {
 }
 
 interface AgentQuery {
-  /** Push a follow-up message into the active query */
+  /** Push a follow-up message into the active query. */
   push(message: string): void;
 
-  /** Signal that no more input will be sent */
+  /** Signal that no more input will be sent. */
   end(): void;
 
-  /** Output event stream */
+  /** Output event stream. */
   events: AsyncIterable<ProviderEvent>;
 
-  /** Force-stop the query (e.g., container shutting down) */
+  /** Force-stop the query (e.g., container shutting down). */
   abort(): void;
 }
 
 type ProviderEvent =
-  | { type: 'init'; sessionId: string }
-  | { type: 'result'; text: string | null }
+  | { type: 'init'; continuation: string }
+  | { type: 'result'; text: string | null; isError?: boolean }
   | { type: 'error'; message: string; retryable: boolean; classification?: string }
-  | { type: 'progress'; message: string };
+  | { type: 'progress'; message: string }
+  | { type: 'activity' };
 ```
 
 ### What the interface does NOT include
 
 - **Message formatting** — the agent-runner formats messages before passing to the provider. The provider receives a ready-to-send prompt string.
-- **Hooks** — Claude-specific. The Claude provider registers hooks internally (PreCompact, PreToolUse, etc.). Other providers don't need them.
-- **Tool allowlists** — Claude uses `allowedTools`. Codex uses `approvalPolicy`. OpenCode uses `permission`. Each provider configures this internally based on the same intent: "allow everything, no prompting."
-- **Session persistence** — Claude persists sessions to disk automatically. Codex and OpenCode manage their own session state. The agent-runner doesn't control this — it just passes `sessionId` and `resumeAt`.
+- **Hooks** — Claude-specific. The Claude provider registers hooks internally (PreToolUse, PostToolUse, PreCompact). Other providers don't need them.
+- **Tool allowlists** — Claude uses `allowedTools` + `disallowedTools`. Other SDKs use their own equivalents. Each provider configures this internally.
+- **Session persistence** — the agent-runner stores one opaque `continuation` token per provider (see [Session Resume](#session-resume)) and passes it back as `QueryInput.continuation`. What it means is provider-private; Claude persists its own `.jsonl` transcript on disk keyed by the continuation (session ID).
 - **Sandbox configuration** — provider-specific. Each provider configures its own sandbox internally.
 
 ### Provider event semantics
 
-- **`init`** — emitted once per query when the provider establishes or resumes a session. The agent-runner captures `sessionId` for future resume.
-- **`result`** — emitted when the agent produces a complete response. May be emitted multiple times per query (e.g., Claude's multi-turn with subagents). The agent-runner writes each result to messages_out.
-- **`error`** — emitted on failure. `retryable` indicates whether the agent-runner should retry. `classification` is optional detail (e.g., 'quota', 'auth', 'transport').
+- **`init`** — emitted once per query when the provider establishes or resumes a session. The agent-runner captures `continuation` and persists it for future resume.
+- **`result`** — emitted when the agent produces a complete response. May be emitted multiple times per query (e.g., Claude's multi-turn with subagents). `isError` is set when the SDK flagged the turn as an error (e.g. a non-retryable billing error) so the poll-loop still surfaces the text instead of dropping it. The agent-runner writes each result to messages_out.
+- **`error`** — emitted on failure. `retryable` indicates whether the agent-runner should retry. `classification` is optional detail (e.g., 'quota').
 - **`progress`** — optional, for logging. The agent-runner logs these but doesn't act on them.
+- **`activity`** — a liveness signal. Providers MUST yield it on every underlying SDK event (tool call, thinking, partial message) so the poll-loop's idle timer stays honest during long tool runs.
 
 ## Provider Implementations
 
@@ -97,58 +124,82 @@ Only the `claude` provider ships in trunk. The Codex and OpenCode sections below
 
 Wraps `@anthropic-ai/claude-agent-sdk`'s `query()`.
 
+The provider takes its settings (`mcpServers`, `env`, `additionalDirectories`,
+`model`, `effort`, `assistantName`) in its constructor via `ProviderOptions`; `query()`
+only reads the per-turn `QueryInput`.
+
 ```typescript
 class ClaudeProvider implements AgentProvider {
+  readonly supportsNativeSlashCommands = true;
+  // ...constructor stores options.mcpServers, .env, .additionalDirectories,
+  //    .model, .effort, .assistantName...
+
   query(input: QueryInput): AgentQuery {
     const stream = new MessageStream();  // AsyncIterable<SDKUserMessage>
     stream.push(input.prompt);
 
-    const sdkQuery = query({
+    const sdkResult = sdkQuery({
       prompt: stream,
       options: {
         cwd: input.cwd,
-        resume: input.sessionId,
-        resumeSessionAt: input.resumeAt,
-        systemPrompt: input.systemPrompt
-          ? { type: 'preset', preset: 'claude_code', append: input.systemPrompt }
+        additionalDirectories: this.additionalDirectories,
+        resume: input.continuation,
+        pathToClaudeCodeExecutable: '/pnpm/claude',
+        systemPrompt: input.systemContext?.instructions
+          ? { type: 'preset', preset: 'claude_code', append: input.systemContext.instructions }
           : undefined,
-        mcpServers: input.mcpServers,  // already the right shape
-        additionalDirectories: input.additionalDirectories,
-        env: input.env,
-        allowedTools: NANOCLAW_TOOL_ALLOWLIST,
+        // Base tools plus one `mcp__<server>__*` pattern per registered MCP
+        // server — without the explicit MCP patterns the SDK's allowedTools
+        // filter silently drops every MCP namespace.
+        allowedTools: [...TOOL_ALLOWLIST, ...Object.keys(this.mcpServers).map(mcpAllowPattern)],
+        disallowedTools: SDK_DISALLOWED_TOOLS,
+        env: this.env,
+        model: this.model,
+        effort: this.effort,
         permissionMode: 'bypassPermissions',
         allowDangerouslySkipPermissions: true,
+        settingSources: ['project', 'user', 'local'],
+        mcpServers: this.mcpServers,
         hooks: {
-          PreCompact: [{ hooks: [preCompactHook] }],
-          PreToolUse: [{ matcher: 'Bash', hooks: [sanitizeBashHook] }],
+          PreToolUse: [{ hooks: [preToolUseHook] }],
+          PostToolUse: [{ hooks: [postToolUseHook] }],
+          PostToolUseFailure: [{ hooks: [postToolUseHook] }],
+          PreCompact: [{ hooks: [createPreCompactHook(this.assistantName)] }],
         },
       },
     });
 
+    let aborted = false;
     return {
       push: (msg) => stream.push(msg),
       end: () => stream.end(),
-      abort: () => sdkQuery.close(),
-      events: translateClaudeEvents(sdkQuery),
+      // Abort doesn't call into the SDK — it flips a flag the event generator
+      // checks and ends the input stream so the query drains and stops.
+      abort: () => { aborted = true; stream.end(); },
+      events: translateEvents(sdkResult, () => aborted),
     };
   }
 }
 ```
 
-`translateClaudeEvents` is an async generator that maps SDK messages to `ProviderEvent`:
-- `message.type === 'system' && message.subtype === 'init'` → `{ type: 'init', sessionId }`
-- `message.type === 'result'` → `{ type: 'result', text }`
-- `message.type === 'system' && message.subtype === 'api_retry'` → `{ type: 'error', retryable: true }`
-- `message.type === 'system' && message.subtype === 'rate_limit_event'` → `{ type: 'error', retryable: false, classification: 'quota' }`
-- `message.type === 'system' && message.subtype === 'task_notification'` → `{ type: 'progress', message }`
-- Everything else → logged, not emitted
+`translateEvents` is an async generator that yields `{ type: 'activity' }` for **every**
+SDK message (so the idle timer stays honest) and maps recognized messages to `ProviderEvent`:
+- `system`/`init` → `{ type: 'init', continuation: session_id }`
+- `result` → `{ type: 'result', text, isError }` — `text` is `result.result`, or the joined `result.errors[]` on error subtypes (billing/quota), so the notice still reaches the user
+- `system`/`api_retry` → `{ type: 'error', retryable: true }`
+- `system`/`rate_limit_event` → `{ type: 'error', retryable: false, classification: 'quota' }`
+- `system`/`compact_boundary` → `{ type: 'result', text: 'Context compacted…' }`
+- `system`/`task_notification` → `{ type: 'progress', message }`
+- when the `aborted` flag is set → the generator returns immediately
 
-**Claude-specific features preserved inside the provider:**
-- `MessageStream` for async iterable input (push-based)
-- `resumeSessionAt` for resume at specific message UUID
-- PreCompact hook for transcript archiving
-- PreToolUse hook for sanitizing bash env vars
-- Full tool allowlist
+**Claude-specific behavior inside the provider:**
+- `MessageStream` for async iterable input (push-based follow-ups)
+- Resume via the SDK `resume` option keyed on the stored `continuation` (the SDK session ID) — no separate resume-at cursor
+- `TOOL_ALLOWLIST` (Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, Task, Skill, …) extended at the call site with a `mcp__<server>__*` pattern per registered MCP server; `SDK_DISALLOWED_TOOLS` blocks SDK builtins that collide with NanoClaw's own scheduling/interaction model (CronCreate/Delete/List, ScheduleWakeup, AskUserQuestion, Enter/ExitPlanMode, Enter/ExitWorktree)
+- **PreToolUse hook** records the current tool + its declared timeout to `container_state` (so the host sweep widens its stuck tolerance while a long Bash runs) and, as defense-in-depth, blocks any `SDK_DISALLOWED_TOOLS` call that slips through. It does **not** sanitize bash env vars — there is no such hook.
+- **PostToolUse / PostToolUseFailure** hooks clear the in-flight tool
+- **PreCompact** hook archives the transcript to `conversations/` before compaction
+- `maybeRotateContinuation` drops an oversized/aged transcript (default caps 12 MB / 14 days, both operator-overridable) so a cold container isn't killed reloading days of `.jsonl` before the host idle ceiling; `isSessionInvalid` clears a continuation whose transcript is gone
 - `additionalDirectories` for multi-directory access
 
 ### Codex Provider
@@ -159,8 +210,8 @@ Wraps `@openai/codex-sdk`.
 class CodexProvider implements AgentProvider {
   query(input: QueryInput): AgentQuery {
     const codex = new Codex(this.buildOptions(input));
-    const thread = input.sessionId
-      ? codex.resumeThread(input.sessionId, this.threadOptions(input))
+    const thread = input.continuation
+      ? codex.resumeThread(input.continuation, this.threadOptions(input))
       : codex.startThread(this.threadOptions(input));
 
     const abortController = new AbortController();
@@ -188,13 +239,13 @@ class CodexProvider implements AgentProvider {
           signal: abortController.signal,
         });
 
-        let sessionId: string | undefined;
+        let continuation: string | undefined;
         let resultText = '';
 
         for await (const event of streamed.events) {
           if (event.type === 'thread.started') {
-            sessionId = event.thread_id;
-            yield { type: 'init', sessionId };
+            continuation = event.thread_id;
+            yield { type: 'init', continuation };
           }
           if (event.type === 'item.completed' && event.item.type === 'agent_message') {
             resultText = event.item.text || resultText;
@@ -264,7 +315,7 @@ class OpenCodeProvider implements AgentProvider {
 
   private async *run(client, server, stream, input, getPendingFollowUp): AsyncIterable<ProviderEvent> {
     const session = await client.session.create();
-    yield { type: 'init', sessionId: session.data.id };
+    yield { type: 'init', continuation: session.data.id };
 
     await client.session.promptAsync({
       path: { id: session.data.id },
@@ -356,62 +407,58 @@ The agent-runner transforms messages_in rows into a prompt string. The provider
 
 **Routing field stripping:** `platform_id`, `channel_type`, `thread_id` are never included in the prompt. They're stored as context for writing messages_out.
 
-**Single message formatting by kind:**
+Every kind renders to a single self-contained XML element. The `id` attribute is the
+message's `seq` (the agent-facing message ID it passes to `edit_message` / `add_reaction`).
+The `from` attribute is the origin destination name (resolved from the routing fields via
+the destination map), so the agent always knows where a message came from — routing fields
+themselves are never shown.
 
-- **`chat`** — format into message XML:
+- **`chat`** — one `<message>` per row:
   ```xml
-  <message sender="John" time="2024-01-01 10:00">
-    Check this PR
-  </message>
+  <message id="5" from="family" sender="John" time="Jan 1, 10:00 AM">Check this PR</message>
   ```
+  A reply carries a `reply_to` attribute and an inline `<quoted_message from="…">…</quoted_message>`.
 
-- **`chat-sdk`** — extract fields from serialized Chat SDK message:
+- **`chat-sdk`** — same `<message>` shape, fields extracted from the serialized Chat SDK
+  message. Attachments are appended inline: `[image: screenshot.png — saved to /workspace/…]`
+  or `[image: screenshot.png (https://signed-url…)]`. Images/PDFs that Claude handles
+  natively are also passed as content blocks (see Media Handling below).
+
+- **`task`** — a `<task>` element, script output first when present:
   ```xml
-  <message sender="John (john@slack)" time="2024-01-01 10:00">
-    Check this PR
-    [image: screenshot.png — https://signed-url...]
-  </message>
-  ```
-  Attachments are listed inline. Images/PDFs that Claude handles natively are passed as content blocks (see Media Handling below).
-
-- **`task`** — task prompt, optionally with script output:
-  ```
-  [SCHEDULED TASK]
-
-  Script output:
-  {"data": ...}
+  <task from="scheduler" time="Jan 1, 9:00 AM">Script output:
+  {"data": …}
 
   Instructions:
-  Review open PRs
+  Review open PRs</task>
   ```
 
-- **`webhook`** — webhook payload:
-  ```
-  [WEBHOOK: github/pull_request]
-
-  {"action": "opened", "pull_request": {...}}
+- **`webhook`** — a `<webhook>` element wrapping the JSON payload:
+  ```xml
+  <webhook from="github" source="github" event="pull_request">{"action": "opened", …}</webhook>
   ```
 
-- **`system`** — host action result (response to an earlier system request):
-  ```
-  [SYSTEM RESPONSE]
-
-  Action: register_agent_group
-  Status: success
-  Result: {"agent_group_id": "ag-456"}
+- **`system`** — host action result, rendered as `<system_response>`:
+  ```xml
+  <system_response from="host" action="create_agent" status="success">{"agent_group_id": "ag-456"}</system_response>
   ```
 
-**Batch formatting:** Multiple pending messages are combined into one prompt:
+**Batch formatting:** All pending messages are combined into one prompt. The prompt opens
+with a self-closing `<context timezone="<IANA>" />` header (so the agent interprets every
+timestamp — and every time it schedules — in the user's zone), then the chat messages
+concatenated as consecutive `<message>` blocks, then any task/webhook/system elements,
+joined by blank lines:
 
 ```xml
-<context timezone="America/Los_Angeles">
-<messages>
-<message sender="John" time="10:00">Check this PR</message>
-<message sender="Jane" time="10:01">Already on it</message>
-</messages>
+<context timezone="America/Los_Angeles" />
+<message id="2" from="family" sender="John" time="10:00">Check this PR</message>
+<message id="4" from="family" sender="Jane" time="10:01">Already on it</message>
 ```
 
-Mixed kinds (e.g., a chat message + a system response) are combined with clear delimiters. Each section is labeled by kind.
+There is **no** outer `<messages>` envelope — an earlier revision wrapped multi-message
+batches that way, but the Claude Agent SDK answered the wrapped shape with a synthetic
+"No response requested." stub instead of calling the API (#2555). Dropping the wrapper made
+the single-message path just the N=1 case of the same concatenation.
 
 **Command detection:** Messages starting with `/` are checked against a command list. Recognized commands bypass formatting and are passed raw to the provider (for Claude's slash command handling) or intercepted by the agent-runner (for NanoClaw-level commands like session reset).
 
@@ -430,54 +477,70 @@ interface RoutingContext {
 
 When writing messages_out (either from provider results or MCP tool calls), the agent-runner copies this routing context by default. The agent never sees routing fields — it just produces text. The routing is implicit: "respond to whoever sent the message."
 
-MCP tools that target a different destination (e.g., `send_to_agent`, `send_message` with explicit channel) override the routing context for that specific messages_out row.
+MCP tools that target a named destination (`send_message` / `send_file` with a `to`
+argument) resolve routing through the session's destination map instead of the default
+reply context — including agent-to-agent sends, which are just a `to` pointing at an
+`agent`-type destination.
 
 ### Status Management
 
-The agent-runner manages the `status` and `status_changed` fields on messages_in:
+`inbound.db` is a read-only mount inside the container, so the agent-runner never writes
+`messages_in`. It tracks processing status in the `processing_ack` table in the
+container-owned `outbound.db`; the host reads `processing_ack` and mirrors completion
+back onto `messages_in.status`.
 
 ```
-pending → processing → completed
-                    → failed (if provider returns error and max retries exhausted)
+processing_ack: (no row) → processing → completed
 ```
 
-- **Pick up:** `UPDATE messages_in SET status = 'processing', status_changed = now(), tries = tries + 1 WHERE id IN (...)`
-- **Complete:** `UPDATE messages_in SET status = 'completed', status_changed = now() WHERE id IN (...)`
-- **Error:** Agent-runner does NOT set `failed` — it leaves the message as `processing`. The host detects stale processing via `status_changed` and handles retry logic (reset to pending with backoff). This keeps retry policy on the host side.
+- **Pick up:** `INSERT OR REPLACE INTO processing_ack (message_id, status, status_changed) VALUES (?, 'processing', now())` for each claimed row (`markProcessing`). Pending queries skip any row already present in `processing_ack`.
+- **Complete:** same upsert with `status = 'completed'` (`markCompleted`). Every consumed batch ends here — error outcomes included. On a provider error the poll-loop writes an error **chat message** to `messages_out` (so the user sees it), then still acks the batch completed; errors surface as messages, not as an ack status. (A `markFailed` helper exists in `messages-in.ts` but currently has no callers.)
+- The host's `syncProcessingAcks` mirrors acked ids onto `messages_in.status = 'completed'`. Its stale/retry policy is driven off the `.heartbeat` file mtime and the `processing_ack` claim timestamps. On startup the agent-runner clears leftover `processing` acks (crash recovery) so orphaned claims re-process.
 
 ### MCP Tools
 
-The agent-runner runs an MCP server that exposes NanoClaw tools to the agent. All tools write to the session DB.
-
-**DB path:** The MCP server receives the session DB path via environment variable. It opens a second connection to the same SQLite file (WAL mode allows concurrent access).
+The agent-runner runs an MCP server (stdio) that exposes NanoClaw tools to the agent. The
+tool modules use the same two-DB connection layer as the rest of the runner
+(`container/agent-runner/src/db/connection.ts`): they read the host-written `inbound.db`
+at `/workspace/inbound.db` **read-only** (destinations, session routing, question
+responses, task lists) and write to the container-owned `outbound.db` at
+`/workspace/outbound.db`. There is no shared single-file connection and no WAL — both files
+are `journal_mode=DELETE` because WAL's memory-mapped `-shm` file does not stay coherent
+across the VirtioFS host↔container mount.
 
 #### send_message
 
-Send a chat message to the current conversation (or a specified destination).
+Send a chat message to a named destination. Agents address destinations by name, never by
+raw platform/channel/thread IDs — the destination map (`destinations` table in `inbound.db`,
+written by the host) resolves the name to routing fields.
 
 ```typescript
 {
   name: 'send_message',
   params: {
-    text: string,          // message content
-    channel?: string,      // optional: target channel type (default: reply to origin)
-    platformId?: string,   // optional: target platform ID
-    threadId?: string,     // optional: target thread ID
+    text: string,    // message content (required)
+    to?: string,     // destination name (e.g. "family", "worker-1").
+                     // Optional when the agent has exactly one destination.
   }
 }
 ```
 
-Implementation: write a `messages_out` row with `kind: 'chat'`. If channel/platformId/threadId are provided, use those as routing. Otherwise, copy from the current routing context.
+Implementation: `resolveRouting(to)` looks up the destination. With no `to`, it defaults to
+the session's own reply routing (`session_routing`); if the destination resolves to the same
+channel the session is bound to, the session's `thread_id` is preserved so the reply lands
+in-thread, otherwise `thread_id` is null. The tool then writes a `messages_out` row with
+`kind: 'chat'` and content `{ text }`, and returns the new `seq` as the message id.
 
 #### send_file
 
-Send a file to the current conversation.
+Send a file to a named destination (same destination model as `send_message`).
 
 ```typescript
 {
   name: 'send_file',
   params: {
-    path: string,          // file path (relative to /workspace/agent/ or absolute)
+    path: string,          // file path (relative to /workspace/agent/ or absolute) (required)
+    to?: string,           // destination name; optional if the agent has one destination
     text?: string,         // optional accompanying message
     filename?: string,     // display name (default: basename of path)
   }
@@ -485,10 +548,10 @@ Send a file to the current conversation.
 ```
 
 Implementation:
-1. Generate a message ID
-2. Create `outbox/{messageId}/` directory
-3. Copy the file into the outbox directory
-4. Write a `messages_out` row with `files: [filename]` in the content
+1. Resolve routing via `resolveRouting(to)` (as `send_message`)
+2. Generate a message ID and create `/workspace/outbox/{messageId}/`
+3. Copy the file into that outbox directory
+4. Write a `messages_out` row (`kind: 'chat'`) with content `{ text, files: [filename] }`
 
 #### send_card
 
@@ -523,11 +586,11 @@ Send an interactive question and wait for the user's response. This is a **block
 ```
 
 Implementation:
-1. Generate a `questionId`
-2. Write a `messages_out` row with `operation: 'ask_question'`, the question, options, and questionId
-3. Poll `messages_in` for a row with matching `questionId` in content
-4. When found, return the `selectedOption` as the tool result
-5. If timeout expires, return a timeout error as the tool result
+1. Generate a `questionId` and normalize each option to `{ label, selectedLabel, value }`
+2. Write a `messages_out` row with `kind: 'chat-sdk'` and content `{ type: 'ask_question', questionId, title, question, options }`
+3. Poll `inbound.db` (read-only) for a pending `messages_in` row whose content carries the matching `questionId` (`findQuestionResponse`), skipping any already in `processing_ack`
+4. When found, `markCompleted` the response row (a `processing_ack` write in `outbound.db`) and return its `selectedOption` as the tool result
+5. If the deadline passes, return a timeout error as the tool result
 
 The agent's execution is paused at this tool call. The provider's query keeps running (Claude holds the tool call open). The agent-runner polls for the response in a separate loop.
 
@@ -563,22 +626,13 @@ Add an emoji reaction to a message.
 
 Implementation: write a `messages_out` row with `operation: 'reaction'`.
 
-#### send_to_agent
+#### Agent-to-agent sends (no dedicated tool)
 
-Send a message to another agent group.
-
-```typescript
-{
-  name: 'send_to_agent',
-  params: {
-    agentGroupId: string,  // target agent group
-    text: string,          // message content
-    sessionId?: string,    // optional: target specific session
-  }
-}
-```
-
-Implementation: write a `messages_out` row with `channel_type: 'agent'`, `platform_id: agentGroupId`, `thread_id: sessionId`.
+There is no `send_to_agent` tool. Agents and channels share one destination namespace, so
+messaging another agent is just `send_message(to="<agent-name>")` where the named
+destination is of type `agent`. `resolveRouting` maps it to a `messages_out` row with
+`channel_type: 'agent'` and `platform_id` set to the target agent group id; the host
+validates the send and routes it into the target session's `inbound.db`.
 
 #### schedule_task
 
@@ -596,7 +650,7 @@ Schedule a one-shot or recurring task.
 }
 ```
 
-Implementation: write a `messages_in` row (to self) with `kind: 'task'`, `process_after`, and optionally `recurrence`. The host sweep picks it up when due.
+Implementation: the container can't write host-owned `inbound.db`, so this writes a `messages_out` row with `kind: 'system'` and `action: 'schedule_task'` (`container/agent-runner/src/mcp-tools/scheduling.ts`). During delivery the host's action handler (`src/modules/scheduling/actions.ts` → `insertTask()` in `src/modules/scheduling/db.ts`) inserts the `kind: 'task'` row into `inbound.db` with `process_after` and optionally `recurrence`. The host sweep picks it up when due.
 
 #### list_tasks
 
@@ -609,7 +663,7 @@ List active scheduled/recurring tasks.
 }
 ```
 
-Implementation: query `messages_in WHERE recurrence IS NOT NULL AND status != 'failed'`.
+Implementation: a read, not a write — the container may read the read-only `inbound.db` mount directly. Returns one row per series (the live pending/paused occurrence): `SELECT series_id AS id, ... FROM messages_in WHERE kind = 'task' AND status IN ('pending','paused') GROUP BY series_id`. See `container/agent-runner/src/mcp-tools/scheduling.ts`.
 
 #### cancel_task / pause_task / resume_task / update_task
 
@@ -625,27 +679,44 @@ Modify a scheduled task.
 // update_task: merge { prompt?, recurrence?, processAfter?, script? } into the live row
 ```
 
-Implementation: cancel/pause/resume update the live row(s) directly. update_task is sent as a system action — the host reads current content, merges supplied fields, and writes back. All four match by `(id = ? OR series_id = ?) AND kind='task' AND status IN ('pending','paused')`, so they reach the live next occurrence of a recurring task even when the agent passes the original (now-completed) id.
+Implementation: all four are sent as system actions (`messages_out`, `kind: 'system'`, `action: 'cancel_task' | 'pause_task' | 'resume_task' | 'update_task'`) — the container never writes `inbound.db`. The host's handlers in `src/modules/scheduling/actions.ts` apply the change against `inbound.db` via `src/modules/scheduling/db.ts`: cancel/pause/resume flip status on the live row(s); update_task reads current content, merges supplied fields, and writes back. All four match by `(id = ? OR series_id = ?) AND kind='task' AND status IN ('pending','paused')`, so they reach the live next occurrence of a recurring task even when the agent passes the original (now-completed) id.
 
-#### register_agent_group
+#### create_agent
 
-Register a new agent group (admin only).
+Create a long-lived companion sub-agent. The `name` becomes a destination the creating
+agent can address. (There is no `register_agent_group` tool — this replaced it.)
 
 ```typescript
 {
-  name: 'register_agent_group',
+  name: 'create_agent',
   params: {
-    name: string,
-    folder: string,
-    platformId: string,        // messaging group to wire to
-    channelType: string,
-    triggerRules?: object,
-    sessionMode?: 'shared' | 'per-thread',
+    name: string,           // human-readable name; also the destination name (required)
+    instructions?: string,  // CLAUDE.md content for the new agent (role, personality)
   }
 }
 ```
 
-Implementation: write a `messages_out` row with `kind: 'system'`, `action: 'register_agent_group'`. The host reads, validates admin permission, creates the entity rows in the central DB, and writes a `system` messages_in response.
+Implementation: fire-and-forget. Writes a `messages_out` row with `kind: 'system'`,
+`action: 'create_agent'`, `requestId`, `name`, and `instructions`. The container is
+untrusted and does not gate itself; the host authorizes by CLI scope — trusted owner groups
+(scope `global`) create directly, confined groups require admin approval
+(`src/modules/agent-to-agent/create-agent.ts`) — then creates the entity rows and notifies
+the agent via a chat message when the agent is ready.
+
+#### Self-modification: install_packages, add_mcp_server
+
+Two fire-and-forget system-action tools let an agent extend its own runtime (both require
+admin approval, applied host-side):
+
+- **`install_packages`** — `{ apt?: string[], npm?: string[], reason?: string }`. Package
+  names are validated at the tool boundary and re-validated on the host. On approval the
+  host rebuilds the per-agent image and restarts the container.
+- **`add_mcp_server`** — `{ name, command, args?, env? }`. Wires an existing third-party MCP
+  server into the agent's `container.json`; on approval the host updates the config and
+  restarts (no rebuild — Bun runs the TS directly).
+
+Both write a `messages_out` row with `kind: 'system'` and the matching `action`, then return
+immediately; the host notifies the agent when approval resolves.
 
 ### Media Handling
 
@@ -701,20 +772,28 @@ Archive location: `/workspace/agent/conversations/{date}-{summary}.md`
 
 ### Session Resume
 
-The agent-runner tracks `sessionId` and `resumeAt` across queries:
+The agent-runner tracks a single opaque `continuation` token per provider:
 
-- `sessionId` — captured from `ProviderEvent { type: 'init' }`. Passed back to `QueryInput.sessionId` on the next query.
-- `resumeAt` — Claude-specific (last assistant message UUID). Stored by the agent-runner, passed to `QueryInput.resumeAt`. Providers that don't support this ignore it.
+- Captured from `ProviderEvent { type: 'init', continuation }` and persisted to the
+  `session_state` table in `outbound.db` under the key `continuation:<provider>` (keyed per
+  provider because a continuation is provider-private — a Claude session id is meaningless to
+  another provider).
+- Passed back as `QueryInput.continuation` on the next query. For Claude that becomes the
+  SDK `resume` option; the SDK reloads its on-disk `.jsonl` transcript for that session id.
 
-These are ephemeral to the container's lifetime. When the container is killed and restarted, the host passes the stored `sessionId` from the central DB's sessions table. `resumeAt` is lost on container restart (the provider resumes from the end of the session).
+Because it lives in the session folder's `outbound.db`, the continuation survives container
+teardown and restart — a fresh container reads it back and resumes. `/clear` deletes the row
+to start a clean session. Before resuming, `maybeRotateContinuation` may archive and drop an
+oversized/aged transcript (so a cold container isn't killed reloading it), and
+`isSessionInvalid` clears a continuation whose backing transcript has gone missing.
 
 ### Container Startup
 
 The agent-runner receives configuration via:
 
-- **Environment variables:** `AGENT_PROVIDER` (claude/codex/opencode), `NANOCLAW_ADMIN_USER_ID`, provider-specific vars (API keys, model overrides), `TZ`
-- **Fixed mount paths:** Session DB at `/workspace/session.db`. Agent group folder at `/workspace/agent/`. System prompt from `/workspace/agent/CLAUDE.md` and `/workspace/global/CLAUDE.md`.
-- **Optional startup config:** Some config may be passed as a JSON file at a fixed path (e.g., `/workspace/config.json`) for things like the session ID to resume, assistant name, and admin user ID. This avoids overloading environment variables.
+- **`container.json`:** The provider name, model, assistant name, MCP servers, and other NanoClaw config are read from `/workspace/agent/container.json` (materialized by the host from the `container_configs` table), not from environment variables. See `container/agent-runner/src/config.ts`.
+- **Environment variables:** provider-specific vars only (API keys, model overrides), `TZ`.
+- **Fixed mount paths:** Host-written `inbound.db` (read-only) at `/workspace/inbound.db` and container-owned `outbound.db` at `/workspace/outbound.db`. Agent group folder at `/workspace/agent/`. System prompt from `/workspace/agent/CLAUDE.md` and `/workspace/global/CLAUDE.md`.
 
 The agent-runner reads config, creates the provider, and enters the poll loop. No stdin, no initial prompt — messages are already in the session DB.
 
@@ -731,7 +810,7 @@ function createProvider(name: ProviderName, config: ProviderConfig): AgentProvid
 }
 ```
 
-The provider name comes from the container's environment (`AGENT_PROVIDER` env var), set by the host based on `agent_groups.agent_provider` or `sessions.agent_provider`.
+The provider name comes from the `provider` key in `/workspace/agent/container.json` (defaulting to `'claude'`), which the host materializes from the `container_configs` table — set it with `ncl groups config update --provider`. It is not an environment variable.
 
 `ProviderConfig` contains provider-specific settings (API keys, model overrides, etc.) passed via environment variables — not via the interface. Each provider reads what it needs from `env`.
 

docs/api-details.md

@@ -13,6 +13,8 @@ interface ChannelSetup {
 
   // Host callbacks
   onInbound(platformId: string, threadId: string | null, message: InboundMessage): void;
+  // Admin-transport adapters (e.g. CLI) route to an arbitrary channel via this instead of onInbound
+  onInboundEvent(event: InboundEvent): void;
   onMetadata(platformId: string, name?: string, isGroup?: boolean): void;
 }
 
@@ -34,7 +36,7 @@ interface ChannelAdapter {
   isConnected(): boolean;
 
   // Outbound delivery
-  deliver(platformId: string, threadId: string | null, message: OutboundMessage): Promise<void>;
+  deliver(platformId: string, threadId: string | null, message: OutboundMessage): Promise<string | undefined>;
 
   // Optional
   setTyping?(platformId: string, threadId: string | null): Promise<void>;
@@ -307,7 +309,7 @@ function createWhatsAppChannel(): ChannelAdapter {
 **Ask user question:**
 ```json
 {
-  "operation": "ask_question",
+  "type": "ask_question",
   "questionId": "q-123",
   "title": "Failing Test",
   "question": "How should we handle the failing test?",

docs/architecture-diagram.html

@@ -311,7 +311,6 @@ erDiagram
     string name
     string folder
     string agent_provider
-    json container_config
   }
   messaging_groups {
     int id
@@ -344,14 +343,15 @@ erDiagram
     int messaging_group_id
     int agent_group_id
     string session_mode
-    json trigger_rules
+    string engage_mode "pattern | mention | mention-sticky"
+    string sender_scope "all | known"
     int priority
   }
   sessions {
     int id
     int agent_group_id
     int messaging_group_id
-    string sdk_session_id
+    string thread_id
     string status
   }
 </pre>
@@ -391,7 +391,7 @@ flowchart LR
   Container -->|writes · odd seq| Out
   Container -->|touch every poll| HB
   HostSweep[Host sweep] -->|stat mtime| HB
-  HostSweep -->|reads processing_ack| In
+  HostSweep -->|reads processing_ack| Out
 </pre>
         </div>
       </section>

docs/architecture-diagram.md

@@ -28,18 +28,18 @@ flowchart TB
     Approvals["configureManualApproval<br/>-> pending_approvals"]
   end
 
-  subgraph Session["Per-Session Container (Docker / Apple Container)"]
+  subgraph Session["Per-Session Container (Docker)"]
     direction TB
     PollLoop["Poll Loop<br/>(container/agent-runner)"]
-    Provider["Agent providers<br/>(claude, opencode, mock; todo: codex)"]
+    Provider["Agent providers<br/>(claude — the only one registered in trunk;<br/>opencode ships via the /add-opencode skill)"]
     MCP["MCP Tools<br/>send_message, send_file, edit_message,<br/>add_reaction, send_card, ask_user_question,<br/>schedule_task, create_agent,<br/>install_packages, add_mcp_server"]
     Skills["Container Skills<br/>(container/skills/)"]
-    InDB[("inbound.db<br/>host writes<br/>even seq<br/>messages_in<br/>destinations<br/>processing_ack")]
-    OutDB[("outbound.db<br/>container writes<br/>odd seq<br/>messages_out<br/>heartbeat file")]
+    InDB[("inbound.db<br/>host writes<br/>even seq<br/>messages_in<br/>delivered<br/>destinations<br/>session_routing")]
+    OutDB[("outbound.db<br/>container writes<br/>odd seq<br/>messages_out<br/>processing_ack<br/>session_state<br/>container_state<br/>heartbeat file")]
   end
 
   subgraph Groups["Agent Group Filesystem (groups/*)"]
-    Folder["CLAUDE.md<br/>memory<br/>per-group skills<br/>container_config"]
+    Folder["CLAUDE.md<br/>memory<br/>per-group skills<br/>container.json (materialized from container_configs)"]
   end
 
   P1 & P2 & P3 & P4 & P5 --> Bridge
@@ -140,7 +140,6 @@ erDiagram
     string name
     string folder
     string agent_provider
-    json container_config
   }
   messaging_groups {
     int id
@@ -173,14 +172,15 @@ erDiagram
     int messaging_group_id
     int agent_group_id
     string session_mode "agent-shared | shared | per-thread"
-    json trigger_rules
+    string engage_mode "pattern | mention | mention-sticky"
+    string sender_scope "all | known"
     int priority
   }
   sessions {
     int id
     int agent_group_id
     int messaging_group_id
-    string sdk_session_id
+    string thread_id
     string status
   }
 ```
@@ -209,7 +209,7 @@ flowchart LR
   Container -->|"writes only<br/>(odd seq)"| Out
   Container -->|touch every poll| HB
   HostSweep[Host sweep] -->|stat mtime| HB
-  HostSweep -->|reads processing_ack| In
+  HostSweep -->|reads processing_ack| Out
 
   note1["Each file has exactly ONE writer.<br/>Eliminates SQLite cross-process write contention.<br/>Collision-free seq numbering."]
 ```

docs/architecture.md

@@ -1,8 +1,20 @@
 # NanoClaw Architecture (Draft)
 
+> **Draft — design intent, not a line-by-line spec.** Some passages predate the current implementation and can drift from it. The root [CLAUDE.md](../CLAUDE.md) and the cited source files (`src/`, `container/agent-runner/src/`) are the source of truth; when this doc and the code disagree, trust the code. Notably, scheduling MCP tools do **not** write `inbound.db` directly — they emit `messages_out` system actions that the host applies (see [agent-runner-details.md](agent-runner-details.md) and `src/modules/scheduling/`).
+
 ## Core Idea
 
-Each agent session has a mounted SQLite DB. The DB is the one and only IO mechanism between host and container. No IPC files, no stdin piping. Two tables: messages_in (host → agent-runner) and messages_out (agent-runner → host). Everything is a message.
+Each agent session has a **pair** of mounted SQLite DBs. They are the one and only IO
+mechanism between host and container. No IPC files, no stdin piping. `inbound.db` carries
+host → agent-runner messages (`messages_in`); `outbound.db` carries agent-runner → host
+messages (`messages_out`) plus the container's processing acks. Everything is a message.
+
+The split exists so each file has exactly one writer: the host writes `inbound.db` (the
+container opens it read-only) and the container writes `outbound.db` (the host opens it
+read-only). One writer per file means no cross-process lock contention over the
+host↔container mount. Both files run `journal_mode=DELETE`, **not** WAL: WAL's memory-mapped
+`-shm` coherency does not propagate across VirtioFS, so a WAL reader in the guest would
+freeze on an early snapshot and never see new host writes.
 
 ## Two-Level DB
 
@@ -11,15 +23,18 @@ Each agent session has a mounted SQLite DB. The DB is the one and only IO mechan
 - Maps platform IDs → agent groups → sessions
 - Channel adapters don't touch this directly — the host does the lookup
 
-**Per-session DB (mounted into container):**
-- messages_in (written by host, read by agent-runner)
-- messages_out (written by agent-runner, read by host)
-- Everything is a message: chat, tasks, webhooks, system actions, agent-to-agent — all use these two tables
-- One DB per session, not per agent group
+**Per-session DBs (mounted into container):**
+- `inbound.db` → `messages_in` (written by host, read-only in container) plus host-written
+  lookup tables the container reads live: `destinations`, `session_routing`, `delivered`
+- `outbound.db` → `messages_out` (written by agent-runner, read by host) plus
+  `processing_ack`, `session_state`, and `container_state` (all container-owned)
+- Everything is a message: chat, tasks, webhooks, system actions, agent-to-agent — all use
+  `messages_in` / `messages_out`
+- One pair per session, not per agent group
 
 ## Agent Groups vs Sessions
 
-An agent group has its own filesystem — folder, CLAUDE.md, skills, container config. Multiple sessions can share the same agent group (same filesystem, same skills) but each session gets its own DB mounted at a known path. Each session = a separate container with the same agent group's filesystem but a different session DB.
+An agent group has its own filesystem — folder, CLAUDE.md, skills, container config. Multiple sessions can share the same agent group (same filesystem, same skills) but each session gets its own `inbound.db`/`outbound.db` pair mounted at known paths. Each session = a separate container with the same agent group's filesystem but a different DB pair.
 
 ## Message Flow
 
@@ -28,13 +43,13 @@ Platform event
   → Channel adapter (trigger check, ID extraction)
   → Returns: { platformChannelId, platformThreadId, triggered }
   → Host maps platformChannelId + platformThreadId → agent group + session
-  → Host writes message to session's DB
+  → Host writes messages_in row to the session's inbound.db
   → Host calls wakeUpAgent(session)
   → Container spins up (or is already running)
-  → Agent-runner polls its session DB, finds new messages
-  → Agent-runner processes with Claude
-  → Agent-runner writes response to session DB
-  → Host polls active session DBs for responses
+  → Agent-runner polls inbound.db (read-only), finds new messages
+  → Agent-runner processes with the configured provider
+  → Agent-runner writes response to messages_out in outbound.db
+  → Host polls active sessions' outbound.db for responses
   → Host reads response, looks up conversation, delivers through channel adapter
 ```
 
@@ -128,9 +143,8 @@ Non-Chat-SDK channels (WhatsApp via Baileys, Gmail, custom integrations) impleme
 The host is an orchestrator:
 1. **Spawn** — when wakeUpAgent is called and no container exists for the session
 2. **Idle kill** — when a container has no unprocessed messages for some timeout period
-3. **Limits** — MAX_CONCURRENT_CONTAINERS caps active containers
 
-When a container spins up, the agent-runner immediately starts polling its session DB. Messages are already there waiting.
+When a container spins up, the agent-runner immediately starts polling `inbound.db`. Messages are already there waiting.
 
 ## Media Handling
 
@@ -184,50 +198,66 @@ Dedup is the channel adapter's responsibility. Chat SDK handles this internally.
 
 ## Session DB Schema
 
-Two tables. JSON blobs for content — schema-free, format varies by `kind`.
+Split across the two files. JSON blobs for content — schema-free, format varies by `kind`.
+`seq` is a global ordering counter with a **disjoint parity**: the host writes even seqs to
+`messages_in`, the container writes odd seqs to `messages_out`. Each side reads the other's
+MAX(seq) to pick its next value, so seq is a single monotonic message id across both tables —
+which is why the agent-facing message id it returns from `send_message` (and accepts in
+`edit_message` / `add_reaction`) is unambiguous.
 
 ```sql
--- Host writes, agent-runner reads
+-- inbound.db — host writes, container opens read-only
 CREATE TABLE messages_in (
   id             TEXT PRIMARY KEY,
+  seq            INTEGER UNIQUE,     -- even (host-assigned)
   kind           TEXT NOT NULL,      -- 'chat' | 'chat-sdk' | 'task' | 'webhook' | 'system'
   timestamp      TEXT NOT NULL,
-  status         TEXT DEFAULT 'pending',  -- 'pending' | 'processing' | 'completed' | 'failed'
-  status_changed TEXT,               -- ISO timestamp of last status change
+  status         TEXT DEFAULT 'pending',  -- host-owned; the host mirrors the container's
+                                          -- processing_ack terminal states onto this column
   process_after  TEXT,               -- ISO timestamp. NULL = process immediately.
   recurrence     TEXT,               -- cron expression. NULL = one-shot.
+  series_id      TEXT,               -- groups a recurring task's occurrences
   tries          INTEGER DEFAULT 0,  -- number of processing attempts
-
-  -- routing (agent-runner copies to messages_out; agent never sees these)
-  platform_id    TEXT,
+  trigger        INTEGER NOT NULL DEFAULT 1,  -- 0 = accumulated context (don't wake), 1 = wake
+  platform_id    TEXT,               -- routing (stripped before the agent sees content)
   channel_type   TEXT,
   thread_id      TEXT,
-
-  -- payload (structure depends on kind)
-  content        TEXT NOT NULL        -- JSON blob
+  content        TEXT NOT NULL,      -- JSON blob (structure depends on kind)
+  source_session_id TEXT,            -- a2a return path: source session that emitted the trigger
+  on_wake        INTEGER NOT NULL DEFAULT 0  -- 1 = only deliver on a container's first poll
 );
 
--- Agent-runner writes, host reads
+-- outbound.db — container writes, host opens read-only
 CREATE TABLE messages_out (
   id             TEXT PRIMARY KEY,
-  in_reply_to    TEXT,               -- references messages_in.id (optional)
+  seq            INTEGER UNIQUE,     -- odd (container-assigned)
+  in_reply_to    TEXT,              -- references messages_in.id (optional)
   timestamp      TEXT NOT NULL,
-  delivered      INTEGER DEFAULT 0,
-  deliver_after  TEXT,               -- ISO timestamp. NULL = deliver immediately.
-  recurrence     TEXT,               -- cron expression. NULL = one-shot.
-
-  -- routing (default: copied from messages_in by agent-runner)
-  kind           TEXT NOT NULL,      -- 'chat' | 'chat-sdk' | 'task' | 'webhook' | 'system'
-  platform_id    TEXT,
+  deliver_after  TEXT,              -- ISO timestamp. NULL = deliver immediately.
+  recurrence     TEXT,              -- cron expression. NULL = one-shot.
+  kind           TEXT NOT NULL,     -- copied from messages_in by default
+  platform_id    TEXT,              -- routing (default: copied from messages_in)
   channel_type   TEXT,
   thread_id      TEXT,
-
-  -- payload (format matches kind)
-  content        TEXT NOT NULL        -- JSON blob
+  content        TEXT NOT NULL      -- JSON blob (format matches kind)
 );
 
+-- outbound.db — container's processing status (it can't write inbound.db).
+-- Host reads this to drive the message lifecycle; stale 'processing' rows are
+-- cleared on container startup (crash recovery).
+CREATE TABLE processing_ack (
+  message_id     TEXT PRIMARY KEY,  -- references messages_in.id
+  status         TEXT NOT NULL,     -- 'processing' | 'completed' | 'failed'
+  status_changed TEXT NOT NULL
+);
 ```
 
+Delivery is tracked host-side in a `delivered` table in `inbound.db` (not a column on
+`messages_out`, which the host can't write). `inbound.db` also holds the host-written
+`destinations` and `session_routing` tables the container reads live; `outbound.db` also
+holds `session_state` (the resume continuation, per provider) and `container_state`
+(current tool in flight).
+
 ### Scheduling
 
 One-shot and recurring tasks use the same tables — no separate scheduler.
@@ -236,15 +266,15 @@ One-shot and recurring tasks use the same tables — no separate scheduler.
 
 **Recurring:** Same, plus a `recurrence` cron expression. After the host marks a row as handled/delivered, if `recurrence` is set, it inserts a new row with `process_after`/`deliver_after` advanced to the next cron occurrence. Next time is computed from the scheduled time (not wall clock) to prevent drift.
 
-**Host sweep** (every ~60s across all session DBs):
-- `messages_in WHERE status = 'pending' AND (process_after IS NULL OR process_after <= now())` → wake agent
-- `messages_in WHERE status = 'processing' AND status_changed < (now - stale_threshold)` → stale detection, increment tries, reset to pending with backoff
-- `messages_out WHERE delivered = 0 AND (deliver_after IS NULL OR deliver_after <= now())` → deliver
+**Host sweep** (every ~60s across all sessions):
+- `inbound.db` → `messages_in WHERE status = 'pending' AND (process_after IS NULL OR process_after <= now())` → wake agent
+- A `processing_ack` (in `outbound.db`) whose claim, or the `.heartbeat` mtime, is older than the stale threshold → stale detection, increment tries, reschedule `process_after` with backoff
+- `outbound.db` → due `messages_out` rows not yet in the host's `delivered` table (in `inbound.db`) → deliver
 - After completing/delivering a row with `recurrence`, insert next occurrence
 
 **Active container poll** (~1s) checks the same conditions but only for sessions with running containers.
 
-**Agent-runner creates schedules** by writing messages_in (to itself) or messages_out (reminders/notifications) with `process_after` and optionally `recurrence`.
+**Agent-runner creates schedules** by emitting a `messages_out` row with `kind: 'system'` and an `action` (`schedule_task`, `cancel_task`, …) — it cannot write host-owned `inbound.db` directly. The host applies the action during delivery (`src/modules/scheduling/actions.ts`), inserting/updating the `kind: 'task'` `messages_in` row with `process_after` and optionally `recurrence`.
 
 ### messages_in content by kind
 
@@ -331,7 +361,7 @@ Two patterns, both handled at the host level:
 
 In both cases, the approval and action execution happen on the host side, not the agent side.
 
-**Approval routing:** Privilege is a user-level concept. `user_roles` records `owner` (global only — first user to pair becomes owner) and `admin` (global or scoped to a specific `agent_group_id`). When an action requires approval, `pickApprover(agentGroupId)` returns candidates in order: scoped admins for that agent group → global admins → owners (deduplicated). `pickApprovalDelivery` then takes the first candidate reachable via `ensureUserDm` (with a same-channel-kind tie-break so a Discord approval request prefers a Discord-using approver). The approval card lands in the approver's DM messaging group, not the origin chat. Delivery is resolved through the Chat SDK's `openDM` for resolution-required channels (Discord/Slack/…) or the user's handle directly for direct-addressable channels (Telegram/WhatsApp/…), and the mapping is cached in `user_dms` for subsequent requests. See `src/access.ts`, `src/user-dm.ts`.
+**Approval routing:** Privilege is a user-level concept. `user_roles` records `owner` (global only — first user to pair becomes owner) and `admin` (global or scoped to a specific `agent_group_id`). When an action requires approval, `pickApprover(agentGroupId)` returns candidates in order: scoped admins for that agent group → global admins → owners (deduplicated). `pickApprovalDelivery` then takes the first candidate reachable via `ensureUserDm` (with a same-channel-kind tie-break so a Discord approval request prefers a Discord-using approver). The approval card lands in the approver's DM messaging group, not the origin chat. Delivery is resolved through the Chat SDK's `openDM` for resolution-required channels (Discord/Slack/…) or the user's handle directly for direct-addressable channels (Telegram/WhatsApp/…), and the mapping is cached in `user_dms` for subsequent requests. See `src/modules/permissions/access.ts` and `src/modules/permissions/user-dm.ts` (`ensureUserDm`); the approver-picking primitives live in `src/modules/approvals/primitive.ts`.
 
 **Editing a sent message:**
 
@@ -408,14 +438,16 @@ This is documented as a pattern, not a built-in feature.
 
 ## Design Decisions
 
-**Session DB location:** Not in the agent group folder. Separate directory (e.g., `sessions/{session_id}/`). Each session gets its own folder containing `session.db` and the Claude SDK's `.claude/` directory. The session identity IS the folder — no need to track Claude SDK session IDs.
+**Session DB location:** Not in the agent group folder. Separate directory (e.g., `sessions/{session_id}/`). Each session gets its own folder containing `inbound.db`, `outbound.db`, and — when using the claude provider — the SDK's `.claude/` directory. The session identity IS the folder. The SDK's resume token (session id) is persisted in `outbound.db`'s `session_state` table, so a fresh container picks the conversation back up without the host tracking it centrally.
 
 **Container mount structure:**
 
 ```
 /workspace/                 ← mount: session folder (read-write)
-  .claude/                  ← Claude SDK session data (auto-created)
-  session.db                ← session SQLite DB
+  .claude/                  ← Claude SDK session data / transcripts (auto-created)
+  inbound.db                ← host writes, container reads (opened read-only)
+  outbound.db               ← container writes, host reads (opened read-only)
+  .heartbeat                ← container touches this; host watches its mtime
   outbox/                   ← agent-runner writes outbound files here
   agent/                    ← mount: agent group folder (nested, read-write)
     CLAUDE.md               ← agent instructions
@@ -423,11 +455,17 @@ This is documented as a pattern, not a built-in feature.
     ... working files
 ```
 
-Two directory mounts: session folder at `/workspace`, agent group folder at `/workspace/agent/`. The agent-runner CDs into `/workspace/agent/` to run the agent. Claude SDK writes `.claude/` at `/workspace/.claude/` (root of the workspace). The session DB is at `/workspace/session.db`.
+Two directory mounts: session folder at `/workspace`, agent group folder at `/workspace/agent/`. The agent-runner CDs into `/workspace/agent/` to run the agent. Claude SDK writes `.claude/` at `/workspace/.claude/` (root of the workspace).
 
-This works on both Docker (nested bind mounts) and Apple Container (directory mounts only — no file-level mounts, but nested directory mounts are supported).
+The runtime is Docker (`src/container-runtime.ts` hardcodes the `docker` binary); nested bind mounts make this layout straightforward. The layout deliberately sticks to directory mounts (no file-level mounts) so it stays portable to runtimes that only support directory mounts.
 
-**Session DB concurrent access:** The host writes messages_in, the agent-runner writes messages_out. Both access the same SQLite file simultaneously. WAL mode handles this — SQLite allows concurrent readers, and the two sides write to different tables so writer contention is minimal. The host enables WAL mode when creating the session DB.
+**Cross-mount DB access:** The two files exist precisely so each has a single writer — the
+host writes `inbound.db`, the container writes `outbound.db` — which removes writer
+contention across the mount. Both files use `journal_mode=DELETE`, **not** WAL: WAL keeps its
+index in a memory-mapped `-shm` file, and VirtioFS does not propagate that mmap coherency
+from host to guest, so a WAL reader in the container would freeze on an early snapshot and
+silently never see new host writes. Readers that must see fresh host writes promptly (the
+`messages_in` poll) open `inbound.db` with `mmap_size = 0` to bypass SQLite's page cache.
 
 **Session management:** Host-managed. The host creates session folders and mounts them. The container only sees its own session folder.
 
@@ -438,7 +476,7 @@ This works on both Docker (nested bind mounts) and Apple Container (directory mo
 3. More messages arrive before container starts → host finds the existing session, writes to the same session DB
 4. Container starts, mounts the folder, agent-runner finds messages waiting
 
-The central DB session row creation is the serialization point. No Claude SDK session ID to coordinate — the SDK discovers its own session data in `.claude/` when the agent runs.
+The central DB session row creation is the serialization point. No provider session ID to coordinate — the SDK discovers its own session data in `.claude/` when the agent runs.
 
 **System actions:** The agent uses MCP tools (register group, reset session, schedule task, etc.). The agent-runner handles these tool calls and writes a structured, deterministic messages_out row with `kind: 'system'`. This is not natural language — it's a programmatic, structured payload that the host processes deterministically. Host validates permissions, executes, and writes the result back as a `system` messages_in row.
 
@@ -448,7 +486,9 @@ The central DB session row creation is the serialization point. No Claude SDK se
 
 ### Output Delivery
 
-NanoClaw does not stream tokens to users. The Claude Agent SDK's `query()` yields complete results. The agent-runner writes one complete message to messages_out per result. The host delivers complete messages to channels.
+NanoClaw does not stream tokens to users. The provider's query interface yields complete results, but a result's text is not delivered as-is: the agent-runner parses it for `<message to="name">...</message>` blocks (`dispatchResultText` in poll-loop.ts) and writes one messages_out row per block, addressed to that destination with its thread context resolved per destination. Everything outside a block — including `<internal>...</internal>` — is scratchpad: logged, never sent. A block naming an unknown destination is dropped into the scratchpad log.
+
+If a result produced text but no valid block, the agent-runner pushes a one-time `<system>` nudge into the live turn asking the agent to re-wrap its response. The exception is a non-retryable error result (e.g. a billing error) with no envelope, which is delivered as an error notice instead of being dropped as scratchpad. Mid-turn interim updates go out through the `send_message` MCP tool; the final-text envelope parsing is how a turn's reply reaches the user. The host delivers complete messages_out rows to channels.
 
 Message editing is supported as an explicit operation (agent calls an `edit_message` tool), not as a streaming mechanism.
 
@@ -456,21 +496,30 @@ Typing indicators: host sets typing when a container is active for a session, cl
 
 ### Message Batching
 
-When multiple messages arrive while the container is down, they accumulate as `handled = 0` rows in messages_in. When the container wakes up, the agent-runner queries all unhandled messages and processes them as a batch — multiple messages are formatted into a single `<messages>` XML block.
+When multiple messages arrive while the container is down, they accumulate as `status = 'pending'` rows in `messages_in`. When the container wakes up, the agent-runner reads all pending messages (those not yet in `processing_ack`) and processes them as a batch — formatted as a `<context timezone="…" />` header followed by the messages concatenated as consecutive `<message>` blocks. (There is no `<messages>` wrapper element; see [agent-runner-details.md](agent-runner-details.md#message-formatting).)
 
 ### Message Lifecycle
 
 ```
-pending → processing → completed
-                    → failed (after max retries)
+messages_in.status:   pending ──────────► completed (mirrored from ack)
+                              └─────────► failed (host-set, retries exhausted)
+processing_ack.status:         processing → completed
 ```
 
-- **pending**: Written by host. Ready to be picked up (if `process_after` is null or past).
-- **processing**: Agent-runner sets this when it picks up the message. `status_changed` is set to now. Prevents other polls from re-picking the same message.
-- **completed**: Agent-runner sets this after successful processing.
-- **failed**: Set after max retries exhausted.
+Because `inbound.db` is read-only in the container, the agent-runner never mutates
+`messages_in.status`. It records lifecycle in `processing_ack` (in `outbound.db`); the host
+reads that and mirrors completion back.
 
-**Stale detection**: If a message is `processing` but `status_changed` is too old (e.g., >10 minutes), the host assumes the container crashed. It resets the message to `pending`, increments `tries`, and sets `process_after` with exponential backoff.
+- **pending**: Host writes the `messages_in` row. Ready to be picked up (if `process_after` is null or past).
+- **processing**: Agent-runner upserts a `processing_ack` row (`status = 'processing'`) when it claims the message. Subsequent polls skip any id already in `processing_ack`, so it isn't re-picked.
+- **completed**: Agent-runner sets `processing_ack.status = 'completed'` for **every** consumed batch, error outcomes included — a provider error is surfaced to the user as an error chat message in `messages_out`, then the batch is still acked completed. The host's `syncProcessingAcks` copies it onto `messages_in.status`.
+- **failed**: Set by the **host** (sweep's `markMessageFailed`) when retries are exhausted — never by the container.
+
+**Liveness / stale detection**: The container touches a `/workspace/.heartbeat` file rather
+than writing the DB. The host sweep watches that mtime (widening its tolerance when
+`container_state` shows a long-declared Bash running) to decide a container has crashed, then
+increments `tries` and reschedules `process_after` with exponential backoff. On the next
+container startup, leftover `processing` acks are cleared so orphaned claims re-process.
 
 ### Error Handling and Retries
 
@@ -555,7 +604,7 @@ const DISCORD_TOKEN = process.env.DISCORD_BOT_TOKEN;
 const GMAIL_CREDS = process.env.GMAIL_CREDENTIALS_PATH;
 ```
 
-Shared config (DATA_DIR, TIMEZONE, MAX_CONCURRENT_CONTAINERS) stays in `config.ts`. Channel/skill-specific config stays in the module that uses it.
+Shared config (DATA_DIR, TIMEZONE) stays in `config.ts`. Channel/skill-specific config stays in the module that uses it.
 
 ### Code Style
 
@@ -594,13 +643,15 @@ src/db/
 - **No inline ALTER TABLE.** A migration runner with a `schema_version` table replaces `try { ALTER TABLE } catch { /* exists */ }` blocks. On startup, it checks the current version and applies pending migrations in order. Each migration is a function: `(db: Database) => void`.
 - **Skills add migrations.** A skill that needs a new column adds a new numbered migration file. No conflicts with other skills' migrations as long as numbers don't collide (use timestamps or high-enough numbers for skill branches).
 
-**Agent-runner session DB** uses the same pattern but lighter — no migrations needed since session DBs are created fresh by the host:
+**Agent-runner session DBs** use the same pattern but lighter — no migrations needed since the DB files are created fresh by the host:
 
 ```
 container/agent-runner/src/db/
-  connection.ts          ← open session.db at fixed path, WAL mode
-  messages-in.ts         ← read pending, update status
-  messages-out.ts        ← write results, outbox queries
+  connection.ts          ← open inbound.db (read-only) + outbound.db (DELETE mode) at fixed paths
+  messages-in.ts         ← read pending from inbound.db, ack via processing_ack in outbound.db
+  messages-out.ts        ← write results/outbox rows to outbound.db (odd seq)
+  session-state.ts       ← resume continuation, keyed per provider
+  session-routing.ts     ← read the host-written default reply routing
   index.ts               ← barrel
 ```
 
@@ -663,9 +714,13 @@ CREATE TABLE agent_groups (
   name             TEXT NOT NULL,
   folder           TEXT NOT NULL UNIQUE,
   agent_provider   TEXT,              -- default for sessions (null = system default)
-  container_config TEXT,              -- JSON: { additionalMounts, timeout }
   created_at       TEXT NOT NULL
 );
+-- Container config is NOT a column here — it lives in a separate container_configs
+-- table (migration 014), keyed by agent_group_id, with columns: provider, model,
+-- effort, image_tag, assistant_name, max_messages_per_prompt, cli_scope, and JSON
+-- columns skills / mcp_servers / packages_apt / packages_npm / additional_mounts.
+-- The host materializes it into /workspace/agent/container.json for the container.
 
 -- Platform groups/channels (WhatsApp group, Slack channel, Discord channel, email thread, etc.)
 -- One row per chat PER ADAPTER INSTANCE. instance defaults to channel_type
@@ -720,16 +775,21 @@ CREATE TABLE user_dms (
   PRIMARY KEY (user_id, channel_type)
 );
 
--- Which agent groups handle which messaging groups, with what rules
+-- Which agent groups handle which messaging groups, with what rules.
+-- The opaque trigger_rules JSON + response_scope enum were replaced (migration
+-- 010) by four orthogonal axes:
 CREATE TABLE messaging_group_agents (
-  id                 TEXT PRIMARY KEY,
-  messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
-  agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
-  trigger_rules      TEXT,              -- JSON: { pattern, mentionOnly, excludeSenders, includeSenders }
-  response_scope     TEXT DEFAULT 'all',    -- 'all' | 'triggered' | 'allowlisted'
-  session_mode       TEXT DEFAULT 'shared', -- 'shared' | 'per-thread'
-  priority           INTEGER DEFAULT 0,     -- higher = checked first when multiple agents match
-  created_at         TEXT NOT NULL,
+  id                     TEXT PRIMARY KEY,
+  messaging_group_id     TEXT NOT NULL REFERENCES messaging_groups(id),
+  agent_group_id         TEXT NOT NULL REFERENCES agent_groups(id),
+  engage_mode            TEXT NOT NULL DEFAULT 'mention',  -- 'pattern' | 'mention' | 'mention-sticky'
+  engage_pattern         TEXT,                             -- regex; required for engage_mode='pattern'
+                                                           -- ('.' = match every message, the "always" flavor)
+  sender_scope           TEXT NOT NULL DEFAULT 'all',      -- 'all' | 'known'
+  ignored_message_policy TEXT NOT NULL DEFAULT 'drop',     -- 'drop' | 'accumulate'
+  session_mode           TEXT DEFAULT 'shared',            -- 'shared' | 'per-thread'
+  priority               INTEGER DEFAULT 0,                -- higher = checked first when multiple agents match
+  created_at             TEXT NOT NULL,
   UNIQUE(messaging_group_id, agent_group_id)
 );
 
@@ -794,7 +854,7 @@ stopped → running → idle → stopped
 
 ## Agent-Runner Architecture
 
-The agent-runner is the process inside the container. It mediates between the session DB and the Claude SDK — polling for work, formatting messages for the agent, translating tool calls into DB rows, and managing the agent lifecycle.
+The agent-runner is the process inside the container. It mediates between the session DB and the agent provider — polling for work, formatting messages for the agent, translating tool calls into DB rows, and managing the agent lifecycle.
 
 ### IO Model
 
@@ -807,50 +867,58 @@ All IO goes through the session DB. No stdin, no stdout markers, no IPC files.
 
 ### Poll Loop
 
-1. Query `messages_in WHERE status = 'pending' AND (process_after IS NULL OR process_after <= now())`
-2. If rows found: set `status = 'processing'`, `status_changed = now()` on each
+1. Query `inbound.db` (read-only) for `messages_in WHERE status = 'pending' AND (process_after IS NULL OR process_after <= now())`, skipping any id already in `processing_ack`
+2. If rows found: upsert `processing_ack` rows with `status = 'processing'` in `outbound.db` (the container can't write `messages_in`)
 3. Batch messages into a single prompt (strip routing fields, format by kind)
-4. Push into Claude SDK's MessageStream
+4. Push into the provider's input stream
 5. Process agent output → write `messages_out` rows
-6. Set processed messages to `status = 'completed'`
+6. Set the processed ids' `processing_ack.status = 'completed'` (the host mirrors that onto `messages_in.status`)
 7. Back to step 1. If no messages found, sleep briefly and re-poll (container stays warm for idle timeout)
 
 ### Message Formatting by Kind
 
 Agent-runner strips routing fields (`platform_id`, `channel_type`, `thread_id`) before formatting. The agent never sees routing info — it only sees content.
 
-- **`chat`** — format into `<messages>` XML block
-- **`chat-sdk`** — extract text, author, attachments from serialized message; format into `<messages>` XML
-- **`task`** — format as `[SCHEDULED TASK]` prefix + prompt. Run pre-script if present.
-- **`webhook`** — format as `[WEBHOOK: source/event]` + JSON payload
-- **`system`** — host action results (e.g., "register_group succeeded"). Format as system context, not chat.
+- **`chat`** — format into a `<message id="…" from="…" sender="…" time="…">` element
+- **`chat-sdk`** — extract text, author, attachments from serialized message; same `<message>` element
+- **`task`** — format as a `<task from="…" time="…">` element (script output first if present). Run pre-script if present.
+- **`webhook`** — format as a `<webhook source="…" event="…">` element wrapping the JSON payload
+- **`system`** — host action results, formatted as `<system_response action="…" status="…">`, not chat
 
 Mixed batches (e.g., a chat message + a system result both pending) are combined into one prompt with clear delimiters.
 
 ### MCP Tools
 
-MCP tools write directly to the session DB.
+MCP tools write to the container's own `outbound.db`. Anything that needs a change in host-owned `inbound.db` (schedule/cancel/pause/resume/update a task, create an agent, self-modify) is emitted as a `kind: 'system'` `messages_out` action that the host applies during delivery — the container never writes `inbound.db`.
 
-**Core tools:**
+**Messaging & interaction:**
 
 | Tool | What it does |
 |------|-------------|
-| `send_message` | Write `messages_out` row, `kind: 'chat'` |
-| `send_file` | Move file to `outbox/{msg_id}/`, write `messages_out` with filenames |
-| `schedule_task` | Write `messages_in` row (to self) with `process_after` + `recurrence`. Or `messages_out` with `deliver_after` for outbound reminders. |
-| `list_tasks` | Query `messages_in WHERE recurrence IS NOT NULL` |
-| `pause_task` / `resume_task` / `cancel_task` | Modify `messages_in` rows (update status, clear/set recurrence) |
-| `register_agent_group` | Write `messages_out`, `kind: 'system'`, `action: 'register_agent_group'` |
-
-**New tools:**
-
-| Tool | What it does |
-|------|-------------|
-| `ask_user_question` | Write `messages_out` with question card. Hold tool call open, poll `messages_in` for response matching `questionId`. Return selection as tool result. |
-| `edit_message` | Write `messages_out` with `operation: 'edit'` |
+| `send_message` | Resolve `to` (destination name) → routing, write `messages_out` row, `kind: 'chat'`. Omit `to` to reply in place. Also the agent-to-agent path: a `to` naming an `agent`-type destination. |
+| `send_file` | Copy file to `outbox/{msg_id}/`, write `messages_out` (`kind: 'chat'`) with filenames, same `to` resolution |
+| `send_card` | Write `messages_out`, `kind: 'chat-sdk'`, content `{ type: 'card', … }` |
+| `ask_user_question` | Write `messages_out` (`kind: 'chat-sdk'`, `type: 'ask_question'`). Hold tool call open, poll `inbound.db` for the response matching `questionId`. Return selection as tool result. |
+| `edit_message` | Write `messages_out` with `operation: 'edit'` (targets the original message's destination) |
 | `add_reaction` | Write `messages_out` with `operation: 'reaction'` |
-| `send_to_agent` | Write `messages_out` with `channel_type: 'agent'`, `platform_id: '{target}'` |
-| `send_card` | Write `messages_out` with card structure |
+
+(There is no `send_to_agent` tool — agent-to-agent is `send_message` to an `agent` destination.)
+
+**Scheduling** (all emit `kind: 'system'` actions except the read-only `list_tasks`):
+
+| Tool | What it does |
+|------|-------------|
+| `schedule_task` | `action: 'schedule_task'`; host inserts the `kind: 'task'` `messages_in` row with `process_after` + optional `recurrence` |
+| `list_tasks` | Read `inbound.db` (read-only) — one row per series: `kind = 'task' AND status IN ('pending','paused') GROUP BY series_id` |
+| `pause_task` / `resume_task` / `cancel_task` / `update_task` | matching `action`; host updates the live `messages_in` row(s) |
+
+**Central-DB / self-modification** (`kind: 'system'` actions; host authorizes, often via admin approval):
+
+| Tool | What it does |
+|------|-------------|
+| `create_agent` | `action: 'create_agent'` (name + instructions); host creates the agent group (replaces the old `register_agent_group`) |
+| `install_packages` | `action: 'install_packages'`; on approval host rebuilds the per-agent image and restarts |
+| `add_mcp_server` | `action: 'add_mcp_server'`; on approval host updates `container.json` and restarts |
 
 See [agent-runner-details.md](agent-runner-details.md) for full MCP tool parameter definitions.
 
@@ -886,11 +954,11 @@ The command lists are hardcoded in the agent-runner. Admin verification happens
 
 The agent-runner processes recurring task messages like any other messages_in row. After the agent-runner marks a recurring message as `completed`, the **host** handles inserting the next occurrence (new messages_in row with `process_after` advanced to next cron time). The agent-runner doesn't manage recurrence — it just processes what it finds.
 
-Pre-scripts: if a task message has a `script` field, run it first. If `wakeAgent = false`, mark completed without invoking Claude.
+Pre-scripts: if a task message has a `script` field, run it first. If `wakeAgent = false`, mark completed without invoking the provider.
 
 ### Agent-to-Agent Messaging
 
-**Outbound:** Agent calls `send_to_agent` tool → agent-runner writes messages_out with `channel_type: 'agent'`, `platform_id` = target agent group ID. Host validates permissions and writes to target session's messages_in.
+**Outbound:** Agent calls `send_message(to="<agent-name>")` where the named destination is of type `agent` → agent-runner writes messages_out with `channel_type: 'agent'`, `platform_id` = target agent group ID. Host validates permissions and writes to the target session's `inbound.db` (recording `source_session_id` so the reply routes back to this exact session).
 
 **Inbound:** Messages from other agents arrive as normal `chat` messages_in rows. The content includes `sender` and `senderId` (e.g., `"senderId": "agent:pr-admin"`). No special formatting — the agent sees it as a chat message.
 
@@ -906,7 +974,7 @@ Pre-scripts: if a task message has a `script` field, run it first. If `wakeAgent
 
 - **Approval routing** — how does the host find the admin's DM conversation? What if no DM channel exists? Is the approval list configurable per agent group or global?
 - **MCP server lifecycle** — does the MCP server process persist across multiple queries in the same container, or restart each time?
-- **Container startup config** — what config (if any) is passed to the container at launch beyond env vars? The session DB is at a fixed mount path. System prompt comes from CLAUDE.md. Provider name comes from env. What else?
+- **Container startup config** — what config (if any) is passed to the container at launch beyond env vars? The DB files are at fixed mount paths. System prompt comes from CLAUDE.md. Provider name comes from `container.json` (materialized from the `container_configs` table), not env. What else?
 - **Idle detection with pending questions** — when `ask_user_question` is waiting for a response, the container should not be considered idle. Also need to detect when the agent is still working (active tool calls, subagents) and avoid killing the container even if no messages_out have been written recently.
 
 ## Related Documents

docs/build-and-runtime.md

@@ -33,13 +33,13 @@ Both are committed. CI and the Dockerfile run `--frozen-lockfile` variants — a
 ## Supply chain
 
 - **Host + global CLIs** (pnpm): `minimumReleaseAge: 4320` (3-day hold on new versions), `onlyBuiltDependencies` allowlist for postinstall scripts. See `pnpm-workspace.yaml` and `docs/SECURITY.md`.
-- **Agent-runner** (Bun): no release-age policy — Bun doesn't have an equivalent today. The defenses are `bun.lock` pinning plus version-pinned CLIs/Bun itself via Dockerfile ARGs. When bumping `@anthropic-ai/claude-agent-sdk` or any runtime dep, review the release date on npm and bump deliberately, not via `bun update`.
+- **Agent-runner** (Bun): no release-age policy — Bun doesn't have an equivalent today. The defenses are `bun.lock` pinning plus a version-pinned Bun itself via a Dockerfile ARG (global CLIs are pinned separately in `container/cli-tools.json`). When bumping `@anthropic-ai/claude-agent-sdk` or any runtime dep, review the release date on npm and bump deliberately, not via `bun update`.
 
 ## Image build surface
 
 `container/Dockerfile` is a single-stage build on `node:22-slim`:
 
-- **Pinned ARGs** — `BUN_VERSION`, `CLAUDE_CODE_VERSION`, `AGENT_BROWSER_VERSION`, `VERCEL_VERSION`. Bump deliberately in PRs.
+- **Pinned ARGs** — `BUN_VERSION`, `PNPM_VERSION`, `INSTALL_CJK_FONTS`. Bump deliberately in PRs. Global CLI versions (`@anthropic-ai/claude-code`, `agent-browser`, `vercel`) are pinned separately in `container/cli-tools.json`, not as ARGs.
 - **CJK fonts** — `ARG INSTALL_CJK_FONTS=false`. `container/build.sh` reads `INSTALL_CJK_FONTS` from `.env` and passes it through. Default build saves ~200MB; opt in when the user works with Chinese/Japanese/Korean content.
 - **BuildKit cache mounts** — `/var/cache/apt`, `/var/lib/apt`, `/root/.bun/install/cache`, `/root/.cache/pnpm`. Rebuilds where `package.json`/`bun.lock` haven't changed are fast. Requires BuildKit (default on Docker 23+, Apple Container-compat).
 - **`tini` as init** — reaps Chromium zombies, forwards signals so in-flight `outbound.db` writes finalize on SIGTERM.
@@ -49,7 +49,7 @@ Both are committed. CI and the Dockerfile run `--frozen-lockfile` variants — a
 ## Session wake (two paths)
 
 1. **Base image ENTRYPOINT** — used for stdin-piped test invocations like the sample in `container/build.sh`: `tini --> entrypoint.sh` captures stdin to `/tmp/input.json`, then `exec bun run src/index.ts`.
-2. **Host-spawned session** — `src/container-runner.ts` at line ~301 uses `--entrypoint bash` with `-c 'exec bun run /app/src/index.ts'`. Bypasses tini (Docker's default PID 1 handling applies). Stdin is unused; all IO flows through the mounted session DBs.
+2. **Host-spawned session** — `src/container-runner.ts` at line ~503 uses `--entrypoint bash` with `-c 'exec bun run /app/src/index.ts'`. Bypasses tini (Docker's default PID 1 handling applies). Stdin is unused; all IO flows through the mounted session DBs.
 
 Both paths end with Bun running the same source file from `/app/src/index.ts`.
 

docs/db-central.md

@@ -2,7 +2,7 @@
 
 Complete reference for `data/v2.db`, the host-owned admin-plane database. Start with [db.md](db.md) for the three-DB overview, the map, and the cross-mount rules.
 
-Access layer: `src/db/`. Authoritative schema reference: `src/db/schema.ts` (comments only — actual creation runs via migrations in `src/db/migrations/`).
+Access layer: `src/db/`. `src/db/schema.ts`'s `SCHEMA` constant is a *reference copy* of the core tables for orientation — it is not exhaustive: several tables (`agent_destinations`, `pending_approvals`, `container_configs`, `agent_message_policies`, `pending_channel_approvals`, and others) exist only in their migration files under `src/db/migrations/`, which remain the actual source of truth for what's created at runtime.
 
 ---
 
@@ -55,20 +55,24 @@ Wiring: which agent group handles which messaging group. Many-to-many — the sa
 
 ```sql
 CREATE TABLE messaging_group_agents (
-  id                 TEXT PRIMARY KEY,
-  messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
-  agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
-  trigger_rules      TEXT,
-  response_scope     TEXT DEFAULT 'all',
-  session_mode       TEXT DEFAULT 'shared',
-  priority           INTEGER DEFAULT 0,
-  created_at         TEXT NOT NULL,
+  id                     TEXT PRIMARY KEY,
+  messaging_group_id     TEXT NOT NULL REFERENCES messaging_groups(id),
+  agent_group_id         TEXT NOT NULL REFERENCES agent_groups(id),
+  engage_mode            TEXT NOT NULL DEFAULT 'mention',
+                         -- 'pattern' | 'mention' | 'mention-sticky'
+  engage_pattern         TEXT,   -- regex; required when engage_mode='pattern';
+                                 -- '.' means "match every message"
+  sender_scope           TEXT NOT NULL DEFAULT 'all',    -- 'all' | 'known'
+  ignored_message_policy TEXT NOT NULL DEFAULT 'drop',   -- 'drop' | 'accumulate'
+  session_mode           TEXT DEFAULT 'shared',
+  priority               INTEGER DEFAULT 0,
+  created_at             TEXT NOT NULL,
   UNIQUE(messaging_group_id, agent_group_id)
 );
 ```
 
 - `session_mode`: `shared` (one session per channel), `per-thread` (one per thread), `agent-shared` (one per agent group across all channels).
-- `trigger_rules`: JSON; e.g. regex for native channels.
+- `engage_mode` / `engage_pattern` / `sender_scope` / `ignored_message_policy`: four orthogonal axes (migration 010) that replaced v1's opaque `trigger_rules` JSON + `response_scope` enum. `engage_mode='pattern'` requires `engage_pattern` (`'.'` matches every message — the "always respond" flavor); `sender_scope='known'` restricts engagement to group members; `ignored_message_policy='accumulate'` keeps ignored messages as context instead of dropping them.
 - **Side effect:** creating a wiring must also populate `agent_destinations` — don't mutate one without the other (see §1.10).
 
 ### 1.4 `users`
@@ -323,6 +327,71 @@ CREATE TABLE container_configs (
 - **Readers:** `src/container-config.ts`, `src/container-runner.ts`, `src/cli/dispatch.ts` (scope enforcement), `src/claude-md-compose.ts`
 - **Writers:** `src/db/container-configs.ts`, `src/modules/self-mod/apply.ts`, `src/backfill-container-configs.ts`
 
+### 1.16 `pending_sender_approvals`
+
+In-flight state for the `unknown_sender_policy = 'request_approval'` flow. A row exists while an admin-approval card is outstanding for a first-time sender in a wired messaging group; `UNIQUE(messaging_group_id, sender_identity)` dedups concurrent attempts from the same sender instead of spamming the admin with repeat cards.
+
+```sql
+CREATE TABLE pending_sender_approvals (
+  id                 TEXT PRIMARY KEY,
+  messaging_group_id TEXT NOT NULL REFERENCES messaging_groups(id),
+  agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
+  sender_identity    TEXT NOT NULL,    -- namespaced user id (channel_type:handle)
+  sender_name        TEXT,
+  original_message   TEXT NOT NULL,    -- JSON of the original InboundEvent
+  approver_user_id   TEXT NOT NULL,
+  created_at         TEXT NOT NULL,
+  title              TEXT NOT NULL DEFAULT '',       -- added by migration 013
+  options_json       TEXT NOT NULL DEFAULT '[]',     -- added by migration 013
+  UNIQUE(messaging_group_id, sender_identity)
+);
+```
+
+Deleted on admin approve (after adding the sender as a member) or deny.
+
+- Access layer: `src/modules/permissions/db/pending-sender-approvals.ts`
+- **Readers/writers:** `src/modules/permissions/sender-approval.ts`, `src/modules/permissions/index.ts`, `src/db/sessions.ts` (`getAskQuestionRender`), `src/cli/resources/groups.ts`
+
+### 1.17 `pending_channel_approvals`
+
+In-flight state for the unknown-channel registration flow. When a channel with no `messaging_group_agents` wiring receives a mention or DM, the router escalates to the owner; `PRIMARY KEY(messaging_group_id)` gives free in-flight dedup via `INSERT OR IGNORE` — a second mention while a card is pending drops silently.
+
+```sql
+CREATE TABLE pending_channel_approvals (
+  messaging_group_id TEXT PRIMARY KEY REFERENCES messaging_groups(id),
+  agent_group_id     TEXT NOT NULL REFERENCES agent_groups(id),
+                     -- agent the approved wiring will target (earliest
+                     -- agent_group by created_at, picked at request time)
+  original_message   TEXT NOT NULL,      -- JSON of the original InboundEvent
+  approver_user_id   TEXT NOT NULL,
+  created_at         TEXT NOT NULL,
+  title              TEXT NOT NULL DEFAULT '',       -- added by migration 013
+  options_json       TEXT NOT NULL DEFAULT '[]'      -- added by migration 013
+);
+```
+
+Approve creates the `messaging_group_agents` wiring and replays the triggering event; deny sets `messaging_groups.denied_at` so future messages on that channel drop without re-prompting. Either way, this row is deleted.
+
+- Access layer: `src/modules/permissions/db/pending-channel-approvals.ts`
+- **Readers/writers:** `src/modules/permissions/channel-approval.ts`, `src/modules/permissions/index.ts`, `src/router.ts`, `src/db/sessions.ts` (`getAskQuestionRender`), `src/cli/resources/groups.ts`
+
+### 1.18 `agent_message_policies`
+
+Per-message approval gate on an agent-to-agent connection between two agent groups. No row for a `(from, to)` pair means free flow (no approval required); a row names the `approver` who must sign off on each message.
+
+```sql
+CREATE TABLE agent_message_policies (
+  from_agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
+  to_agent_group_id   TEXT NOT NULL REFERENCES agent_groups(id),
+  approver            TEXT NOT NULL,
+  created_at          TEXT NOT NULL,
+  PRIMARY KEY (from_agent_group_id, to_agent_group_id)
+);
+```
+
+- Access layer: `src/modules/agent-to-agent/db/agent-message-policies.ts`
+- **Readers/writers:** `src/cli/resources/policies.ts`; approved messages create a row in `pending_approvals` (see §1.11) via the a2a send path.
+
 ---
 
 ## 2. Migration system
@@ -330,21 +399,33 @@ CREATE TABLE container_configs (
 Migrations live in `src/db/migrations/`, one file per migration. Runner: `runMigrations()` in `src/db/migrations/index.ts`. It:
 
 1. Creates `schema_version` if absent.
-2. Reads `MAX(version)` — call it `current`.
-3. For each migration with `version > current`, executes `up(db)` inside a transaction and appends a `schema_version` row.
+2. Reads every already-applied `name` from `schema_version` into a `Set` and filters the `migrations` barrel array down to the ones whose `name` isn't in that set — dedup is by **name**, not by the numeric `version` field.
+3. Runs each pending migration's `up(db)` inside a transaction, in the barrel array's literal order (which is *not* sorted by `version`), then inserts a `schema_version` row.
+4. The `version` column stored in `schema_version` is **not** the migration's own `version` field — it's `COALESCE(MAX(version), 0) + 1`, i.e. an auto-assigned applied-order number computed at insert time. The `version` field on the `Migration` object is just an ordering hint for humans reading the barrel file; it lets module migrations (installed later by skills) pick arbitrary numbers without coordinating with trunk.
 
-| # | File | Introduces |
-|---|------|------------|
-| 001 | `001-initial.ts` | Core tables: `agent_groups`, `messaging_groups`, `messaging_group_agents`, `users`, `user_roles`, `agent_group_members`, `user_dms`, `sessions`, `pending_questions` |
-| 002 | `002-chat-sdk-state.ts` | `chat_sdk_kv`, `chat_sdk_subscriptions`, `chat_sdk_locks`, `chat_sdk_lists` |
-| 003 | `003-pending-approvals.ts` | `pending_approvals` (session-bound + OneCLI fields) |
-| 004 | `004-agent-destinations.ts` | `agent_destinations` + backfill from existing `messaging_group_agents` wirings |
-| 007 | `007-pending-approvals-title-options.ts` | `ALTER TABLE pending_approvals` add `title`, `options_json` (retrofits DBs created between 003 and 007) |
-| 008 | `008-dropped-messages.ts` | `unregistered_senders` |
-| 009 | `009-drop-pending-credentials.ts` | Drop the defunct `pending_credentials` table |
-| 014 | `014-container-configs.ts` | `container_configs` — per-agent-group container runtime config |
-| 015 | `015-cli-scope.ts` | `ALTER TABLE container_configs ADD COLUMN cli_scope` |
+A few migrations also set `disableForeignKeys: true` (needed for table recreates — SQLite can't relax a table-level `UNIQUE` without DROP+RENAME, which fails FK integrity checks with live child rows). The runner toggles `PRAGMA foreign_keys` around the transaction and runs `PRAGMA foreign_key_check` inside it, snapshotting pre-existing violations so it only fails on violations the migration itself introduced.
 
-Numbers 005 and 006 are intentionally absent — migrations were renumbered during early development.
+Several early migrations were later renamed/retired and replaced by "module" files (their original `name` is retained on the new file so already-migrated DBs don't re-run them):
+
+| Ver. | Name (stored in `schema_version`) | File | Introduces |
+|---|---|------|------------|
+| 1 | `initial-v2-schema` | `001-initial.ts` | Core tables: `agent_groups`, `messaging_groups`, `messaging_group_agents` (with the original `trigger_rules`/`response_scope` columns — see v10), `users`, `user_roles`, `agent_group_members`, `user_dms`, `sessions`, `pending_questions` |
+| 2 | `chat-sdk-state` | `002-chat-sdk-state.ts` | `chat_sdk_kv`, `chat_sdk_subscriptions`, `chat_sdk_locks`, `chat_sdk_lists` |
+| 3 | `pending-approvals` | `module-approvals-pending-approvals.ts` | `pending_approvals` (session-bound + OneCLI fields) |
+| 4 | `agent-destinations` | `module-agent-to-agent-destinations.ts` | `agent_destinations` + backfill from existing `messaging_group_agents` wirings |
+| 7 | `pending-approvals-title-options` | `module-approvals-title-options.ts` | Retroactive `ALTER TABLE pending_approvals` add `title`, `options_json` for DBs that ran migration 3 before its `CREATE TABLE` was edited to include those columns |
+| 8 | `dropped-messages` | `008-dropped-messages.ts` | `unregistered_senders` |
+| 9 | `drop-pending-credentials` | `009-drop-pending-credentials.ts` | Drop the defunct `pending_credentials` table |
+| 10 | `engage-modes` | `010-engage-modes.ts` | `messaging_group_agents`: add `engage_mode`, `engage_pattern`, `sender_scope`, `ignored_message_policy`; backfill from `trigger_rules`/`response_scope`; drop those two legacy columns (see §1.3) |
+| 11 | `pending-sender-approvals` | `011-pending-sender-approvals.ts` | `pending_sender_approvals` (see §1.16) |
+| 12 | `channel-registration` | `012-channel-registration.ts` | `messaging_groups.denied_at` + `pending_channel_approvals` (see §1.17) |
+| 13 | `approval-render-metadata` | `013-approval-render-metadata.ts` | `title`, `options_json` columns on `pending_channel_approvals` and `pending_sender_approvals` |
+| 14 | `container-configs` | `014-container-configs.ts` | `container_configs` — per-agent-group container runtime config |
+| 15 | `cli-scope` | `015-cli-scope.ts` | `ALTER TABLE container_configs ADD COLUMN cli_scope` |
+| 16 | `messaging-group-instance` | `016-messaging-group-instance.ts` | `messaging_groups` gets an `instance` column (adapter-instance dimension); table recreate (`disableForeignKeys: true`) backfills `instance = channel_type` on every existing row and relaxes the `UNIQUE` to `(channel_type, platform_id, instance)` |
+| 17 | `agent-message-policies` | `017-agent-message-policies.ts` | `agent_message_policies` (see §1.18) |
+| 18 | `approvals-approver-user-id` | `018-approvals-approver-user-id.ts` | `pending_approvals.approver_user_id` — names a single required approver for a2a message-gate policies |
+
+Numbers 5 and 6 are intentionally absent — migrations were renumbered during early development.
 
 Session DB schemas (`INBOUND_SCHEMA`, `OUTBOUND_SCHEMA`) are **not** versioned here. They're `CREATE TABLE IF NOT EXISTS` so new columns land via the session-DB lazy migration helpers (`migrateDeliveredTable()` etc.) when a session file from an older build is reopened. See [db-session.md](db-session.md).

docs/db-session.md

@@ -10,14 +10,16 @@ Schemas live in `src/db/schema.ts` as the `INBOUND_SCHEMA` and `OUTBOUND_SCHEMA`
 
 ```
 data/v2-sessions/<agent_group_id>/<session_id>/
-  inbound.db              ← host writes, container reads (read-only mount)
+  inbound.db              ← host writes, container reads (read-only open)
   outbound.db             ← container writes, host reads (read-only open)
   .heartbeat              ← mtime touched by container (not a DB write)
   inbox/<message_id>/     ← user attachments, decoded from inbound message content
   outbox/<message_id>/    ← attachments the agent produced
 ```
 
-One session = one folder = one pair of DBs. The `agent_group_id` parent directory also holds per-group state (`.claude-shared/`, `agent-runner-src/`) that is shared across every session of that agent group.
+The session directory itself is mounted read-write into the container (`src/container-runner.ts`) — read-only is *not* a mount property. The container opens `inbound.db` with `{ readonly: true }` at the SQLite connection layer (`container/agent-runner/src/db/connection.ts`), so the container could technically write to the underlying file via another path, but every code path that touches `inbound.db` from inside the container goes through that read-only handle.
+
+One session = one folder = one pair of DBs. The `agent_group_id` parent directory also holds per-group state (`.claude-shared/`) that is shared across every session of that agent group. (The agent-runner source is not copied per group — it's a shared read-only mount from `container/agent-runner/src` into every container; see `src/container-runner.ts`.)
 
 Path helpers in `src/session-manager.ts`: `sessionDir()`, `inboundDbPath()`, `outboundDbPath()`, `heartbeatPath()`.
 
@@ -55,7 +57,7 @@ CREATE INDEX idx_messages_in_series ON messages_in(series_id);
 
 Content shapes: see [api-details.md §Session DB Schema Details](api-details.md#session-db-schema-details).
 
-**Writers (host):** `insertMessage()`, `insertTask()`, `insertRecurrence()` — all in `src/db/session-db.ts`. Each calls `nextEvenSeq()`.
+**Writers (host):** `insertMessage()` (and `nextEvenSeq()`) in `src/db/session-db.ts`; `insertTask()` and `insertRecurrence()` in `src/modules/scheduling/db.ts`. Each calls `nextEvenSeq()`.
 **Reader (container):** `container/agent-runner/src/db/messages-in.ts` — polls `status='pending' AND (process_after IS NULL OR process_after <= now)`.
 
 ### 2.2 `delivered`
@@ -177,6 +179,24 @@ CREATE TABLE session_state (
 
 Access: `container/agent-runner/src/db/session-state.ts`.
 
+### 4.4 `container_state`
+
+Single-row (`id=1`) tool-in-flight tracker. The container records the currently-running tool on `PreToolUse` and clears it on `PostToolUse`/`PostToolUseFailure`; the host reads it during the stale-container sweep to widen its stuck-tolerance window when `Bash` is running with a user-declared `timeout` over the normal threshold, so long-running scripts aren't killed as "stuck".
+
+```sql
+CREATE TABLE container_state (
+  id                       INTEGER PRIMARY KEY CHECK (id = 1),
+  current_tool             TEXT,
+  tool_declared_timeout_ms INTEGER,
+  tool_started_at          TEXT,
+  updated_at               TEXT NOT NULL
+);
+```
+
+- **Writer (container):** `setContainerToolInFlight()` / `clearContainerToolInFlight()` in `container/agent-runner/src/db/connection.ts`, called from the `preToolUseHook` / `postToolUseHook` in `container/agent-runner/src/providers/claude.ts`.
+- **Reader (host):** `getContainerState()` in `src/db/session-db.ts`; consumed by the sweep's `bashTimeoutMs()` helper in `src/host-sweep.ts`.
+- `CREATE TABLE IF NOT EXISTS` — forward-compatible with `outbound.db` files created before this table existed; `getContainerState()` returns `null` if the table or row is absent.
+
 ---
 
 ## 5. Schema evolution

docs/db.md

@@ -35,7 +35,6 @@ data/
   v2-sessions/
     <agent_group_id>/
       .claude-shared/                     ← shared Claude state for the agent group
-      agent-runner-src/                   ← per-group agent-runner overlay
       <session_id>/
         inbound.db                        ← host writes, container reads
         outbound.db                       ← container writes, host reads

docs/docker-sandboxes.md

@@ -1,359 +0,0 @@
-# Running NanoClaw in Docker Sandboxes (Manual Setup)
-
-This guide walks through setting up NanoClaw inside a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) from scratch — no install script, no pre-built fork. You'll clone the upstream repo, apply the necessary patches, and have agents running in full hypervisor-level isolation.
-
-## Architecture
-
-```
-Host (macOS / Windows WSL)
-└── Docker Sandbox (micro VM with isolated kernel)
-    ├── NanoClaw process (Node.js)
-    │   ├── Channel adapters (WhatsApp, Telegram, etc.)
-    │   └── Container spawner → nested Docker daemon
-    └── Docker-in-Docker
-        └── nanoclaw-agent containers
-            └── Claude Agent SDK
-```
-
-Each agent runs in its own container, inside a micro VM that is fully isolated from your host. Two layers of isolation: per-agent containers + the VM boundary.
-
-The sandbox provides a MITM proxy at `host.docker.internal:3128` that handles network access and injects your Anthropic API key automatically.
-
-> **Note:** This guide is based on a validated setup running on macOS (Apple Silicon) with WhatsApp. Other channels (Telegram, Slack, etc.) and environments (Windows WSL) may require additional proxy patches for their specific HTTP/WebSocket clients. The core patches (container runner, credential proxy, Dockerfile) apply universally — channel-specific proxy configuration varies.
-
-## Prerequisites
-
-- **Docker Desktop v4.40+** with Sandbox support
-- **Anthropic API key** (the sandbox proxy manages injection)
-- For **Telegram**: a bot token from [@BotFather](https://t.me/BotFather) and your chat ID
-- For **WhatsApp**: a phone with WhatsApp installed
-
-Verify sandbox support:
-```bash
-docker sandbox version
-```
-
-## Step 1: Create the Sandbox
-
-On your host machine:
-
-```bash
-# Create a workspace directory
-mkdir -p ~/nanoclaw-workspace
-
-# Create a shell sandbox with the workspace mounted
-docker sandbox create shell ~/nanoclaw-workspace
-```
-
-If you're using WhatsApp, configure proxy bypass so WhatsApp's Noise protocol isn't MITM-inspected:
-
-```bash
-docker sandbox network proxy shell-nanoclaw-workspace \
-  --bypass-host web.whatsapp.com \
-  --bypass-host "*.whatsapp.com" \
-  --bypass-host "*.whatsapp.net"
-```
-
-Telegram does not need proxy bypass.
-
-Enter the sandbox:
-```bash
-docker sandbox run shell-nanoclaw-workspace
-```
-
-## Step 2: Install Prerequisites
-
-Inside the sandbox:
-
-```bash
-sudo apt-get update && sudo apt-get install -y build-essential python3
-npm config set strict-ssl false
-```
-
-## Step 3: Clone and Install NanoClaw
-
-NanoClaw must live inside the workspace directory — Docker-in-Docker can only bind-mount from the shared workspace path.
-
-```bash
-# Clone to home first (virtiofs can corrupt git pack files during clone)
-cd ~
-git clone https://github.com/nanocoai/nanoclaw.git
-
-# Replace with YOUR workspace path (the host path you passed to `docker sandbox create`)
-WORKSPACE=/Users/you/nanoclaw-workspace
-
-# Move into workspace so DinD mounts work
-mv nanoclaw "$WORKSPACE/nanoclaw"
-cd "$WORKSPACE/nanoclaw"
-
-# Install dependencies
-pnpm install
-pnpm install https-proxy-agent
-```
-
-## Step 4: Apply Proxy and Sandbox Patches
-
-NanoClaw needs several patches to work inside a Docker Sandbox. These handle proxy routing, CA certificates, and Docker-in-Docker mount restrictions.
-
-### 4a. Dockerfile — proxy args for container image build
-
-`pnpm install` inside `docker build` fails with `SELF_SIGNED_CERT_IN_CHAIN` because the sandbox's MITM proxy presents its own certificate. Add proxy build args to `container/Dockerfile`:
-
-Add these lines after the `FROM` line:
-
-```dockerfile
-# Accept proxy build args
-ARG http_proxy
-ARG https_proxy
-ARG no_proxy
-ARG NODE_EXTRA_CA_CERTS
-ARG npm_config_strict_ssl=true
-RUN npm config set strict-ssl ${npm_config_strict_ssl}
-```
-
-And after the `RUN pnpm install` line:
-
-```dockerfile
-RUN npm config set strict-ssl true
-```
-
-### 4b. Build script — forward proxy args
-
-Patch `container/build.sh` to pass proxy env vars to `docker build`:
-
-Add these `--build-arg` flags to the `docker build` command:
-
-```bash
---build-arg http_proxy="${http_proxy:-$HTTP_PROXY}" \
---build-arg https_proxy="${https_proxy:-$HTTPS_PROXY}" \
---build-arg no_proxy="${no_proxy:-$NO_PROXY}" \
---build-arg npm_config_strict_ssl=false \
-```
-
-### 4c. Container runner — proxy forwarding, CA cert mount, /dev/null fix
-
-Three changes to `src/container-runner.ts`:
-
-**Replace `/dev/null` shadow mount.** The sandbox rejects `/dev/null` bind mounts. Find where `.env` is shadow-mounted to `/dev/null` and replace it with an empty file:
-
-```typescript
-// Create an empty file to shadow .env (Docker Sandbox rejects /dev/null mounts)
-const emptyEnvPath = path.join(DATA_DIR, 'empty-env');
-if (!fs.existsSync(emptyEnvPath)) fs.writeFileSync(emptyEnvPath, '');
-// Use emptyEnvPath instead of '/dev/null' in the mount
-```
-
-**Forward proxy env vars** to spawned agent containers. Add `-e` flags for `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and their lowercase variants.
-
-**Mount CA certificate.** If `NODE_EXTRA_CA_CERTS` or `SSL_CERT_FILE` is set, copy the cert into the project directory and mount it into agent containers:
-
-```typescript
-const caCertSrc = process.env.NODE_EXTRA_CA_CERTS || process.env.SSL_CERT_FILE;
-if (caCertSrc) {
-  const certDir = path.join(DATA_DIR, 'ca-cert');
-  fs.mkdirSync(certDir, { recursive: true });
-  fs.copyFileSync(caCertSrc, path.join(certDir, 'proxy-ca.crt'));
-  // Mount: certDir -> /workspace/ca-cert (read-only)
-  // Set NODE_EXTRA_CA_CERTS=/workspace/ca-cert/proxy-ca.crt in the container
-}
-```
-
-### 4d. Container runtime — prevent self-termination
-
-In `src/container-runtime.ts`, the `cleanupOrphans()` function matches containers by the `nanoclaw-` prefix. Inside a sandbox, the sandbox container itself may match (e.g., `nanoclaw-docker-sandbox`). Filter out the current hostname:
-
-```typescript
-// In cleanupOrphans(), filter out os.hostname() from the list of containers to stop
-```
-
-### 4e. Credential proxy — route through MITM proxy
-
-In `src/credential-proxy.ts`, upstream API requests need to go through the sandbox proxy. Add `HttpsProxyAgent` to outbound requests:
-
-```typescript
-import { HttpsProxyAgent } from 'https-proxy-agent';
-
-const proxyUrl = process.env.HTTPS_PROXY || process.env.https_proxy;
-const upstreamAgent = proxyUrl ? new HttpsProxyAgent(proxyUrl) : undefined;
-// Pass upstreamAgent to https.request() options
-```
-
-### 4f. Setup script — proxy build args
-
-Patch `setup/container.ts` to pass the same proxy `--build-arg` flags as `build.sh` (Step 4b).
-
-## Step 5: Build
-
-```bash
-pnpm run build
-bash container/build.sh
-```
-
-## Step 6: Add a Channel
-
-### Telegram
-
-```bash
-# Apply the Telegram skill
-pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-telegram
-
-# Rebuild after applying the skill
-pnpm run build
-
-# Configure .env
-cat > .env << EOF
-TELEGRAM_BOT_TOKEN=<your-token-from-botfather>
-ASSISTANT_NAME=nanoclaw
-ANTHROPIC_API_KEY=proxy-managed
-EOF
-mkdir -p data/env && cp .env data/env/env
-
-# Register your chat
-pnpm exec tsx setup/index.ts --step register \
-  --jid "tg:<your-chat-id>" \
-  --name "My Chat" \
-  --trigger "@nanoclaw" \
-  --folder "telegram_main" \
-  --channel telegram \
-  --assistant-name "nanoclaw" \
-  --is-main \
-  --no-trigger-required
-```
-
-**To find your chat ID:** Send any message to your bot, then:
-```bash
-curl -s --proxy $HTTPS_PROXY "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -m json.tool
-```
-
-**Telegram in groups:** Disable Group Privacy in @BotFather (`/mybots` > Bot Settings > Group Privacy > Turn off), then remove and re-add the bot.
-
-**Important:** If the Telegram skill creates `src/channels/telegram.ts`, you'll need to patch it for proxy support. Add an `HttpsProxyAgent` and pass it to grammy's `Bot` constructor via `baseFetchConfig.agent`. Then rebuild.
-
-### WhatsApp
-
-Make sure you configured proxy bypass in [Step 1](#step-1-create-the-sandbox) first.
-
-```bash
-# Apply the WhatsApp skill
-pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-whatsapp
-
-# Rebuild
-pnpm run build
-
-# Configure .env
-cat > .env << EOF
-ASSISTANT_NAME=nanoclaw
-ANTHROPIC_API_KEY=proxy-managed
-EOF
-mkdir -p data/env && cp .env data/env/env
-
-# Authenticate (choose one):
-
-# QR code — scan with WhatsApp camera:
-pnpm exec tsx src/whatsapp-auth.ts
-
-# OR pairing code — enter code in WhatsApp > Linked Devices > Link with phone number:
-pnpm exec tsx src/whatsapp-auth.ts --pairing-code --phone <phone-number-no-plus>
-
-# Register your chat (JID = your phone number + @s.whatsapp.net)
-pnpm exec tsx setup/index.ts --step register \
-  --jid "<phone>@s.whatsapp.net" \
-  --name "My Chat" \
-  --trigger "@nanoclaw" \
-  --folder "whatsapp_main" \
-  --channel whatsapp \
-  --assistant-name "nanoclaw" \
-  --is-main \
-  --no-trigger-required
-```
-
-**Important:** The WhatsApp skill files (`src/channels/whatsapp.ts` and `src/whatsapp-auth.ts`) also need proxy patches — add `HttpsProxyAgent` for WebSocket connections and a proxy-aware version fetch. Then rebuild.
-
-### Both Channels
-
-Apply both skills, patch both for proxy support, combine the `.env` variables, and register each chat separately.
-
-## Step 7: Run
-
-```bash
-pnpm start
-```
-
-You don't need to set `ANTHROPIC_API_KEY` manually. The sandbox proxy intercepts requests and replaces `proxy-managed` with your real key automatically.
-
-## Networking Details
-
-### How the proxy works
-
-All traffic from the sandbox routes through the host proxy at `host.docker.internal:3128`:
-
-```
-Agent container → DinD bridge → Sandbox VM → host.docker.internal:3128 → Host proxy → api.anthropic.com
-```
-
-**"Bypass" does not mean traffic skips the proxy.** It means the proxy passes traffic through without MITM inspection. Node.js doesn't automatically use `HTTP_PROXY` env vars — you need explicit `HttpsProxyAgent` configuration in every HTTP/WebSocket client.
-
-### Shared paths for DinD mounts
-
-Only the workspace directory is available for Docker-in-Docker bind mounts. Paths outside the workspace fail with "path not shared":
-- `/dev/null` → replace with an empty file in the project dir
-- `/usr/local/share/ca-certificates/` → copy cert to project dir
-- `/home/agent/` → clone to workspace instead
-
-### Git clone and virtiofs
-
-The workspace is mounted via virtiofs. Git's pack file handling can corrupt over virtiofs during clone. Workaround: clone to `/home/agent` first, then `mv` into the workspace.
-
-## Troubleshooting
-
-### pnpm install fails with SELF_SIGNED_CERT_IN_CHAIN
-```bash
-npm config set strict-ssl false
-```
-
-### Container build fails with proxy errors
-```bash
-docker build \
-  --build-arg http_proxy=$http_proxy \
-  --build-arg https_proxy=$https_proxy \
-  -t nanoclaw-agent:latest container/
-```
-
-### Agent containers fail with "path not shared"
-All bind-mounted paths must be under the workspace directory. Check:
-- Is NanoClaw cloned into the workspace? (not `/home/agent/`)
-- Is the CA cert copied to the project root?
-- Has the empty `.env` shadow file been created?
-
-### Agent containers can't reach Anthropic API
-Verify proxy env vars are forwarded to agent containers. Check container logs for `HTTP_PROXY=http://host.docker.internal:3128`.
-
-### WhatsApp error 405
-The version fetch is returning a stale version. Make sure the proxy-aware `fetchWaVersionViaProxy` patch is applied — it fetches `sw.js` through `HttpsProxyAgent` and parses `client_revision`.
-
-### WhatsApp "Connection failed" immediately
-Proxy bypass not configured. From the **host**, run:
-```bash
-docker sandbox network proxy <sandbox-name> \
-  --bypass-host web.whatsapp.com \
-  --bypass-host "*.whatsapp.com" \
-  --bypass-host "*.whatsapp.net"
-```
-
-### Telegram bot doesn't receive messages
-1. Check the grammy proxy patch is applied (look for `HttpsProxyAgent` in `src/channels/telegram.ts`)
-2. Check Group Privacy is disabled in @BotFather if using in groups
-
-### Git clone fails with "inflate: data stream error"
-Clone to a non-workspace path first, then move:
-```bash
-cd ~ && git clone https://github.com/nanocoai/nanoclaw.git && mv nanoclaw /path/to/workspace/nanoclaw
-```
-
-### WhatsApp QR code doesn't display
-Run the auth command interactively inside the sandbox (not piped through `docker sandbox exec`):
-```bash
-docker sandbox run shell-nanoclaw-workspace
-# Then inside:
-pnpm exec tsx src/whatsapp-auth.ts
-```

docs/isolation-model.md

@@ -80,7 +80,7 @@ agent_groups (workspace, memory, CLAUDE.md, personality)
     ↕ many-to-many
 messaging_groups (a specific channel/chat/group on a platform)
     via
-messaging_group_agents (session_mode, trigger_rules, priority)
+messaging_group_agents (session_mode, engage_mode, engage_pattern, sender_scope, ignored_message_policy, priority)
 ```
 
 - **Shared session:** multiple messaging_groups → same agent_group, `session_mode = 'agent-shared'`

docs/onecli-upgrades.md

@@ -10,11 +10,11 @@ Find out what is running and what is required:
 
 ```bash
 cat versions.json                                   # the sanctioned pin
-curl -s http://127.0.0.1:10254/api/health           # reports the running gateway version
+curl -s http://127.0.0.1:10254/api/health           # liveness check; `version` field is typically "unknown", not the gateway version
 curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:10254/v1/health
 ```
 
-If the last command prints `404`, the server predates the `/v1` API that `@onecli-sh/sdk` 2.x requires — every SDK call will fail with 404s that look transient but are permanent. If your gateway is remote, substitute its host for `127.0.0.1` (it's in `.env` as `ONECLI_URL` / `NANOCLAW_ONECLI_API_HOST`).
+If the last command prints `404`, the server predates the `/v1` API that `@onecli-sh/sdk` 2.x requires — every SDK call will fail with 404s that look transient but are permanent. If your gateway is remote, substitute its host for `127.0.0.1` (it's `ONECLI_URL` in `.env`; `NANOCLAW_ONECLI_API_HOST` is a setup-time override only, not persisted to `.env`).
 
 Why gateways fall behind: the OneCLI installer's docker-compose tracks the `latest` image tag, but Docker never re-pulls a tag — the server freezes at whatever `latest` meant on install day.
 

docs/setup-flow.md

@@ -179,7 +179,7 @@ So during this step:
   marker.
 
 The level-2 log still gets an entry (`auth [interactive] → success`
-with the method — subscription / oauth-token / api-key). Level-3 captures
+with the method — subscription / oauth / api). Level-3 captures
 are optional here; mirroring `script -q` output is tricky and the risk of
 leaking the token to disk outweighs the debugging value.
 
@@ -190,7 +190,7 @@ leaking the token to disk outweighs the debugging value.
 | `nanoclaw.sh` | Top-level wrapper. Phase 1 (bootstrap) and phase 2 (setup:auto) orchestration. Writes bootstrap's raw log + progression entry. `--uninstall` bypasses bootstrap entirely — it execs setup:auto directly (the flow lives in `setup/uninstall/`), or prints manual-cleanup guidance and exits 1 when the TS toolchain is missing. |
 | `setup.sh` | Phase 1 bootstrap: Node, pnpm, native-module verify. Emits its own `BOOTSTRAP` status block (historically printed to stdout; now goes to the bootstrap raw log). |
 | `setup/auto.ts` | Phase 2 driver. Orchestrates the clack UI, step execution, user prompts, and writes to all three log levels for every step it spawns. |
-| `setup/logs.ts` | The logging primitives (`logStep`, `logUserInput`, `logComplete`, `stepRawLog`, `initSetupLog`). Single source of truth for level 2/3 formatting and file paths. |
+| `setup/logs.ts` | The logging primitives (`step`, `userInput`, `complete`, `stepRawLog`, `reset`). Single source of truth for level 2/3 formatting and file paths. |
 | `setup/<step>.ts` | Individual step implementations. Must emit one terminal status block; must not write directly to the terminal. |
 | `setup/register-claude-token.sh` | The Anthropic exception. Inherits stdio, prints its own UI, returns a status to the driver. |
 | `setup/add-telegram.sh` | Non-interactive adapter installer. Reads `TELEGRAM_BOT_TOKEN` from env; never prompts. User-facing bits live in `auto.ts`. |

docs/setup-wiring.md

@@ -14,7 +14,7 @@ Last updated: 2026-04-09
 - Container clears stale `processing_ack` entries on startup (crash recovery)
 - Files: `src/db/schema.ts` (INBOUND_SCHEMA + OUTBOUND_SCHEMA), `src/session-manager.ts`, `src/delivery.ts`, `src/host-sweep.ts`, `container/agent-runner/src/db/connection.ts`, `messages-in.ts`, `messages-out.ts`, `poll-loop.ts`, `mcp-tools/scheduling.ts`, `mcp-tools/interactive.ts`
 - Container image rebuilt with tsconfig (`container/agent-runner/tsconfig.json`)
-- E2E verified: host → Docker container → Claude responds → "E2E works!" ✓
+- E2E verified: host → Docker container → agent responds → "E2E works!" ✓
 
 ### OneCLI Integration
 - `ensureAgent()` call added before `applyContainerConfig()` in `src/container-runner.ts`
@@ -65,11 +65,11 @@ Added `session_mode: 'agent-shared'` for cross-channel shared sessions (e.g. Git
 
 ### Entity Model
 ```
-agent_groups (id, name, folder, agent_provider, container_config)
-    ↕ many-to-many
-messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy)
+agent_groups (id, name, folder, agent_provider)
+    ↕ many-to-many                       (container runtime config lives in the separate container_configs table)
+messaging_groups (id, channel_type, platform_id, instance, name, is_group, unknown_sender_policy, denied_at)
     via
-messaging_group_agents (messaging_group_id, agent_group_id, trigger_rules, session_mode, priority)
+messaging_group_agents (messaging_group_id, agent_group_id, engage_mode, engage_pattern, sender_scope, ignored_message_policy, session_mode, priority)
 
 users (id, kind, display_name)          -- namespaced as "<channel>:<handle>"
 user_roles (user_id, role, agent_group_id)    -- owner / admin (global or scoped)

docs/templates.md

@@ -2,27 +2,21 @@
 
 A **template** is a reusable folder you stamp into a working agent group: it
 carries the agent's standing instructions, its MCP tool servers, and its skills,
-but **no secrets and no provider**. Point `ncl` (or the setup wizard) at one and
+but **no secrets and no provider**. Point `ncl` at one and
 you get a configured agent in seconds; you choose the runtime/provider
 separately.
 
-Templates are purely additive: no DB migration, no new dependency. **At runtime,
-templates are resolved only from a local directory**: `templates/` at the
+Templates are purely additive: no DB migration, no new dependency. **Templates
+are resolved only from a local directory**: `templates/` at the
 project root by default (committed but shipped empty), or whatever
-`NANOCLAW_TEMPLATES_DIR` points at (a local path only). The setup wizard can also
-discover templates from the public registry
+`NANOCLAW_TEMPLATES_DIR` points at (a local path only). The public registry
 ([`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates))
-and copy a chosen one into your local `templates/` before stamping.
+is a manual copy source — clone or download it yourself and copy the chosen
+template into your local `templates/` before stamping.
 
 ## Using a template
 
-**During install.** `bash nanoclaw.sh` opens the setup wizard. Choose **Template
-setup**, then either **NanoClaw template library** (clones the public registry,
-copies the template you pick into your local `templates/`) or **Local templates**
-(lists what's already in `templates/`). The normal auth step then picks the
-runtime, and the wizard stamps and wires your first agent.
-
-**Anytime, via the CLI:**
+**Via the CLI:**
 
 ```bash
 ncl groups create --template sales/sdr --name "SDR Agent"
@@ -40,8 +34,8 @@ e.g. `sales/sdr` → `templates/sales/sdr`.
 
 For safety the ref must stay inside the templates directory: absolute paths, a
 leading `~`, and `../` escapes are rejected. There is no `--source`, no git URL,
-and no remote fetch at `ncl` time. Populate `templates/` first (by hand, or via
-the setup wizard's library option), then stamp.
+and no remote fetch at `ncl` time. Populate `templates/` first (by hand, e.g.
+copying from the public registry), then stamp.
 
 `NANOCLAW_TEMPLATES_DIR` may point the library at another **local** directory; it
 is never a URL and never changes at runtime.

docs/v1-to-v2-changes.md

@@ -80,7 +80,7 @@ Tasks can exist before a session is awake — the host sweep creates/wakes the c
 
 **v2:** OneCLI Agent Vault. A separate local service at `http://127.0.0.1:10254` holds secrets. Agents are *scoped* to specific secrets and the vault injects them into approved API requests as they leave the container. The container never sees the raw secret value.
 
-Gotcha: auto-created agents default to `selective` secret mode — no secrets attached, even if matching secrets exist in the vault. See the "auto-created agents start in selective secret mode" section of the root CLAUDE.md for the fix (`onecli agents set-secret-mode --mode all`).
+Note: auto-created agents default to `all` secret mode — every vault secret whose host pattern matches is injected automatically. See the "Secret modes" section of the root CLAUDE.md if you want per-agent control (`onecli agents set-secret-mode --mode selective`).
 
 **What the automated migration does:** copies every v1 `.env` key verbatim into v2 `.env`, never overwriting existing v2 keys. The OneCLI vault migration is a separate step owned by the `/init-onecli` skill, which knows how to pull from `.env`.
 

groups/global/CLAUDE.md

@@ -1,166 +0,0 @@
-# Main
-
-You are Main, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
-
-## What You Can Do
-
-- Answer questions and have conversations
-- Search the web and fetch content from URLs
-- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
-- Read and write files in your workspace
-- Run bash commands in your sandbox
-- Schedule tasks to run later or on a recurring basis
-- Send messages back to the chat
-
-## Communication
-
-Be concise — every message costs the reader's attention.
-
-### Destinations
-
-Each turn, your system prompt lists the destinations available to you. If you only have one destination, just write your response directly — it goes there automatically. If you have multiple, wrap each message in a `<message to="name">...</message>` block:
-
-```
-<message to="family">On my way home, 15 minutes</message>
-<message to="worker-1">kick off the pipeline</message>
-```
-
-Inbound messages are labeled with `from="name"` so you can tell which destination they came from and reply using that same name.
-
-### Mid-turn updates
-
-Use the `mcp__nanoclaw__send_message` tool to send a message mid-work (before your final output). If you have one destination, `to` is optional; with multiple, specify it. Pace your updates to the length of the work:
-
-- **Short work (a few seconds, ≤2 quick tool calls):** Don't narrate. Just do it and put the result in your final response.
-- **Longer work (many tool calls, web searches, installs, sub-agents):** Send a short acknowledgment right away ("On it — checking the logs now") so the user knows you got the message.
-- **Long-running work (many minutes, multi-step tasks):** Send periodic updates at natural milestones, and especially **before** slow operations like spinning up an explore sub-agent, downloading large files, or installing packages.
-
-**Never narrate micro-steps.** "I'm going to read the file now… okay, I'm reading it… now I'm parsing it…" is noise. Updates should mark meaningful transitions, not every tool call.
-
-**Outcomes, not play-by-play.** When the work is done, the final message should be about the result, not a transcript of what you did.
-
-### Internal thoughts
-
-Wrap reasoning in `<internal>...</internal>` tags to mark it as scratchpad — logged but not sent. With multiple destinations, any text outside of `<message>` blocks is also treated as scratchpad. With a single destination, only explicit `<internal>` tags are scratchpad; the rest of your response is sent.
-
-```
-<internal>Compiled all three reports, ready to summarize.</internal>
-
-Here are the key findings from the research…
-```
-
-### Sub-agents and teammates
-
-When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
-
-## Your Workspace
-
-Files you create are saved in `/workspace/group/`. Use this for notes, research, or anything that should persist.
-
-## Memory
-
-The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
-
-When you learn something important:
-- Create files for structured data (e.g., `customers.md`, `preferences.md`)
-- Split files larger than 500 lines into folders
-- Keep an index in your memory for the files you create
-
-## Message Formatting
-
-Format messages based on the channel you're responding to. Check your group folder name:
-
-### Slack channels (folder starts with `slack_`)
-
-Use Slack mrkdwn syntax. Run `/slack-formatting` for the full reference. Key rules:
-- `*bold*` (single asterisks)
-- `_italic_` (underscores)
-- `<https://url|link text>` for links (NOT `[text](url)`)
-- `•` bullets (no numbered lists)
-- `:emoji:` shortcodes
-- `>` for block quotes
-- No `##` headings — use `*Bold text*` instead
-
-### WhatsApp/Telegram channels (folder starts with `whatsapp_` or `telegram_`)
-
-- `*bold*` (single asterisks, NEVER **double**)
-- `_italic_` (underscores)
-- `•` bullet points
-- ` ``` ` code blocks
-
-No `##` headings. No `[links](url)`. No `**double stars**`.
-
-### Discord channels (folder starts with `discord_`)
-
-Standard Markdown works: `**bold**`, `*italic*`, `[links](url)`, `# headings`.
-
----
-
-## Installing Packages & Tools
-
-Your container is ephemeral — anything installed via `apt-get` or `pnpm install -g` is lost on restart. To install packages that persist, use the self-modification tools:
-
-1. **`install_packages`** — request system (apt) or global npm packages. Requires admin approval.
-2. **`request_rebuild`** — rebuild your container image so approved packages are baked in. Always call this after `install_packages` to apply the changes.
-
-Example flow:
-```
-install_packages({ apt: ["ffmpeg"], npm: ["@xenova/transformers"], reason: "Audio transcription" })
-# → Admin gets an approval card → approves
-request_rebuild({ reason: "Apply ffmpeg + transformers" })
-# → Admin approves → image rebuilt with the packages
-```
-
-**When to use this vs workspace pnpm install:**
-- `pnpm install` in `/workspace/agent/` persists on disk (it's mounted) but isn't on the global PATH — use it for project-level dependencies
-- `install_packages` is for system tools (ffmpeg, imagemagick) and global npm packages that need to be on PATH
-
-### MCP Servers
-
-Use **`add_mcp_server`** to add an MCP server to your configuration, then **`request_rebuild`** to apply. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `pnpm dlx`, e.g.:
-
-```
-add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
-request_rebuild({ reason: "Add memory MCP server" })
-```
-
-## Task Scripts
-
-For any recurring task, use `schedule_task`. This is the scheduling path — tasks persist across sessions and restarts, and support the pre-task `script` hook described below. Other scheduling tools you might discover (e.g. `CronCreate`, `ScheduleWakeup`) are session-scoped SDK builtins and won't behave the way NanoClaw users expect, so stick with `schedule_task`.
-
-To inspect or change existing tasks, use `list_tasks` (returns one row per series with the stable id) and `update_task` / `cancel_task` / `pause_task` / `resume_task`. Prefer `update_task` over cancel + reschedule — it preserves the series id the user already knows.
-
-Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
-
-### How it works
-
-1. You provide a bash `script` alongside the `prompt` when scheduling
-2. When the task fires, the script runs first (30-second timeout)
-3. Script prints JSON to stdout: `{ "wakeAgent": true/false, "data": {...} }`
-4. If `wakeAgent: false` — nothing happens, task waits for next run
-5. If `wakeAgent: true` — you wake up and receive the script's data + prompt
-
-### Always test your script first
-
-Before scheduling, run the script in your sandbox to verify it works:
-
-```bash
-bash -c 'node --input-type=module -e "
-  const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
-  const prs = await r.json();
-  console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
-"'
-```
-
-### When NOT to use scripts
-
-If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt.
-
-### Frequent task guidance
-
-If a user wants tasks running more than ~2x daily and a script can't reduce agent wake-ups:
-
-- Explain that each wake-up uses API credits and risks rate limits
-- Suggest restructuring with a script that checks the condition first
-- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
-- Help the user find the minimum viable frequency

groups/main/CLAUDE.md

@@ -1,312 +0,0 @@
-@./.claude-global.md
-# Main
-
-You are Main, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
-
-## What You Can Do
-
-- Answer questions and have conversations
-- Search the web and fetch content from URLs
-- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
-- Read and write files in your workspace
-- Run bash commands in your sandbox
-- Schedule tasks to run later or on a recurring basis
-- Send messages back to the chat
-
-## Communication
-
-Your output is sent to the user or group.
-
-You also have `mcp__nanoclaw__send_message` which sends a message immediately while you're still working. This is useful when you want to acknowledge a request before starting longer work.
-
-### Internal thoughts
-
-If part of your output is internal reasoning rather than something for the user, wrap it in `<internal>` tags:
-
-```
-<internal>Compiled all three reports, ready to summarize.</internal>
-
-Here are the key findings from the research...
-```
-
-Text inside `<internal>` tags is logged but not sent to the user. If you've already sent the key information via `send_message`, you can wrap the recap in `<internal>` to avoid sending it again.
-
-### Sub-agents and teammates
-
-When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
-
-## Memory
-
-The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
-
-When you learn something important:
-- Create files for structured data (e.g., `customers.md`, `preferences.md`)
-- Split files larger than 500 lines into folders
-- Keep an index in your memory for the files you create
-
-## Message Formatting
-
-Format messages based on the channel. Check the group folder name prefix:
-
-### Slack channels (folder starts with `slack_`)
-
-Use Slack mrkdwn syntax. Run `/slack-formatting` for the full reference. Key rules:
-- `*bold*` (single asterisks)
-- `_italic_` (underscores)
-- `<https://url|link text>` for links (NOT `[text](url)`)
-- `•` bullets (no numbered lists)
-- `:emoji:` shortcodes like `:white_check_mark:`, `:rocket:`
-- `>` for block quotes
-- No `##` headings — use `*Bold text*` instead
-
-### WhatsApp/Telegram (folder starts with `whatsapp_` or `telegram_`)
-
-- `*bold*` (single asterisks, NEVER **double**)
-- `_italic_` (underscores)
-- `•` bullet points
-- ` ``` ` code blocks
-
-No `##` headings. No `[links](url)`. No `**double stars**`.
-
-### Discord (folder starts with `discord_`)
-
-Standard Markdown: `**bold**`, `*italic*`, `[links](url)`, `# headings`.
-
----
-
-## Admin Context
-
-This is the **main channel**, which has elevated privileges.
-
-## Authentication
-
-Anthropic credentials must be either an API key from console.anthropic.com (`ANTHROPIC_API_KEY`) or a long-lived OAuth token from `claude setup-token` (`CLAUDE_CODE_OAUTH_TOKEN`). Short-lived tokens from the system keychain or `~/.claude/.credentials.json` expire within hours and can cause recurring container 401s. The `/setup` skill walks through this. OneCLI manages credentials (including Anthropic auth) — run `onecli --help`.
-
-## Container Mounts
-
-Main has read-only access to the project, read-write access to the store (SQLite DB), and read-write access to its group folder:
-
-| Container Path | Host Path | Access |
-|----------------|-----------|--------|
-| `/workspace/project` | Project root | read-only |
-| `/workspace/project/store` | `store/` | read-write |
-| `/workspace/group` | `groups/main/` | read-write |
-
-Key paths inside the container:
-- `/workspace/project/store/messages.db` - SQLite database (read-write)
-- `/workspace/project/store/messages.db` (registered_groups table) - Group config
-- `/workspace/project/groups/` - All group folders
-
----
-
-## Managing Groups
-
-### Finding Available Groups
-
-Available groups are provided in `/workspace/ipc/available_groups.json`:
-
-```json
-{
-  "groups": [
-    {
-      "jid": "120363336345536173@g.us",
-      "name": "Family Chat",
-      "lastActivity": "2026-01-31T12:00:00.000Z",
-      "isRegistered": false
-    }
-  ],
-  "lastSync": "2026-01-31T12:00:00.000Z"
-}
-```
-
-Groups are ordered by most recent activity. The list is synced from WhatsApp daily.
-
-If a group the user mentions isn't in the list, request a fresh sync:
-
-```bash
-echo '{"type": "refresh_groups"}' > /workspace/ipc/tasks/refresh_$(date +%s).json
-```
-
-Then wait a moment and re-read `available_groups.json`.
-
-**Fallback**: Query the SQLite database directly:
-
-```bash
-sqlite3 /workspace/project/store/messages.db "
-  SELECT jid, name, last_message_time
-  FROM chats
-  WHERE jid LIKE '%@g.us' AND jid != '__group_sync__'
-  ORDER BY last_message_time DESC
-  LIMIT 10;
-"
-```
-
-### Registered Groups Config
-
-Groups are registered in the SQLite `registered_groups` table:
-
-```json
-{
-  "1234567890-1234567890@g.us": {
-    "name": "Family Chat",
-    "folder": "whatsapp_family-chat",
-    "trigger": "@Andy",
-    "added_at": "2024-01-31T12:00:00.000Z"
-  }
-}
-```
-
-Fields:
-- **Key**: The chat JID (unique identifier — WhatsApp, Telegram, Slack, Discord, etc.)
-- **name**: Display name for the group
-- **folder**: Channel-prefixed folder name under `groups/` for this group's files and memory
-- **trigger**: The trigger word (usually same as global, but could differ)
-- **requiresTrigger**: Whether `@trigger` prefix is needed (default: `true`). Set to `false` for solo/personal chats where all messages should be processed
-- **isMain**: Whether this is the main control group (elevated privileges, no trigger required)
-- **added_at**: ISO timestamp when registered
-
-### Trigger Behavior
-
-- **Main group** (`isMain: true`): No trigger needed — all messages are processed automatically
-- **Groups with `requiresTrigger: false`**: No trigger needed — all messages processed (use for 1-on-1 or solo chats)
-- **Other groups** (default): Messages must start with `@AssistantName` to be processed
-
-### Adding a Group
-
-1. Query the database to find the group's JID
-2. Ask the user whether the group should require a trigger word before registering
-3. Use the `register_group` MCP tool with the JID, name, folder, trigger, and the chosen `requiresTrigger` setting
-4. Optionally include `containerConfig` for additional mounts
-5. The group folder is created automatically: `/workspace/project/groups/{folder-name}/`
-6. Optionally create an initial `CLAUDE.md` for the group
-
-Folder naming convention — channel prefix with underscore separator:
-- WhatsApp "Family Chat" → `whatsapp_family-chat`
-- Telegram "Dev Team" → `telegram_dev-team`
-- Discord "General" → `discord_general`
-- Slack "Engineering" → `slack_engineering`
-- Use lowercase, hyphens for the group name part
-
-#### Adding Additional Directories for a Group
-
-Groups can have extra directories mounted. Add `containerConfig` to their entry:
-
-```json
-{
-  "1234567890@g.us": {
-    "name": "Dev Team",
-    "folder": "dev-team",
-    "trigger": "@Andy",
-    "added_at": "2026-01-31T12:00:00Z",
-    "containerConfig": {
-      "additionalMounts": [
-        {
-          "hostPath": "~/projects/webapp",
-          "containerPath": "webapp",
-          "readonly": false
-        }
-      ]
-    }
-  }
-}
-```
-
-The directory will appear at `/workspace/extra/webapp` in that group's container.
-
-#### Sender Allowlist
-
-After registering a group, explain the sender allowlist feature to the user:
-
-> This group can be configured with a sender allowlist to control who can interact with me. There are two modes:
->
-> - **Trigger mode** (default): Everyone's messages are stored for context, but only allowed senders can trigger me with @{AssistantName}.
-> - **Drop mode**: Messages from non-allowed senders are not stored at all.
->
-> For closed groups with trusted members, I recommend setting up an allow-only list so only specific people can trigger me. Want me to configure that?
-
-If the user wants to set up an allowlist, edit `~/.config/nanoclaw/sender-allowlist.json` on the host:
-
-```json
-{
-  "default": { "allow": "*", "mode": "trigger" },
-  "chats": {
-    "<chat-jid>": {
-      "allow": ["sender-id-1", "sender-id-2"],
-      "mode": "trigger"
-    }
-  },
-  "logDenied": true
-}
-```
-
-Notes:
-- Your own messages (`is_from_me`) explicitly bypass the allowlist in trigger checks. Bot messages are filtered out by the database query before trigger evaluation, so they never reach the allowlist.
-- If the config file doesn't exist or is invalid, all senders are allowed (fail-open)
-- The config file is on the host at `~/.config/nanoclaw/sender-allowlist.json`, not inside the container
-
-### Removing a Group
-
-1. Read `/workspace/project/data/registered_groups.json`
-2. Remove the entry for that group
-3. Write the updated JSON back
-4. The group folder and its files remain (don't delete them)
-
-### Listing Groups
-
-Read `/workspace/project/data/registered_groups.json` and format it nicely.
-
----
-
-## Global Memory
-
-You can read and write to `/workspace/global/CLAUDE.md` for facts that should apply to all groups. Only update global memory when explicitly asked to "remember this globally" or similar.
-
----
-
-## Scheduling for Other Groups
-
-When scheduling tasks for other groups, use the `target_group_jid` parameter with the group's JID from `registered_groups.json`:
-- `schedule_task(prompt: "...", schedule_type: "cron", schedule_value: "0 9 * * 1", target_group_jid: "120363336345536173@g.us")`
-
-The task will run in that group's context with access to their files and memory.
-
----
-
-## Task Scripts
-
-For any recurring task, use `schedule_task`. Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
-
-Use `list_tasks` to see existing tasks (one row per series with the stable id), and `update_task` / `cancel_task` / `pause_task` / `resume_task` to modify them. Prefer `update_task` over cancel + reschedule when adjusting an existing task.
-
-### How it works
-
-1. You provide a bash `script` alongside the `prompt` when scheduling
-2. When the task fires, the script runs first (30-second timeout)
-3. Script prints JSON to stdout: `{ "wakeAgent": true/false, "data": {...} }`
-4. If `wakeAgent: false` — nothing happens, task waits for next run
-5. If `wakeAgent: true` — you wake up and receive the script's data + prompt
-
-### Always test your script first
-
-Before scheduling, run the script in your sandbox to verify it works:
-
-```bash
-bash -c 'node --input-type=module -e "
-  const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
-  const prs = await r.json();
-  console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
-"'
-```
-
-### When NOT to use scripts
-
-If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt.
-
-### Frequent task guidance
-
-If a user wants tasks running more than ~2x daily and a script can't reduce agent wake-ups:
-
-- Explain that each wake-up uses API credits and risks rate limits
-- Suggest restructuring with a script that checks the condition first
-- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
-- Help the user find the minimum viable frequency