style: fix prettier formatting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/skills/add-gmail-tool/SKILL.md

@@ -82,11 +82,14 @@ For each target agent group, confirm OneCLI will inject Gmail secrets into its c
 onecli agents list
 ```
 
-If that agent's `secretMode` is `all`, you're done — Gmail secrets (identified by OneCLI's Gmail hostPattern) will auto-inject. If it's `selective`, explicitly assign the Gmail secrets:
+If that agent's `secretMode` is `all`, you're done — Gmail secrets (identified by OneCLI's Gmail hostPattern) will auto-inject. If it's `selective`, explicitly assign the Gmail secrets using the safe merge pattern (`set-secrets` replaces the entire list — always read first):
 
 ```bash
-onecli secrets list     # find Gmail secret IDs (OneCLI creates one per connected app)
-onecli agents set-secrets --id <agent-id> --secret-ids <gmail-secret-id>
+GMAIL_IDS=$(onecli secrets list | jq -r '[.data[] | select(.name | test("(?i)gmail")) | .id] | join(",")')
+CURRENT=$(onecli agents secrets --id <agent-id> | jq -r '[.data[]] | join(",")')
+MERGED=$(printf '%s' "$CURRENT,$GMAIL_IDS" | tr ',' '\n' | sort -u | paste -sd ',' -)
+onecli agents set-secrets --id <agent-id> --secret-ids "$MERGED"
+onecli agents secrets --id <agent-id>
 ```
 
 ## Phase 2: Apply Code Changes

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

@@ -0,0 +1,208 @@
+---
+name: add-mnemon
+description: Add persistent graph-based memory via mnemon. Agents recall past context before responding and remember insights after each turn.
+---
+
+# Add Mnemon — Persistent Memory
+
+Installs [mnemon](https://github.com/mnemon-dev/mnemon) in the agent container image. On each container start, `mnemon setup` registers Claude Code hooks that surface relevant memory before the agent responds and store new insights after each turn. Memory is written to the per-agent-group `.claude/` mount and survives container restarts.
+
+## Provider Compatibility
+
+**mnemon hooks only work with `--target claude-code`.** If the agent group uses `AGENT_PROVIDER=opencode`, hooks registered by `mnemon setup` will never fire — OpenCode spawns its own process and doesn't invoke the `claude` CLI at all.
+
+Check your provider:
+
+```bash
+grep AGENT_PROVIDER .env groups/*/container.json 2>/dev/null
+```
+
+- `AGENT_PROVIDER=claude` (default) — fully compatible, proceed with both Phase 2 steps.
+- `AGENT_PROVIDER=opencode` — use **Phase 2 (OpenCode path)** instead of the standard entrypoint step.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+```bash
+grep -q 'MNEMON_VERSION' container/Dockerfile && echo "Already applied" || echo "Not applied"
+```
+
+If already applied, skip to Phase 3 (Verify).
+
+### Check latest mnemon version
+
+```bash
+curl -fsSL https://api.github.com/repos/mnemon-dev/mnemon/releases/latest | grep '"tag_name"'
+```
+
+Note the version (e.g. `v0.1.1`) — use it as `MNEMON_VERSION` in the next step.
+
+## Phase 2: Apply Changes (Claude Code path)
+
+### 1. Dockerfile — install mnemon binary
+
+Add after the AWS CLI block, before the Bun runtime section:
+
+```dockerfile
+# ---- mnemon — persistent agent memory ----------------------------------------
+ARG MNEMON_VERSION=0.1.1
+RUN ARCH=$(dpkg --print-architecture) && \
+    curl -fsSL "https://github.com/mnemon-dev/mnemon/releases/download/v${MNEMON_VERSION}/mnemon_${MNEMON_VERSION}_linux_${ARCH}.tar.gz" \
+    | tar -xz -C /usr/local/bin mnemon && \
+    chmod +x /usr/local/bin/mnemon
+
+ENV MNEMON_DATA_DIR=/home/node/.claude/mnemon
+```
+
+`MNEMON_DATA_DIR` points into the per-agent-group `.claude/` mount so memory persists across container restarts. No extra volume mounts needed.
+
+### 2. Entrypoint — run mnemon setup on each container start
+
+`mnemon setup` is idempotent. Edit `container/entrypoint.sh` to run it right after `set -e`, before the `cat` that captures stdin:
+
+```bash
+#!/bin/bash
+# NanoClaw agent container entrypoint.
+#
+# ...existing header comment...
+
+set -e
+
+mnemon setup --target claude-code --yes --global >/dev/stderr 2>&1
+
+cat > /tmp/input.json
+
+exec bun run /app/src/index.ts < /tmp/input.json
+```
+
+`>/dev/stderr 2>&1` routes all mnemon output to stderr (docker logs) so it doesn't interfere with the JSON stdin handshake between host and agent-runner.
+
+### 3. Rebuild and smoke-test the image
+
+```bash
+./container/build.sh
+docker run --rm --entrypoint mnemon nanoclaw-agent:latest --version
+```
+
+## Phase 3: Restart and Verify
+
+### Restart the service
+
+```bash
+systemctl --user restart nanoclaw          # Linux
+# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+### Confirm mnemon hooks are registered
+
+After the next container starts, check that setup ran:
+
+```bash
+docker logs $(docker ps --filter name=nanoclaw-v2 --format '{{.Names}}' | head -1) 2>&1 | grep -i mnemon
+```
+
+Then inspect the hooks inside the running container:
+
+```bash
+docker exec $(docker ps --filter name=nanoclaw-v2 --format '{{.Names}}' | head -1) \
+  cat /home/node/.claude/settings.json | grep -A5 mnemon
+```
+
+### Test memory recall
+
+Have a conversation with the agent, then start a new session and reference something from the earlier one. Mnemon should surface the relevant context automatically without you restating it.
+
+## Phase 2 (OpenCode path) — context injection
+
+mnemon hooks don't fire under OpenCode. Instead, the agent-runner injects mnemon context directly into every prompt via `wrapPromptWithContext()` in `container/agent-runner/src/providers/opencode.ts`. This is already implemented in NanoClaw — no code changes needed if you're on current `ester`/`main`.
+
+**How it works:** On each prompt, `readMnemonContext()` checks for `MNEMON_DATA_DIR` (set by the Dockerfile `ENV`). If the env var is present, it reads `$MNEMON_DATA_DIR/prompt/guide.md` (mnemon's custom prompt guide, written by `mnemon setup`) or falls back to an inline guide. The content is prepended as a `<system>` block, instructing the agent to run `mnemon recall` at the start of relevant tasks and `mnemon remember` after key decisions.
+
+**What this means for the agent:** The agent (running inside OpenCode) can call `mnemon recall`, `mnemon remember`, `mnemon link`, and `mnemon status` via its bash tool. mnemon writes its graph to `$MNEMON_DATA_DIR`, which is in the per-agent-group `.claude/` mount — so memory persists across container restarts.
+
+**Applying:** Only the Dockerfile step from Phase 2 is needed for OpenCode agents. Skip `container/entrypoint.sh` entirely.
+
+```dockerfile
+ARG MNEMON_VERSION=0.1.1
+RUN ARCH=$(dpkg --print-architecture) && \
+    curl -fsSL "https://github.com/mnemon-dev/mnemon/releases/download/v${MNEMON_VERSION}/mnemon_${MNEMON_VERSION}_linux_${ARCH}.tar.gz" \
+    | tar -xz -C /usr/local/bin mnemon && \
+    chmod +x /usr/local/bin/mnemon
+ENV MNEMON_DATA_DIR=/home/node/.claude/mnemon
+```
+
+Then rebuild: `./container/build.sh`
+
+### Verify (OpenCode)
+
+Start a session and ask the agent to run `mnemon status`. It should report empty graphs (no error) on first run.
+
+```bash
+# Also confirm the binary is present in the image:
+docker run --rm --entrypoint mnemon nanoclaw-agent:latest --version
+```
+
+## Memory Storage
+
+Mnemon writes to `/home/node/.claude/mnemon/` inside the container, which maps to the per-agent-group `.claude/` directory on the host. To find the exact host path:
+
+```bash
+docker inspect $(docker ps --filter name=nanoclaw-v2 --format '{{.Names}}' | head -1) \
+  --format '{{range .Mounts}}{{if eq .Destination "/home/node/.claude"}}{{.Source}}{{end}}{{end}}'
+```
+
+To reset all memory for an agent, stop the container and delete the `mnemon/` subdirectory from that host path.
+
+## Migration Guide Update
+
+If you are using `/migrate-nanoclaw`, add these entries to `.nanoclaw-migrations/05-dockerfile.md`:
+
+**Dockerfile — after AWS CLI, before Bun runtime:**
+```dockerfile
+ARG MNEMON_VERSION=0.1.1
+RUN ARCH=$(dpkg --print-architecture) && \
+    curl -fsSL "https://github.com/mnemon-dev/mnemon/releases/download/v${MNEMON_VERSION}/mnemon_${MNEMON_VERSION}_linux_${ARCH}.tar.gz" \
+    | tar -xz -C /usr/local/bin mnemon && \
+    chmod +x /usr/local/bin/mnemon
+ENV MNEMON_DATA_DIR=/home/node/.claude/mnemon
+```
+
+**`container/entrypoint.sh` — add after `set -e`:**
+```bash
+mnemon setup --target claude-code --yes --global >/dev/stderr 2>&1
+```
+
+## Troubleshooting
+
+### `mnemon: command not found` in container
+
+The image wasn't rebuilt after adding the Dockerfile layer. Run `./container/build.sh` and restart.
+
+### Memory not persisting across restarts
+
+Verify `MNEMON_DATA_DIR` resolves to a mounted path (not an in-container ephemeral directory):
+
+```bash
+docker exec <container> sh -c 'ls -la $MNEMON_DATA_DIR'
+```
+
+If the directory is empty after conversations, the mount is missing or the path is wrong. Check the host mount with the `docker inspect` command above.
+
+### Agent not using past memory
+
+`mnemon setup` writes hooks into `/home/node/.claude/settings.json`. Verify:
+
+```bash
+docker exec <container> cat /home/node/.claude/settings.json
+```
+
+If the hooks are absent, `mnemon setup` may have failed silently. Check container startup logs for errors from mnemon.
+
+### Setup fails at container start
+
+Run setup manually inside a running container to see the full error:
+
+```bash
+docker exec -it <container> mnemon setup --target claude-code --yes --global
+```

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

@@ -132,12 +132,15 @@ Credentials: register provider API keys in OneCLI with the matching `--host-patt
 
 After adding a secret, **grant the agent access** — agents in `selective` mode only receive secrets they've been explicitly assigned:
 
-```bash
-# Find the agent id and secret id, then:
-onecli agents set-secrets --id <agent-id> --secret-ids <existing-ids>,<new-secret-id>
-```
+Use the safe merge pattern — `set-secrets` replaces the entire list, so always read first:
 
-Always include existing secret IDs in the list — `set-secrets` replaces, not appends.
+```bash
+AGENT_ID=$(onecli agents list | jq -r '.data[] | select(.identifier=="<agentGroupId>") | .id')
+CURRENT=$(onecli agents secrets --id "$AGENT_ID" | jq -r '[.data[]] | join(",")')
+MERGED=$(printf '%s' "$CURRENT,<new-secret-id>" | tr ',' '\n' | sort -u | paste -sd ',' -)
+onecli agents set-secrets --id "$AGENT_ID" --secret-ids "$MERGED"
+onecli agents secrets --id "$AGENT_ID"
+```
 
 #### Example: DeepSeek
 

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

@@ -284,6 +284,11 @@ If you see `Signal daemon not reachable at 127.0.0.1:7583` and `SIGNAL_MANAGE_DA
 1. Channel initialized: `grep "Signal channel connected" logs/nanoclaw.log | tail -1`
 2. Channel wired: `pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id, mg.name FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id WHERE mg.channel_type='signal'"`
 3. Service running: `launchctl print gui/$(id -u)/com.nanoclaw` (macOS) / `systemctl --user status nanoclaw` (Linux)
+4. **Check for duplicate service instances** — if `logs/nanoclaw.error.log` shows `No adapter for channel type channelType="signal"` despite the adapter starting, two NanoClaw processes are racing. See the `/debug` skill section "No adapter for channel type / Messages silently lost" for the full fix.
+
+### Messages delivered but never arrive (null platformMsgId)
+
+Signal responses show `platformMsgId=undefined` in the main log. This means the delivery poll ran but found no adapter — likely a duplicate service instance issue (see above). Affected messages cannot be retried; the user must resend.
 
 ### Lost connection mid-session
 

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

@@ -90,12 +90,12 @@ onecli secrets list | grep -i vercel
 OneCLI uses selective secret mode — secrets must be explicitly assigned to each agent. Get the Vercel secret ID from the output above, then assign it to every agent:
 
 ```bash
-# For each agent, add the Vercel secret to its assigned secrets list.
-# First get current assignments, then set them with the new secret appended.
-VERCEL_SECRET_ID=$(onecli secrets list 2>/dev/null | grep -B2 "Vercel" | grep '"id"' | head -1 | sed 's/.*"id": "//;s/".*//')
-for agent in $(onecli agents list 2>/dev/null | grep '"id"' | sed 's/.*"id": "//;s/".*//'); do
-  CURRENT=$(onecli agents secrets --id "$agent" 2>/dev/null | grep '"' | grep -v hint | grep -v data | sed 's/.*"//;s/".*//' | tr '\n' ',' | sed 's/,$//')
-  onecli agents set-secrets --id "$agent" --secret-ids "${CURRENT:+$CURRENT,}$VERCEL_SECRET_ID"
+# set-secrets replaces the entire list — read and merge for each agent.
+VERCEL_SECRET_ID=$(onecli secrets list | jq -r '.data[] | select(.name | test("(?i)vercel")) | .id' | head -1)
+for agent in $(onecli agents list | jq -r '.data[].id'); do
+  CURRENT=$(onecli agents secrets --id "$agent" | jq -r '[.data[]] | join(",")')
+  MERGED=$(printf '%s' "$CURRENT,$VERCEL_SECRET_ID" | tr ',' '\n' | sort -u | paste -sd ',' -)
+  onecli agents set-secrets --id "$agent" --secret-ids "$MERGED"
 done
 ```
 

.claude/skills/debug/SKILL.md

@@ -57,7 +57,50 @@ Debug level shows:
 
 ## Common Issues
 
-### 1. "Claude Code process exited with code 1"
+### 1. "No adapter for channel type" / Messages silently lost (null platformMsgId)
+
+**Symptom:** The bot stops replying. `logs/nanoclaw.error.log` shows repeated:
+```
+WARN No adapter for channel type channelType="telegram"
+WARN No adapter for channel type channelType="signal"
+```
+The main log shows "Message delivered" entries with `platformMsgId=undefined` — meaning the delivery poll ran, found no adapter, and permanently marked the message as delivered without sending it.
+
+**Root cause: two NanoClaw service instances running simultaneously.**
+
+When a second service instance (often `nanoclaw-v2-<id>.service` running alongside `nanoclaw.service`) is active with a stale binary, it has no channel adapters registered. Its delivery poll races against the working instance and wins — permanently marking outbound messages as delivered without ever sending them.
+
+**Diagnosis:**
+```bash
+# Check for duplicate running instances
+ps aux | grep 'nanoclaw/dist/index.js' | grep -v grep
+
+# Check which services are active
+systemctl --user list-units 'nanoclaw*' --all
+
+# Confirm channel adapters registered by the current process
+grep "Channel adapter started" logs/nanoclaw.log | tail -10
+```
+
+**Fix:**
+1. Identify which service has the correct binary and EnvironmentFile (the one showing `signal`, `telegram`, `cli` all started in the log).
+2. Stop and disable the stale duplicate service:
+   ```bash
+   systemctl --user stop nanoclaw.service   # or whichever is the old one
+   systemctl --user disable nanoclaw.service
+   ```
+3. If the remaining service unit is missing `EnvironmentFile`, add it:
+   ```bash
+   # Edit the service unit — add this line under [Service]:
+   # EnvironmentFile=/home/[user]/nanoclaw/.env
+   systemctl --user daemon-reload
+   systemctl --user restart nanoclaw-v2-<id>.service
+   ```
+4. Verify only one instance runs: `ps aux | grep nanoclaw/dist/index.js | grep -v grep`
+
+**Note:** Messages that were marked delivered with a null `platform_message_id` cannot be automatically retried — they are permanently lost. The user must resend their message.
+
+### 2. "Claude Code process exited with code 1"
 
 **Check the container log file** in `groups/{folder}/logs/container-*.log`
 

.claude/skills/init-onecli/SKILL.md

@@ -259,6 +259,41 @@ Tell the user:
 - To manage secrets: `onecli secrets list`, or open ${ONECLI_URL}
 - To add rate limits or policies: `onecli rules create --help`
 
+## Granting secrets to agents (safe merge)
+
+`set-secrets` **replaces** the agent's entire secret list — it never appends. Always read the current list first and merge before calling it. This pattern is canonical across all skills that assign secrets:
+
+```bash
+AGENT_ID=$(onecli agents list | jq -r '.data[] | select(.identifier=="<agentGroupId>") | .id')
+CURRENT=$(onecli agents secrets --id "$AGENT_ID" | jq -r '[.data[]] | join(",")')
+MERGED=$(printf '%s' "$CURRENT,<new-secret-id>" | tr ',' '\n' | sort -u | paste -sd ',' -)
+onecli agents set-secrets --id "$AGENT_ID" --secret-ids "$MERGED"
+onecli agents secrets --id "$AGENT_ID"
+```
+
+- `<agentGroupId>` — the `agentGroupId` field in `groups/<folder>/container.json`
+- `<new-secret-id>` — the `id` from `onecli secrets list`
+- Multiple new secrets: append them comma-separated before the `printf` step
+
+### git over HTTPS
+
+OneCLI's proxy injects credentials proactively — `injections_applied=1` appears in `docker logs onecli` even when git sends no auth header. However, OneCLI sets `SSL_CERT_FILE` for Node/Python/Deno but not `GIT_SSL_CAINFO`. Without it, git rejects the OneCLI MITM certificate.
+
+**Auth format matters**: GitHub's git smart HTTP protocol (`github.com`) requires `Basic` auth, not `Bearer`. GitHub's REST API (`api.github.com`) accepts `Bearer`. These must be configured as separate secrets with different formats — see `/add-github` for the full setup.
+
+If an agent uses `git` or `gh`, add to `data/v2-sessions/<agent-group-id>/.claude-shared/settings.json`:
+
+```json
+"GIT_SSL_CAINFO": "/tmp/onecli-combined-ca.pem",
+"GIT_TERMINAL_PROMPT": "0",
+"GIT_CONFIG_COUNT": "1",
+"GIT_CONFIG_KEY_0": "credential.helper",
+"GIT_CONFIG_VALUE_0": "",
+"GH_TOKEN": "ghp_onecli_proxy_replaces_this"
+```
+
+**Debugging injection**: `docker logs onecli 2>&1 | grep "github.com"` shows every request with `injections_applied=N` and the HTTP status. If `injections_applied=1` but status is still 401, the injected credential value is wrong or uses the wrong auth format for that endpoint.
+
 ## Troubleshooting
 
 **"OneCLI gateway not reachable" in logs:** The gateway isn't running. Check with `curl -sf ${ONECLI_URL}/health`. Start it with `onecli start` if needed.

CLAUDE.md

@@ -76,11 +76,37 @@ 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 |
+| `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) |
 | `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). |
 
+## Admin CLI (`ncl`)
+
+`ncl` queries and modifies the central DB — agent groups, messaging groups, wirings, users, roles, and more. On the host it connects via Unix socket (`src/cli/socket-server.ts`); inside containers it uses the session DB transport (`container/agent-runner/src/cli/ncl.ts`).
+
+```
+ncl <resource> <verb> [<id>] [--flags]
+ncl <resource> help
+ncl help
+```
+
+| Resource | Verbs | What it is |
+|----------|-------|------------|
+| groups | list, get, create, update, delete | Agent groups (workspace, personality, container config) |
+| messaging-groups | list, get, create, update, delete | A single chat/channel on one platform |
+| wirings | list, get, create, update, delete | Links a messaging group to an agent group (session mode, triggers) |
+| users | list, get, create, update | Platform identities (`<channel>:<handle>`) |
+| roles | list, grant, revoke | Owner / admin privileges (global or scoped to an agent group) |
+| 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) |
+| 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) |
+
+Key files: `src/cli/dispatch.ts` (dispatcher + approval handler), `src/cli/crud.ts` (generic CRUD registration), `src/cli/resources/` (per-resource definitions).
+
 ## Channels and Providers (skill-installed)
 
 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:
@@ -100,7 +126,7 @@ A second tier (direct source-level self-edits via a draft/activate flow) is plan
 
 ## Secrets / Credentials / OneCLI
 
-API keys, OAuth tokens, and auth credentials are managed by the OneCLI gateway. Secrets are injected into per-agent containers at request time — none are passed in env vars or through chat context. `src/onecli-approvals.ts`, `ensureAgent()` in `container-runner.ts`. Run `onecli --help`.
+API keys, OAuth tokens, and auth credentials are managed by the OneCLI gateway. Secrets are injected into per-agent containers at request time — none are passed in env vars or through chat context. The container agent sees this via the `onecli-gateway` container skill (`container/skills/onecli-gateway/SKILL.md`), which teaches it how the proxy works, how to handle auth errors, and to never ask for raw credentials. Host-side wiring: `src/onecli-approvals.ts`, `ensureAgent()` in `container-runner.ts`. Run `onecli --help`.
 
 ### Gotcha: auto-created agents start in `selective` secret mode
 
@@ -144,7 +170,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. `/claw`).
 - **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/`: `welcome`, `self-customize`, `agent-browser`, `slack-formatting`).
+- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `onecli-gateway`, `welcome`, `self-customize`, `agent-browser`, `slack-formatting`).
 
 | Skill | When to Use |
 |-------|-------------|

bin/ncl

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# ncl — NanoClaw CLI launcher.
+#
+# Resolves the project root from this script's location, cd's there so the
+# host-resolved DATA_DIR matches the running host, and execs the TS entry
+# via tsx. Symlink this file into a directory on your PATH (or alias `ncl`
+# to its full path) to invoke from anywhere:
+#
+#   ln -s "$(pwd)/bin/ncl" /usr/local/bin/ncl
+#   # or
+#   alias ncl="$(pwd)/bin/ncl"
+
+set -euo pipefail
+
+SCRIPT="${BASH_SOURCE[0]}"
+# Resolve symlinks so PROJECT_ROOT points at the real checkout.
+while [ -h "$SCRIPT" ]; do
+  DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
+  SCRIPT="$(readlink "$SCRIPT")"
+  [[ "$SCRIPT" != /* ]] && SCRIPT="$DIR/$SCRIPT"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SCRIPT")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_ROOT"
+exec pnpm exec tsx src/cli/client.ts "$@"

container/Dockerfile

@@ -91,7 +91,13 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 #     the SDK fails at spawn time with "native binary not found".
 ENV PNPM_HOME="/pnpm"
 ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
+# Pin pnpm to match the host (package.json packageManager). pnpm 11 stopped
+# honoring `only-built-dependencies[]=` in .npmrc for global installs, which
+# silently skips claude-code's native-binary postinstall and agent-browser's
+# bin chmod — the agent then crashes at runtime with "native binary not
+# installed". Keep this in lockstep with package.json's `packageManager`.
+ARG PNPM_VERSION=10.33.0
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
 
 RUN --mount=type=cache,target=/root/.cache/pnpm \
     echo "only-built-dependencies[]=agent-browser" > /root/.npmrc && \
@@ -104,6 +110,11 @@ RUN --mount=type=cache,target=/root/.cache/pnpm \
 RUN --mount=type=cache,target=/root/.cache/pnpm \
     pnpm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
 
+# ---- ncl CLI wrapper ----------------------------------------------------------
+# Actual script lives in the mounted source at /app/src/cli/ncl.ts.
+RUN printf '#!/bin/sh\nexec bun /app/src/cli/ncl.ts "$@"\n' > /usr/local/bin/ncl && \
+    chmod +x /usr/local/bin/ncl
+
 # ---- Entrypoint --------------------------------------------------------------
 COPY entrypoint.sh /app/entrypoint.sh
 RUN chmod +x /app/entrypoint.sh

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

@@ -0,0 +1,257 @@
+#!/usr/bin/env bun
+/**
+ * ncl — NanoClaw CLI client (container edition).
+ *
+ * Same interface as the host-side `bin/ncl`. Detects that it's inside a
+ * container (the session DBs exist at /workspace/) and uses a DB transport
+ * instead of the Unix socket transport.
+ *
+ * Writes a cli_request system message to outbound.db, polls inbound.db
+ * for the response. Self-contained — no imports from agent-runner.
+ */
+import { Database } from 'bun:sqlite';
+
+// ---------------------------------------------------------------------------
+// Frame types (mirrors src/cli/frame.ts on the host)
+// ---------------------------------------------------------------------------
+
+type RequestFrame = {
+  id: string;
+  command: string;
+  args: Record<string, unknown>;
+};
+
+type ResponseFrame =
+  | { id: string; ok: true; data: unknown }
+  | { id: string; ok: false; error: { code: string; message: string } };
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const INBOUND_DB = '/workspace/inbound.db';
+const OUTBOUND_DB = '/workspace/outbound.db';
+
+// ---------------------------------------------------------------------------
+// DB transport
+// ---------------------------------------------------------------------------
+
+function generateId(): string {
+  return `cli-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Write a cli_request to outbound.db.
+ *
+ * Uses BEGIN IMMEDIATE to acquire a write lock before reading max(seq),
+ * preventing seq collisions with concurrent agent-runner writes.
+ */
+function writeRequest(req: RequestFrame): void {
+  const db = new Database(OUTBOUND_DB);
+  db.exec('PRAGMA journal_mode = DELETE');
+  db.exec('PRAGMA busy_timeout = 5000');
+
+  const inDb = new Database(INBOUND_DB, { readonly: true });
+  inDb.exec('PRAGMA busy_timeout = 5000');
+
+  try {
+    db.exec('BEGIN IMMEDIATE');
+    const maxOut = (db.prepare('SELECT COALESCE(MAX(seq), 0) AS m FROM messages_out').get() as { m: number }).m;
+    const maxIn = (inDb.prepare('SELECT COALESCE(MAX(seq), 0) AS m FROM messages_in').get() as { m: number }).m;
+    const max = Math.max(maxOut, maxIn);
+    const nextSeq = max % 2 === 0 ? max + 1 : max + 2;
+
+    db.prepare(
+      `INSERT INTO messages_out (id, seq, timestamp, kind, content)
+       VALUES ($id, $seq, datetime('now'), 'system', $content)`,
+    ).run({
+      $id: req.id,
+      $seq: nextSeq,
+      $content: JSON.stringify({
+        action: 'cli_request',
+        requestId: req.id,
+        command: req.command,
+        args: req.args,
+      }),
+    });
+    db.exec('COMMIT');
+  } catch (e) {
+    db.exec('ROLLBACK');
+    throw e;
+  } finally {
+    inDb.close();
+    db.close();
+  }
+}
+
+/**
+ * Poll inbound.db for a cli_response matching our requestId.
+ * Opens a fresh connection each poll (mmap_size=0) for cross-mount visibility.
+ */
+function pollResponse(requestId: string, timeoutMs: number): ResponseFrame | null {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const inDb = new Database(INBOUND_DB, { readonly: true });
+    inDb.exec('PRAGMA busy_timeout = 5000');
+    inDb.exec('PRAGMA mmap_size = 0');
+
+    try {
+      const row = inDb
+        .prepare("SELECT id, content FROM messages_in WHERE status = 'pending' AND content LIKE ?")
+        .get(`%"requestId":"${requestId}"%`) as { id: string; content: string } | null;
+
+      if (row) {
+        // Mark as completed via processing_ack so agent-runner skips it
+        const outDb = new Database(OUTBOUND_DB);
+        outDb.exec('PRAGMA journal_mode = DELETE');
+        outDb.exec('PRAGMA busy_timeout = 5000');
+        outDb
+          .prepare(
+            "INSERT OR REPLACE INTO processing_ack (message_id, status, status_changed) VALUES (?, 'completed', datetime('now'))",
+          )
+          .run(row.id);
+        outDb.close();
+
+        const parsed = JSON.parse(row.content);
+        return parsed.frame as ResponseFrame;
+      }
+    } finally {
+      inDb.close();
+    }
+
+    Bun.sleepSync(500);
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing (mirrors host-side client.ts)
+// ---------------------------------------------------------------------------
+
+function parseArgv(argv: string[]): {
+  command: string;
+  args: Record<string, unknown>;
+  json: boolean;
+} {
+  const positional: string[] = [];
+  const args: Record<string, unknown> = {};
+  let json = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i++;
+      }
+      continue;
+    }
+    positional.push(a);
+  }
+
+  if (positional.length === 0) {
+    process.stderr.write('ncl: missing command\n');
+    printUsage();
+    process.exit(2);
+  }
+
+  const command = positional.length >= 2 ? `${positional[0]}-${positional[1]}` : positional[0];
+
+  // Third positional is the target ID
+  if (positional.length >= 3) {
+    args.id = positional[2];
+  }
+
+  return { command, args, json };
+}
+
+function printUsage(): void {
+  process.stdout.write(
+    ['Usage: ncl <command> [--key value ...] [--json]', '', 'Run `ncl help` to list available commands.', ''].join('\n'),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Formatting (mirrors src/cli/format.ts on the host)
+// ---------------------------------------------------------------------------
+
+function formatHuman(resp: ResponseFrame): string {
+  if (!resp.ok) {
+    return `error (${resp.error.code}): ${resp.error.message}\n`;
+  }
+
+  const data = resp.data;
+  if (!Array.isArray(data) || data.length === 0) {
+    return JSON.stringify(data, null, 2) + '\n';
+  }
+
+  const isFlat = data.every(
+    (r) =>
+      typeof r === 'object' &&
+      r !== null &&
+      !Array.isArray(r) &&
+      Object.values(r as Record<string, unknown>).every((v) => typeof v !== 'object' || v === null),
+  );
+
+  if (!isFlat) return JSON.stringify(data, null, 2) + '\n';
+
+  const keys = Object.keys(data[0] as Record<string, unknown>);
+  const widths = keys.map((k) =>
+    Math.max(k.length, ...data.map((r) => String((r as Record<string, unknown>)[k] ?? '').length)),
+  );
+
+  const header = keys.map((k, i) => k.padEnd(widths[i])).join('  ');
+  const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+  const rows = data.map((r) =>
+    keys
+      .map((k, i) => String((r as Record<string, unknown>)[k] ?? '').padEnd(widths[i]))
+      .join('  '),
+  );
+
+  return [header, sep, ...rows, ''].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const argv = process.argv.slice(2);
+
+if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+  printUsage();
+  process.exit(0);
+}
+
+const { command, args, json } = parseArgv(argv);
+const requestId = generateId();
+const req: RequestFrame = { id: requestId, command, args };
+
+writeRequest(req);
+
+const resp = pollResponse(requestId, 30_000);
+
+if (!resp) {
+  process.stderr.write('ncl: command timed out after 30s\n');
+  process.exit(2);
+}
+
+if (json) {
+  process.stdout.write(JSON.stringify(resp, null, 2) + '\n');
+} else {
+  const output = formatHuman(resp);
+  if (!resp.ok) {
+    process.stderr.write(output);
+    process.exit(1);
+  }
+  process.stdout.write(output);
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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/destinations.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+
+import { closeSessionDb, getInboundDb, initTestSessionDb } from './db/connection.js';
+import { buildSystemPromptAddendum } from './destinations.js';
+
+beforeEach(() => {
+  initTestSessionDb();
+});
+
+afterEach(() => {
+  closeSessionDb();
+});
+
+function seedDestination(name: string, displayName: string, channelType: string, platformId: string): void {
+  getInboundDb()
+    .prepare(
+      `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+       VALUES (?, ?, 'channel', ?, ?, NULL)`,
+    )
+    .run(name, displayName, channelType, platformId);
+}
+
+describe('buildSystemPromptAddendum — multi-destination routing guidance', () => {
+  it('includes default-routing nudge when there are >1 destinations', () => {
+    seedDestination('casa', 'Casa', 'whatsapp', 'group-1@g.us');
+    seedDestination('whatsapp-mg-17780', 'whatsapp-mg-17780', 'whatsapp', 'phone-2@s.whatsapp.net');
+
+    const prompt = buildSystemPromptAddendum('Casa');
+
+    expect(prompt).toContain('Default routing');
+    expect(prompt).toContain('from="name"');
+    expect(prompt).toContain('`casa`');
+    expect(prompt).toContain('`whatsapp-mg-17780`');
+  });
+
+  it('requires explicit wrapping even for a single destination', () => {
+    seedDestination('casa', 'Casa', 'whatsapp', 'group-1@g.us');
+
+    const prompt = buildSystemPromptAddendum('Casa');
+
+    expect(prompt).toContain('Every response must be wrapped');
+    expect(prompt).toContain('<message to="name">');
+    expect(prompt).toContain('`casa`');
+  });
+
+  it('handles the no-destination case without crashing', () => {
+    const prompt = buildSystemPromptAddendum('Casa');
+
+    expect(prompt).toContain('no configured destinations');
+    expect(prompt).not.toContain('Default routing');
+  });
+
+  it('includes default-routing and wrapping instructions for single destination', () => {
+    seedDestination('casa', 'Casa', 'whatsapp', 'group-1@g.us');
+
+    const prompt = buildSystemPromptAddendum('Casa');
+
+    expect(prompt).toContain('Every response must be wrapped');
+    expect(prompt).toContain('<message to="name">');
+    expect(prompt).toContain('Default routing');
+    expect(prompt).toContain('`casa`');
+  });
+});

container/agent-runner/src/destinations.ts

@@ -120,6 +120,10 @@ function buildDestinationsSection(): string {
   lines.push('Text outside of `<message>` blocks is scratchpad — logged but not sent anywhere.');
   lines.push('Use `<internal>...</internal>` to make scratchpad intent explicit.');
   lines.push('');
+  lines.push(
+    '**Default routing**: when replying to an incoming message, address the same destination the message came `from` — every inbound `<message>` tag carries a `from="name"` attribute that names the origin destination. Only address a different destination when the request itself asks you to (e.g., "tell Laura that…").',
+  );
+  lines.push('');
   lines.push(
     'To send a message mid-response (e.g., an acknowledgment before a long task), call the `send_message` MCP tool with the `to` parameter set to a destination name.',
   );

container/agent-runner/src/integration.test.ts

@@ -3,6 +3,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
 import { initTestSessionDb, closeSessionDb, getInboundDb, getOutboundDb } from './db/connection.js';
 import { getUndeliveredMessages } from './db/messages-out.js';
 import { getPendingMessages } from './db/messages-in.js';
+import { getContinuation, setContinuation } from './db/session-state.js';
 import { MockProvider } from './providers/mock.js';
 import { runPollLoop } from './poll-loop.js';
 
@@ -112,6 +113,125 @@ describe('poll loop integration', () => {
     await loopPromise.catch(() => {});
   });
 
+  it('bare text produces no outbound messages (scratchpad only)', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'hello' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    // Agent responds with bare text — no <message to="..."> wrapping
+    const provider = new MockProvider({}, () => 'I am thinking about this...');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    // Wait long enough for the poll loop to process
+    await sleep(1000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('unknown destination is dropped, valid destination is sent', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'hi' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new MockProvider(
+      {},
+      () => '<message to="nonexistent">dropped</message><message to="discord-test">delivered</message>',
+    );
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    // Only the valid destination should produce output
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toBe('delivered');
+    expect(out[0].platform_id).toBe('chan-1');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('multiple <message> blocks each produce an outbound message', async () => {
+    getInboundDb()
+      .prepare(
+        `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+         VALUES ('slack-test', 'Slack Test', 'channel', 'slack', 'chan-2', NULL)`,
+      )
+      .run();
+
+    insertMessage('m1', { sender: 'Alice', text: 'broadcast' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new MockProvider(
+      {},
+      () => '<message to="discord-test">for discord</message><message to="slack-test">for slack</message>',
+    );
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length >= 2, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(2);
+    const discord = out.find((m) => m.platform_id === 'chan-1');
+    const slack = out.find((m) => m.platform_id === 'chan-2');
+    expect(discord).toBeDefined();
+    expect(JSON.parse(discord!.content).text).toBe('for discord');
+    expect(slack).toBeDefined();
+    expect(JSON.parse(slack!.content).text).toBe('for slack');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('sends null thread_id when no prior inbound from destination', async () => {
+    // Seed a second destination that has NO inbound messages
+    getInboundDb()
+      .prepare(
+        `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+         VALUES ('slack-new', 'Slack New', 'channel', 'slack', 'chan-new', NULL)`,
+      )
+      .run();
+
+    // Only insert a message from discord — slack-new has never sent anything
+    insertMessage('m1', { sender: 'Alice', text: 'tell slack' }, { platformId: 'chan-1', channelType: 'discord', threadId: 'discord-thread' });
+
+    const provider = new MockProvider({}, () => '<message to="slack-new">hello slack</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(out[0].platform_id).toBe('chan-new');
+    expect(out[0].thread_id).toBeNull();
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('resolves most recent thread_id when destination has multiple inbound messages', async () => {
+    // Two messages from same destination, different threads
+    insertMessage('m-old', { sender: 'Alice', text: 'old' }, { platformId: 'chan-1', channelType: 'discord', threadId: 'thread-old' });
+    insertMessage('m-new', { sender: 'Alice', text: 'new' }, { platformId: 'chan-1', channelType: 'discord', threadId: 'thread-new' });
+
+    const provider = new MockProvider({}, () => '<message to="discord-test">reply</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(out[0].thread_id).toBe('thread-new');
+    expect(out[0].in_reply_to).toBe('m-new');
+
+    await loopPromise.catch(() => {});
+  });
+
   it('should process messages arriving after loop starts', async () => {
     const provider = new MockProvider({}, () => '<message to="discord-test">Processed</message>');
     const controller = new AbortController();
@@ -129,8 +249,161 @@ describe('poll loop integration', () => {
 
     await loopPromise.catch(() => {});
   });
+
+  it('internal tags between message blocks are stripped from scratchpad', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'hi' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new MockProvider(
+      {},
+      () => '<internal>thinking about this...</internal><message to="discord-test">answer</message><internal>done thinking</internal>',
+    );
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toBe('answer');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('handles mixed task + chat batch with correct origin metadata', async () => {
+    // Seed destination for routing lookup
+    insertMessage('m-chat', { sender: 'Alice', text: 'check this' }, { platformId: 'chan-1', channelType: 'discord' });
+    // Task with same routing — simulates a scheduled task in a channel session
+    getInboundDb()
+      .prepare(
+        `INSERT INTO messages_in (id, kind, timestamp, status, platform_id, channel_type, content)
+         VALUES ('t-task', 'task', datetime('now'), 'pending', 'chan-1', 'discord', ?)`,
+      )
+      .run(JSON.stringify({ prompt: 'daily check' }));
+
+    const provider = new MockProvider({}, () => '<message to="discord-test">done</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(out[0].platform_id).toBe('chan-1');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('should inject destination reminder after a compacted event', async () => {
+    // Two destinations — required for the reminder to fire (single-destination
+    // groups have a fallback path that works without <message to="…"> wrapping).
+    getInboundDb()
+      .prepare(
+        `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+         VALUES ('discord-second', 'Discord Second', 'channel', 'discord', 'chan-2', NULL)`,
+      )
+      .run();
+
+    insertMessage('m1', { sender: 'Alice', text: 'First message' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new CompactingProvider();
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 2500);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2500);
+    controller.abort();
+
+    expect(provider.pushes.length).toBeGreaterThanOrEqual(1);
+    const reminder = provider.pushes.find((p) => p.includes('Context was just compacted'));
+    expect(reminder).toBeDefined();
+    expect(reminder).toContain('2 destinations');
+    expect(reminder).toContain('discord-test');
+    expect(reminder).toContain('discord-second');
+    expect(reminder).toContain('<message to="name">');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('should NOT inject destination reminder with a single destination', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'First message' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new CompactingProvider();
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 2500);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2500);
+    controller.abort();
+
+    // Only the original prompt push (if any) — no reminder, since beforeEach
+    // seeds exactly one destination.
+    const reminders = provider.pushes.filter((p) => p.includes('Context was just compacted'));
+    expect(reminders).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
 });
 
+/**
+ * Provider that emits a single compacted event mid-stream, then returns a
+ * result. Captures every push() call so tests can assert on the injected
+ * reminder content.
+ */
+class CompactingProvider {
+  readonly supportsNativeSlashCommands = false;
+  readonly pushes: string[] = [];
+
+  isSessionInvalid(): boolean {
+    return false;
+  }
+
+  query(_input: { prompt: string; cwd: string }) {
+    const pushes = this.pushes;
+    let ended = false;
+    let aborted = false;
+    let resolveWaiter: (() => void) | null = null;
+
+    async function* events() {
+      yield { type: 'activity' as const };
+      yield { type: 'init' as const, continuation: 'compaction-test-session' };
+      yield { type: 'activity' as const };
+      yield { type: 'compacted' as const, text: 'Context compacted (50,000 tokens compacted).' };
+
+      // Wait for poll-loop to push the reminder (or end / abort)
+      await new Promise<void>((resolve) => {
+        resolveWaiter = resolve;
+        // Belt-and-braces: don't hang forever if the reminder never arrives
+        setTimeout(resolve, 200);
+      });
+
+      yield { type: 'activity' as const };
+      yield { type: 'result' as const, text: '<message to="discord-test">ack</message>' };
+      while (!ended && !aborted) {
+        await new Promise<void>((resolve) => {
+          resolveWaiter = resolve;
+          setTimeout(resolve, 50);
+        });
+      }
+    }
+
+    return {
+      push(message: string) {
+        pushes.push(message);
+        resolveWaiter?.();
+      },
+      end() {
+        ended = true;
+        resolveWaiter?.();
+      },
+      abort() {
+        aborted = true;
+        resolveWaiter?.();
+      },
+      events: events(),
+    };
+  }
+}
+
 // Helper: run poll loop until aborted or timeout
 async function runPollLoopWithTimeout(provider: MockProvider, signal: AbortSignal, timeoutMs: number): Promise<void> {
   return Promise.race([
@@ -157,3 +430,142 @@ async function waitFor(condition: () => boolean, timeoutMs: number): Promise<voi
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+describe('poll loop — provider error recovery', () => {
+  it('writes error to outbound and continues loop on provider throw', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'trigger error' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new ThrowingProvider('API rate limit exceeded');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toContain('Error:');
+    expect(JSON.parse(out[0].content).text).toContain('API rate limit exceeded');
+
+    // Input message should be marked completed despite the error
+    const pending = getPendingMessages();
+    expect(pending).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
+});
+
+describe('poll loop — stale session recovery', () => {
+  it('clears continuation when provider reports session invalid', async () => {
+    // Pre-seed a continuation so the local variable in runPollLoop is set.
+    // Without this, the `if (continuation && isSessionInvalid)` check skips.
+    setContinuation('mock', 'pre-existing-session');
+
+    insertMessage('m1', { sender: 'Alice', text: 'stale session' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new InvalidSessionProvider();
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    // Error was written to outbound
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toContain('Error:');
+
+    // Continuation was cleared (isSessionInvalid returned true)
+    expect(getContinuation('mock')).toBeUndefined();
+
+    await loopPromise.catch(() => {});
+  });
+});
+
+describe('poll loop — /clear command', () => {
+  it('clears session, writes confirmation, skips query', async () => {
+    // Seed a continuation so we can verify it gets cleared
+    setContinuation('mock', 'existing-session-id');
+    expect(getContinuation('mock')).toBe('existing-session-id');
+
+    // Insert a /clear command
+    getInboundDb()
+      .prepare(
+        `INSERT INTO messages_in (id, kind, timestamp, status, platform_id, channel_type, content)
+         VALUES ('m-clear', 'chat', datetime('now'), 'pending', 'chan-1', 'discord', ?)`,
+      )
+      .run(JSON.stringify({ text: '/clear' }));
+
+    const provider = new MockProvider({}, () => '<message to="discord-test">should not run</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(JSON.parse(out[0].content).text).toBe('Session cleared.');
+
+    // Continuation was cleared
+    expect(getContinuation('mock')).toBeUndefined();
+
+    // Command message was completed
+    const pending = getPendingMessages();
+    expect(pending).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
+});
+
+/**
+ * Provider that throws on every query, simulating API failures.
+ */
+class ThrowingProvider {
+  readonly supportsNativeSlashCommands = false;
+  private errorMessage: string;
+
+  constructor(errorMessage: string) {
+    this.errorMessage = errorMessage;
+  }
+
+  isSessionInvalid(): boolean {
+    return false;
+  }
+
+  query(_input: { prompt: string; cwd: string }) {
+    const errorMessage = this.errorMessage;
+    return {
+      push() {},
+      end() {},
+      abort() {},
+      events: (async function* () {
+        throw new Error(errorMessage);
+      })(),
+    };
+  }
+}
+
+/**
+ * Provider that throws with an error that triggers isSessionInvalid.
+ * First emits an init event (setting continuation), then throws.
+ */
+class InvalidSessionProvider {
+  readonly supportsNativeSlashCommands = false;
+
+  isSessionInvalid(): boolean {
+    return true;
+  }
+
+  query(_input: { prompt: string; cwd: string }) {
+    return {
+      push() {},
+      end() {},
+      abort() {},
+      events: (async function* () {
+        yield { type: 'init' as const, continuation: 'doomed-session' };
+        throw new Error('session not found');
+      })(),
+    };
+  }
+}

container/agent-runner/src/mcp-tools/cli.instructions.md

@@ -0,0 +1,78 @@
+## Admin CLI (`ncl`)
+
+The `ncl` command is available at `/usr/local/bin/ncl`. It lets you query and modify NanoClaw's central configuration — agent groups, messaging groups, wirings, users, roles, and more.
+
+### Usage
+
+```
+ncl <resource> <verb> [<id>] [--flags]
+ncl <resource> help
+ncl help
+```
+
+### Resources
+
+| Resource | Verbs | What it is |
+|----------|-------|------------|
+| groups | list, get, create, update, delete | Agent groups (workspace, personality, container config) |
+| messaging-groups | list, get, create, update, delete | A single chat/channel on one platform |
+| wirings | list, get, create, update, delete | Links a messaging group to an agent group (session mode, triggers) |
+| users | list, get, create, update | Platform identities (`<channel>:<handle>`) |
+| roles | list, grant, revoke | Owner / admin privileges (global or scoped to an agent group) |
+| 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) |
+| 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) |
+
+### When to use
+
+- **Looking up your own config** — `ncl groups get <your-group-id>` to see your agent group settings.
+- **Finding who you're wired to** — `ncl wirings list` to see which messaging groups route to which agent groups.
+- **Checking user roles** — `ncl roles list` to see who is an owner/admin.
+- **Answering questions about the system** — when the user asks about groups, channels, users, or configuration, query `ncl` rather than guessing.
+
+### Access rules
+
+Read commands (list, get) are open. Write commands (create, update, delete, grant, revoke, add, remove) require admin approval — the request is held until an admin approves it.
+
+### Approval flow
+
+Write commands (create, update, delete, grant, revoke, add, remove) require admin approval. Here's what happens:
+
+1. You run the command (e.g. `ncl groups create --name "Research" --folder research`).
+2. The command returns immediately with an `approval-pending` response — it has **not** been executed yet.
+3. An admin or owner gets a notification (on the same channel when possible) showing exactly what you requested, with approve/reject options.
+4. Once the admin responds:
+   - **Approved:** the command executes and the result is delivered back to you as a system message in this conversation.
+   - **Rejected:** you get a system message saying the request was rejected.
+
+You don't need to poll or retry — the result arrives automatically.
+
+### Examples
+
+```bash
+# Read commands (no approval needed)
+ncl groups list
+ncl groups get abc123
+ncl wirings list --messaging-group-id mg_xyz
+ncl roles list
+ncl wirings help
+
+# Write commands (approval required)
+ncl groups create --name "Research" --folder research
+ncl groups update abc123 --name "Research v2"
+ncl roles grant --user telegram:jane --role admin
+ncl roles grant --user discord:bob --role admin --group abc123
+ncl members add --user-id telegram:jane --agent-group-id abc123
+ncl destinations add --agent-group-id abc123 --messaging-group-id mg_xyz
+```
+
+### Tips
+
+- Use `ncl <resource> help` to see all available fields, types, enums, and which fields are required or updatable.
+- Flags use `--hyphen-case` (e.g. `--agent-group-id`), mapped to `underscore_case` DB columns automatically.
+- `list` supports filtering by any non-auto column (e.g. `ncl wirings list --messaging-group-id mg_xyz`). Default limit is 200 rows; override with `--limit N`.
+- For composite-key resources (roles, members, destinations), use the custom verbs (grant/revoke, add/remove) instead of create/delete.
+- Write commands return `approval-pending` immediately — don't treat this as an error. Wait for the system message with the result.

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

@@ -0,0 +1,50 @@
+/**
+ * Tests for the core MCP tools' interaction with the per-batch routing
+ * context. The agent-runner sets a current `inReplyTo` at the top of each
+ * 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.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+
+import { initTestSessionDb, closeSessionDb, getInboundDb } from '../db/connection.js';
+import { getUndeliveredMessages } from '../db/messages-out.js';
+import { setCurrentInReplyTo, clearCurrentInReplyTo } from '../current-batch.js';
+import { sendMessage } from './core.js';
+
+beforeEach(() => {
+  initTestSessionDb();
+  // Seed a peer agent destination
+  getInboundDb()
+    .prepare(
+      `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+       VALUES ('peer', 'Peer', 'agent', NULL, NULL, 'ag-peer')`,
+    )
+    .run();
+});
+
+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');
+
+    await sendMessage.handler({ to: 'peer', text: 'hello' });
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    expect(out[0].in_reply_to).toBe('inbound-msg-1');
+  });
+
+  it('writes null when no batch is active', async () => {
+    // No setCurrentInReplyTo before this call — 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();
+  });
+});

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

@@ -9,6 +9,7 @@
 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 { getSessionRouting } from '../db/session-routing.js';
@@ -50,9 +51,7 @@ function destinationList(): string {
  */
 function resolveRouting(
   to: string | undefined,
-):
-  | { channel_type: string; platform_id: string; thread_id: string | null; resolvedName: string }
-  | { error: string } {
+): { channel_type: string; platform_id: string; thread_id: string | null; resolvedName: string } | { error: string } {
   if (!to) {
     // Default: reply to whatever thread/channel this session is bound to.
     const session = getSessionRouting();
@@ -82,9 +81,7 @@ function resolveRouting(
     // preserve the thread_id so replies land in the correct thread.
     const session = getSessionRouting();
     const threadId =
-      session.channel_type === dest.channelType && session.platform_id === dest.platformId
-        ? session.thread_id
-        : null;
+      session.channel_type === dest.channelType && session.platform_id === dest.platformId ? session.thread_id : null;
     return {
       channel_type: dest.channelType!,
       platform_id: dest.platformId!,
@@ -98,12 +95,14 @@ function resolveRouting(
 export const sendMessage: McpToolDefinition = {
   tool: {
     name: 'send_message',
-    description:
-      'Send a message to a named destination. If you have only one destination, you can omit `to`.',
+    description: 'Send a message to a named destination. If you have only one destination, you can omit `to`.',
     inputSchema: {
       type: 'object' as const,
       properties: {
-        to: { type: 'string', description: 'Destination name (e.g., "family", "worker-1"). Optional if you have only one destination.' },
+        to: {
+          type: 'string',
+          description: 'Destination name (e.g., "family", "worker-1"). Optional if you have only one destination.',
+        },
         text: { type: 'string', description: 'Message content' },
       },
       required: ['text'],
@@ -119,6 +118,7 @@ export const sendMessage: McpToolDefinition = {
     const id = generateId();
     const seq = writeMessageOut({
       id,
+      in_reply_to: getCurrentInReplyTo(),
       kind: 'chat',
       platform_id: routing.platform_id,
       channel_type: routing.channel_type,
@@ -165,6 +165,7 @@ export const sendFile: McpToolDefinition = {
 
     writeMessageOut({
       id,
+      in_reply_to: getCurrentInReplyTo(),
       kind: 'chat',
       platform_id: routing.platform_id,
       channel_type: routing.channel_type,

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

@@ -149,6 +149,76 @@ describe('routing', () => {
   });
 });
 
+describe('origin metadata (from= attribute)', () => {
+  function seedDestination(name: string, channelType: string, platformId: string): void {
+    getInboundDb()
+      .prepare(
+        `INSERT INTO destinations (name, display_name, type, channel_type, platform_id, agent_group_id)
+         VALUES (?, ?, 'channel', ?, ?, NULL)`,
+      )
+      .run(name, name, channelType, platformId);
+  }
+
+  function insertWithRouting(id: string, kind: string, content: object, channelType: string | null, platformId: string | null): void {
+    getInboundDb()
+      .prepare(
+        `INSERT INTO messages_in (id, kind, timestamp, status, platform_id, channel_type, content)
+         VALUES (?, ?, datetime('now'), 'pending', ?, ?, ?)`,
+      )
+      .run(id, kind, platformId, channelType, JSON.stringify(content));
+  }
+
+  it('chat message includes from= when destination matches', () => {
+    seedDestination('discord-main', 'discord', 'chan-1');
+    insertWithRouting('m1', 'chat', { sender: 'Alice', text: 'hi' }, 'discord', 'chan-1');
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).toContain('from="discord-main"');
+  });
+
+  it('chat message falls back to raw routing when no destination matches', () => {
+    insertWithRouting('m1', 'chat', { sender: 'Alice', text: 'hi' }, 'telegram', 'chat-999');
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).toContain('from="unknown:telegram:chat-999"');
+  });
+
+  it('chat message omits from= when routing is null', () => {
+    insertMessage('m1', 'chat', { sender: 'Alice', text: 'hi' });
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).not.toContain('from=');
+  });
+
+  it('task message includes from= when destination matches', () => {
+    seedDestination('slack-ops', 'slack', 'C-OPS');
+    insertWithRouting('t1', 'task', { prompt: 'check status' }, 'slack', 'C-OPS');
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).toContain('<task');
+    expect(prompt).toContain('from="slack-ops"');
+  });
+
+  it('task message omits from= when routing is null', () => {
+    insertMessage('t1', 'task', { prompt: 'check status' });
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).toContain('<task');
+    expect(prompt).not.toContain('from=');
+  });
+
+  it('webhook message includes from= when destination matches', () => {
+    seedDestination('github-ch', 'github', 'repo-1');
+    insertWithRouting('w1', 'webhook', { source: 'github', event: 'push', payload: {} }, 'github', 'repo-1');
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).toContain('<webhook');
+    expect(prompt).toContain('from="github-ch"');
+  });
+
+  it('system message includes from= when destination matches', () => {
+    seedDestination('discord-main', 'discord', 'chan-1');
+    insertWithRouting('s1', 'system', { action: 'test', status: 'ok', result: null }, 'discord', 'chan-1');
+    const prompt = formatMessages(getPendingMessages());
+    expect(prompt).toContain('<system_response');
+    expect(prompt).toContain('from="discord-main"');
+  });
+});
+
 describe('mock provider', () => {
   it('should produce init + result events', async () => {
     const provider = new MockProvider({}, (prompt) => `Echo: ${prompt}`);

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

@@ -1,13 +1,18 @@
-import { findByName, type DestinationEntry } from './destinations.js';
+import { findByName, getAllDestinations, type DestinationEntry } from './destinations.js';
 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,
-  migrateLegacyContinuation,
-  setContinuation,
-} from './db/session-state.js';
-import { formatMessages, extractRouting, categorizeMessage, isClearCommand, isRunnerCommand, stripInternalTags, type RoutingContext } from './formatter.js';
+  formatMessages,
+  extractRouting,
+  categorizeMessage,
+  isClearCommand,
+  isRunnerCommand,
+  stripInternalTags,
+  type RoutingContext,
+} from './formatter.js';
 import type { AgentProvider, AgentQuery, ProviderEvent } from './providers/types.js';
 
 const POLL_INTERVAL_MS = 1000;
@@ -170,6 +175,9 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
     // Process the query while concurrently polling for new messages
     const skippedSet = new Set(skipped);
     const processingIds = ids.filter((id) => !commandIds.includes(id) && !skippedSet.has(id));
+    // Publish the batch's in_reply_to so MCP tools (send_message, send_file)
+    // can stamp it on outbound rows — needed for a2a return-path routing.
+    setCurrentInReplyTo(routing.inReplyTo);
     try {
       const result = await processQuery(query, routing, processingIds, config.providerName);
       if (result.continuation && result.continuation !== continuation) {
@@ -198,6 +206,8 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
         thread_id: routing.threadId,
         content: JSON.stringify({ text: `Error: ${errMsg}` }),
       });
+    } finally {
+      clearCurrentInReplyTo();
     }
 
     // Ensure completed even if processQuery ended without a result event
@@ -366,6 +376,23 @@ async function processQuery(
         if (event.text) {
           dispatchResultText(event.text, routing);
         }
+      } else if (event.type === 'compacted') {
+        // The SDK auto-compacted the conversation. After compaction the
+        // model often drops the learned `<message to="…">` wrapping
+        // discipline (the destinations are still in the system prompt,
+        // but the behavioral pattern is summarized away). Inject a
+        // reminder back into the live query so the next turn re-anchors
+        // on the destination model. Only do this when there's >1
+        // destination — single-destination groups have a fallback that
+        // works without wrapping. See qwibitai/nanoclaw#2325.
+        const destinations = getAllDestinations();
+        if (destinations.length > 1) {
+          const names = destinations.map((d) => d.name).join(', ');
+          query.push(
+            `[system] Context was just compacted. Reminder: you have ${destinations.length} destinations (${names}). ` +
+              `Use <message to="name"> blocks to address them. Bare text goes to the scratchpad fallback only.`,
+          );
+        }
       }
     }
   } finally {
@@ -385,11 +412,16 @@ function handleEvent(event: ProviderEvent, _routing: RoutingContext): void {
       log(`Result: ${event.text ? event.text.slice(0, 200) : '(empty)'}`);
       break;
     case 'error':
-      log(`Error: ${event.message} (retryable: ${event.retryable}${event.classification ? `, ${event.classification}` : ''})`);
+      log(
+        `Error: ${event.message} (retryable: ${event.retryable}${event.classification ? `, ${event.classification}` : ''})`,
+      );
       break;
     case 'progress':
       log(`Progress: ${event.message}`);
       break;
+    case 'compacted':
+      log(`Compacted: ${event.text}`);
+      break;
   }
 }
 

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

@@ -329,7 +329,7 @@ export class ClaudeProvider implements AgentProvider {
         } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'compact_boundary') {
           const meta = (message as { compact_metadata?: { pre_tokens?: number } }).compact_metadata;
           const detail = meta?.pre_tokens ? ` (${meta.pre_tokens.toLocaleString()} tokens compacted)` : '';
-          yield { type: 'result', text: `Context compacted${detail}.` };
+          yield { type: 'compacted', text: `Context compacted${detail}.` };
         } else if (message.type === 'system' && (message as { subtype?: string }).subtype === 'task_notification') {
           const tn = message as { summary?: string };
           yield { type: 'progress', message: tn.summary || 'Task notification' };

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

@@ -79,4 +79,12 @@ export type ProviderEvent =
    * event (tool call, thinking, partial message, anything) so the
    * poll-loop's idle timer stays honest during long tool runs.
    */
-  | { type: 'activity' };
+  | { type: 'activity' }
+  /**
+   * The provider's underlying SDK auto-compacted the conversation context.
+   * The poll-loop reacts by injecting a destination reminder back into
+   * the live query so the agent doesn't drop `<message to="…">` wrapping
+   * after compaction. Distinct from `result` so it doesn't mark the turn
+   * completed or get dispatched as a chat message. See qwibitai/nanoclaw#2325.
+   */
+  | { type: 'compacted'; text: string };

container/skills/onecli-gateway/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: onecli-gateway
+description: >-
+  OneCLI Gateway: transparent HTTPS proxy that injects stored credentials
+  into outbound calls. You MUST use this skill when the user asks you to
+  read emails, check calendar, access GitHub repos, create issues, check
+  Stripe payments, or interact with ANY external service or API. Do NOT
+  use browser extensions or OAuth CLI tools. Make HTTP requests directly;
+  the gateway injects credentials automatically.
+compatibility: Requires HTTPS_PROXY set in environment (automatic when launched via `onecli run`)
+metadata:
+  author: onecli
+  version: "0.5.0"
+---
+
+# OneCLI Gateway
+
+Your outbound HTTPS traffic is transparently proxied through the OneCLI
+gateway, which injects stored credentials at the proxy boundary. You never
+see or handle credential values directly.
+
+## How to Access External Services
+
+You have direct HTTP access to external APIs. OAuth apps (Gmail, GitHub,
+Google Calendar, Google Drive, etc.) and API key services are all available
+through the gateway. Just make the request directly; the gateway injects
+credentials if the app is connected. If not, it returns an error with a
+connect URL you can present to the user.
+
+## Making Requests
+
+Call the real API URL. The gateway intercepts the request and injects
+credentials automatically.
+
+```bash
+curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=5"
+curl -s "https://api.github.com/user/repos?per_page=10"
+curl -s "https://api.stripe.com/v1/charges?limit=5"
+```
+
+Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) all
+honor the `HTTPS_PROXY` environment variable automatically. You do not need
+to set any auth headers.
+
+## Credential Stubs for MCP Servers
+
+Some MCP servers need local credential files to start. Stubs for connected
+apps are pre-written automatically. Files containing `"onecli-managed"`
+values are managed by OneCLI — do NOT modify or delete them.
+
+If an MCP server won't start due to missing credentials, create stubs
+**before** starting it. Use `"onecli-managed"` as the placeholder for all
+secret values, with file permissions `0600`. See the guide at:
+https://www.onecli.sh/docs/guides/credential-stubs/general-app
+
+## When a Request Fails
+
+If you get a 401, 403, or a gateway error (e.g., `app_not_connected`):
+
+**Step 1 — Show the user a connect link.** Use the `connect_url` from the
+error response:
+
+> To connect [service], open this link:
+> [connect_url from the error response]
+
+If there is no `connect_url` in the error, tell the user to open the
+OneCLI dashboard and connect the service there.
+
+**Step 2 — Retry after the user connects.** Let the user know you will
+retry once they have connected. When they confirm, retry the original
+request. If the retry still fails, ask if they need help with the setup.
+
+## Rules
+
+- **Never** say "I don't have access to X" without first making the HTTP
+  request through the proxy.
+- **Never** use browser extensions, gcloud, or manual auth flows. The
+  gateway handles credentials for you.
+- **Never** ask the user for API keys or tokens directly. Direct them to
+  connect the service in the OneCLI dashboard.
+- **Never** suggest the user open Gmail/Calendar/GitHub in their browser
+  when they ask you to read or interact with those services. You have API
+  access. Use it.
+- If the gateway returns a policy error (403 with a JSON body), respect
+  the block. Do not retry or circumvent it.

container/skills/onecli-gateway/instructions.md

@@ -0,0 +1,7 @@
+# Credentials & External Services
+
+Your HTTP requests go through the OneCLI proxy, which injects real credentials automatically. Just call any API directly (Gmail, GitHub, Slack, etc.) — the proxy adds auth before it reaches the service.
+
+Use any method: curl, Python, a CLI tool, whatever fits. If a tool checks for credentials locally, pass any placeholder value — the proxy replaces it with real credentials at request time.
+
+If you get a `401`/`403`/`app_not_connected`, run `/onecli-gateway` for the full error-handling flow. Never ask the user for API keys or tokens — if credentials are missing, the fix is connecting the service in OneCLI.

package.json

@@ -1,10 +1,13 @@
 {
   "name": "nanoclaw",
-  "version": "2.0.33",
+  "version": "2.0.45",
   "description": "Personal Claude assistant. Lightweight, secure, customizable.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "main": "dist/index.js",
+  "bin": {
+    "ncl": "bin/ncl"
+  },
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
@@ -16,6 +19,7 @@
     "prepare": "husky",
     "setup": "tsx setup/index.ts",
     "setup:auto": "tsx setup/auto.ts",
+    "ncl": "tsx src/cli/client.ts",
     "chat": "tsx scripts/chat.ts",
     "auth": "tsx src/whatsapp-auth.ts",
     "lint": "eslint src/",
@@ -26,7 +30,7 @@
   "dependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
-    "@onecli-sh/sdk": "^0.3.1",
+    "@onecli-sh/sdk": "^0.5.0",
     "better-sqlite3": "11.10.0",
     "chat": "^4.24.0",
     "cron-parser": "5.5.0",

pnpm-lock.yaml

@@ -15,8 +15,8 @@ importers:
         specifier: ^1.2.0
         version: 1.2.0
       '@onecli-sh/sdk':
-        specifier: ^0.3.1
-        version: 0.3.1
+        specifier: ^0.5.0
+        version: 0.5.0
       better-sqlite3:
         specifier: 11.10.0
         version: 11.10.0
@@ -303,8 +303,8 @@ packages:
       '@emnapi/core': ^1.7.1
       '@emnapi/runtime': ^1.7.1
 
-  '@onecli-sh/sdk@0.3.1':
-    resolution: {integrity: sha512-oMSa4DUCVS52vec41nFOg3XdCBTbMVEZdCFCsaUd9sRXVorCPWd3VyZq4giXsmk4g09DA/zLjsnrY7l6G94Ulg==}
+  '@onecli-sh/sdk@0.5.0':
+    resolution: {integrity: sha512-oe5Yx9o98v6N1PgzcCR7nULHHqcqKWNJIDOHGOSNX+l20mLlZpFUqfKPeFmsojBNRQMoqbvZQKUlFMp6gVuYBA==}
     engines: {node: '>=20'}
 
   '@oxc-project/types@0.124.0':
@@ -1665,7 +1665,7 @@ snapshots:
       '@tybys/wasm-util': 0.10.1
     optional: true
 
-  '@onecli-sh/sdk@0.3.1': {}
+  '@onecli-sh/sdk@0.5.0': {}
 
   '@oxc-project/types@0.124.0': {}
 

repo-tokens/badge.svg

@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="141k tokens, 71% of context window">
-  <title>141k tokens, 71% of context window</title>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="150k tokens, 75% of context window">
+  <title>150k tokens, 75% of context window</title>
   <linearGradient id="s" x2="0" y2="100%">
     <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
     <stop offset="1" stop-opacity=".1"/>
@@ -15,8 +15,8 @@
       <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
         <text aria-hidden="true" x="26" y="15" fill="#010101" fill-opacity=".3">tokens</text>
         <text x="26" y="14">tokens</text>
-        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">141k</text>
-        <text x="71" y="14">141k</text>
+        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">150k</text>
+        <text x="71" y="14">150k</text>
       </g>
     </g>
   </a>

scripts/chat.ts

@@ -1,5 +1,5 @@
 /**
- * nc — chat with your NanoClaw agent from the terminal.
+ * ncl — chat with your NanoClaw agent from the terminal.
  *
  * Usage:
  *   pnpm run chat <message...>
@@ -36,7 +36,7 @@ function main(): void {
     const e = err as NodeJS.ErrnoException;
     if (e.code === 'ENOENT' || e.code === 'ECONNREFUSED') {
       console.error(`NanoClaw daemon not reachable at ${socketPath()}.`);
-      console.error('Start the service (launchctl/systemd) before running nc.');
+      console.error('Start the service (launchctl/systemd) before running ncl.');
     } else {
       console.error('CLI socket error:', err);
     }

setup/auto.ts

@@ -39,7 +39,7 @@ import { runTelegramChannel } from './channels/telegram.js';
 import { runWhatsAppChannel } from './channels/whatsapp.js';
 import { pingCliAgent, type PingResult } from './lib/agent-ping.js';
 import { brightSelect } from './lib/bright-select.js';
-import { offerClaudeAssist } from './lib/claude-assist.js';
+import { offerClaudeOnFailure } from './lib/claude-handoff.js';
 import {
   applyToEnv,
   parseFlags,
@@ -416,7 +416,7 @@ async function main(): Promise<void> {
       } else {
         phEmit('first_chat_failed', { reason: ping });
         renderPingFailureNote(ping);
-        await offerClaudeAssist({
+        await offerClaudeOnFailure({
           stepName: 'cli-agent',
           msg:
             ping === 'socket_error'
@@ -468,7 +468,7 @@ async function main(): Promise<void> {
       } else if (channelChoice === 'imessage') {
         result = await runIMessageChannel(displayName!);
       } else if (channelChoice === 'other') {
-        await askOtherChannelName();
+        result = await askOtherChannelName();
       } else {
         p.log.info(
           brandBody(
@@ -528,7 +528,7 @@ async function main(): Promise<void> {
         service_running: res.terminal?.fields.SERVICE === 'running',
         has_credentials: res.terminal?.fields.CREDENTIALS === 'configured',
       });
-      await offerClaudeAssist({
+      await offerClaudeOnFailure({
         stepName: 'verify',
         msg: summary || 'Verification completed with unresolved issues.',
         hint: `Terminal block: ${JSON.stringify(res.terminal?.fields ?? {})}`,
@@ -740,12 +740,38 @@ async function runAuthStep(): Promise<void> {
           label: 'Paste an Anthropic API key',
           hint: 'pay-per-use via console.anthropic.com',
         },
+        {
+          value: 'skip',
+          label: "Skip — I'll connect later",
+          hint: 'not recommended — Claude helps debug setup issues',
+        },
       ],
     }),
-  ) as 'subscription' | 'oauth' | 'api';
+  ) as 'subscription' | 'oauth' | 'api' | 'skip';
   setupLog.userInput('auth_method', method);
   phEmit('auth_method_chosen', { method });
 
+  if (method === 'skip') {
+    const confirmed = ensureAnswer(
+      await p.confirm({
+        message:
+          "Skip Claude sign-in? The agent won't be able to run until you connect, and we won't be able to help debug setup errors.",
+        initialValue: false,
+      }),
+    );
+    if (!confirmed) {
+      // Loop back to the auth picker so they can choose a real method.
+      return runAuthStep();
+    }
+    setupLog.step('auth', 'skipped', 0, { REASON: 'user-skipped' });
+    p.log.warn(
+      brandBody(
+        'Claude sign-in skipped. Re-run setup or run `bash nanoclaw.sh` to finish later.',
+      ),
+    );
+    return;
+  }
+
   if (method === 'subscription') {
     await runSubscriptionAuth();
   } else {
@@ -1099,10 +1125,26 @@ async function askChannelChoice(): Promise<ChannelChoice> {
   return choice;
 }
 
-async function askOtherChannelName(): Promise<void> {
+async function askOtherChannelName(): Promise<void | typeof BACK_TO_CHANNEL_SELECTION> {
+  const action = ensureAnswer(
+    await brightSelect<'type' | 'back'>({
+      message: 'Which channel would you like to install?',
+      options: [
+        {
+          value: 'type',
+          label: 'Type the channel name',
+          hint: 'e.g. matrix, github, linear, webex',
+        },
+        { value: 'back', label: '← Back to channel selection' },
+      ],
+      initialValue: 'type',
+    }),
+  );
+  if (action === 'back') return BACK_TO_CHANNEL_SELECTION;
+
   const answer = ensureAnswer(
     await p.text({
-      message: 'Which channel would you like to install?',
+      message: 'Channel name',
       placeholder: 'e.g. matrix, github, linear, webex',
     }),
   );

setup/lib/claude-assist.ts

@@ -43,7 +43,7 @@ export interface AssistContext {
  * rather than us stuffing contents into the prompt. Keys are step names as
  * they appear in fail() calls; values are repo-relative paths.
  */
-const STEP_FILES: Record<string, string[]> = {
+export const STEP_FILES: Record<string, string[]> = {
   bootstrap: ['setup.sh', 'setup/install-node.sh', 'nanoclaw.sh'],
   environment: ['setup/environment.ts'],
   container: [
@@ -81,7 +81,7 @@ const STEP_FILES: Record<string, string[]> = {
   ],
 };
 
-const BIG_PICTURE_FILES = ['README.md', 'setup/auto.ts'];
+export const BIG_PICTURE_FILES = ['README.md', 'setup/auto.ts'];
 
 /**
  * Returns `true` if the user ran a Claude-suggested fix command; callers
@@ -150,7 +150,7 @@ function isClaudeAuthenticated(): boolean {
   }
 }
 
-async function ensureClaudeReady(projectRoot: string): Promise<boolean> {
+export async function ensureClaudeReady(projectRoot: string): Promise<boolean> {
   if (!isClaudeInstalled()) {
     const install = ensureAnswer(
       await p.confirm({

setup/lib/claude-handoff.ts

@@ -23,10 +23,19 @@
  * attempting to parse it as a real answer.
  */
 import { execSync, spawn } from 'child_process';
+import path from 'path';
 
 import * as p from '@clack/prompts';
 import k from 'kleur';
 
+import {
+  type AssistContext,
+  BIG_PICTURE_FILES,
+  ensureClaudeReady,
+  offerClaudeAssist,
+  STEP_FILES,
+} from './claude-assist.js';
+import { ensureAnswer } from './runner.js';
 import { brandBody, note } from './theme.js';
 
 export interface HandoffContext {
@@ -194,3 +203,110 @@ function buildSystemPrompt(ctx: HandoffContext): string {
 
   return lines.join('\n');
 }
+
+/**
+ * Dispatcher: checks NANOCLAW_SETUP_ASSIST_MODE and delegates to either
+ * the interactive failure handoff (default) or the non-interactive assist.
+ *
+ * Drop-in replacement for `offerClaudeAssist` at failure call sites.
+ */
+export async function offerClaudeOnFailure(
+  ctx: AssistContext,
+  projectRoot: string = process.cwd(),
+): Promise<boolean> {
+  if (process.env.NANOCLAW_SETUP_ASSIST_MODE === 'true' || process.env.NANOCLAW_SETUP_ASSIST_MODE === '1') {
+    return offerClaudeAssist(ctx, projectRoot);
+  }
+  return offerFailureHandoff(ctx, projectRoot);
+}
+
+/**
+ * Interactive Claude handoff for setup failures. Same role as
+ * `offerClaudeAssist` but spawns an interactive session instead of
+ * parsing a structured REASON/COMMAND response.
+ *
+ * Returns `true` if Claude was launched (the user may have fixed
+ * things during the session), `false` if skipped/declined/unavailable.
+ */
+async function offerFailureHandoff(
+  ctx: AssistContext,
+  projectRoot: string,
+): Promise<boolean> {
+  if (process.env.NANOCLAW_SKIP_CLAUDE_ASSIST === '1') return false;
+  if (!(await ensureClaudeReady(projectRoot))) return false;
+
+  const want = ensureAnswer(
+    await p.confirm({
+      message: 'Want to debug this with Claude?',
+      initialValue: true,
+    }),
+  );
+  if (!want) return false;
+
+  const systemPrompt = buildFailureSystemPrompt(ctx, projectRoot);
+
+  note(
+    [
+      "Launching Claude to help debug this failure.",
+      "It has the context of what went wrong.",
+      "",
+      k.dim("Type /exit (or press Ctrl-D) when you're ready to come back to setup."),
+    ].join('\n'),
+    'Handing off to Claude',
+  );
+
+  return new Promise<boolean>((resolve) => {
+    const child = spawn(
+      'claude',
+      [
+        '--append-system-prompt',
+        systemPrompt,
+        '--permission-mode',
+        'acceptEdits',
+      ],
+      { stdio: 'inherit' },
+    );
+    child.on('close', () => {
+      p.log.success(brandBody("Back from Claude. Let's continue."));
+      resolve(true);
+    });
+    child.on('error', () => {
+      p.log.error("Couldn't launch Claude. Continuing without handoff.");
+      resolve(false);
+    });
+  });
+}
+
+function buildFailureSystemPrompt(ctx: AssistContext, projectRoot: string): string {
+  const stepRefs = STEP_FILES[ctx.stepName] ?? [];
+  const references = [
+    ...BIG_PICTURE_FILES,
+    ...stepRefs,
+    'logs/setup.log',
+    ctx.rawLogPath
+      ? path.relative(projectRoot, ctx.rawLogPath)
+      : 'logs/setup-steps/',
+  ].filter((v, i, a) => a.indexOf(v) === i);
+
+  const lines: string[] = [
+    "The user is running NanoClaw's interactive setup flow and hit a failure.",
+    '',
+    `Failed step: ${ctx.stepName}`,
+    `Error: ${ctx.msg}`,
+  ];
+
+  if (ctx.hint) lines.push(`Hint: ${ctx.hint}`);
+
+  lines.push(
+    '',
+    'Your job: help them diagnose and fix this issue. Read the referenced files',
+    'and logs to understand what went wrong, then help them fix it. You can read',
+    'files, run commands, check logs, and explain what happened. Be concise.',
+    "When they're ready to resume setup, tell them to type /exit.",
+    '',
+    'Relevant files (read as needed with the Read tool):',
+  );
+  for (const f of references) lines.push(`  - ${f}`);
+
+  return lines.join('\n');
+}

setup/lib/runner.ts

@@ -18,7 +18,7 @@ import * as p from '@clack/prompts';
 import k from 'kleur';
 
 import * as setupLog from '../logs.js';
-import { offerClaudeAssist } from './claude-assist.js';
+import { offerClaudeOnFailure } from './claude-handoff.js';
 import { emit as phEmit } from './diagnostics.js';
 import { brandBody, fitToWidth, fmtDuration } from './theme.js';
 
@@ -367,7 +367,7 @@ export async function fail(
   if (hint) p.log.message(k.dim(hint));
   p.log.message(k.dim('Logs: logs/setup.log · Raw: logs/setup-steps/'));
 
-  const ranFix = await offerClaudeAssist({ stepName, msg, hint, rawLogPath });
+  const ranFix = await offerClaudeOnFailure({ stepName, msg, hint, rawLogPath });
 
   // If the user just ran a Claude-suggested fix, offer to resume the flow
   // at the step that failed instead of aborting. We re-exec via spawnSync

setup/lib/setup-config.ts

@@ -123,6 +123,15 @@ export const CONFIG: Entry[] = [
     surface: 'flag',
     type: 'string',
   },
+  {
+    key: 'assistMode',
+    envVar: 'NANOCLAW_SETUP_ASSIST_MODE',
+    label: 'Assist mode',
+    help: 'Use non-interactive Claude assist on failure instead of interactive handoff.',
+    surface: 'flag',
+    type: 'boolean',
+    default: false,
+  },
 ];
 
 // ─── name derivation ───────────────────────────────────────────────────

setup/lib/windowed-runner.ts

@@ -18,7 +18,7 @@
 import * as p from '@clack/prompts';
 import k from 'kleur';
 
-import { offerClaudeAssist } from './claude-assist.js';
+import { offerClaudeOnFailure } from './claude-handoff.js';
 import { emit as phEmit } from './diagnostics.js';
 import type { StepResult, SpinnerLabels } from './runner.js';
 import { dumpTranscriptOnFailure, spawnStep, writeStepEntry } from './runner.js';
@@ -212,7 +212,7 @@ async function handleStall(
     // offerClaudeAssist runs its own spinner and may propose a fix command.
     // We don't attempt to restart the stalled build from here — if Claude
     // proposes a command the user accepts, they can retry setup afterwards.
-    await offerClaudeAssist({
+    await offerClaudeOnFailure({
       stepName,
       msg: `The ${stepName} step has produced no output for 60 seconds.`,
       hint: 'It may be hung on a slow network pull or a failing Dockerfile step.',

setup/service.ts

@@ -82,6 +82,41 @@ export async function run(_args: string[]): Promise<void> {
     });
     process.exit(1);
   }
+
+  installCliSymlink(projectRoot, homeDir);
+}
+
+/**
+ * Symlink bin/ncl into ~/.local/bin so `ncl` is available from anywhere.
+ * Idempotent — overwrites an existing symlink but won't clobber a real file.
+ */
+function installCliSymlink(projectRoot: string, homeDir: string): void {
+  const source = path.join(projectRoot, 'bin', 'ncl');
+  const targetDir = path.join(homeDir, '.local', 'bin');
+  const target = path.join(targetDir, 'ncl');
+
+  try {
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    // Remove existing symlink (but not a real file)
+    try {
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) {
+        fs.unlinkSync(target);
+      } else {
+        log.warn('~/.local/bin/ncl exists and is not a symlink — skipping', { target });
+        return;
+      }
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    fs.symlinkSync(source, target);
+    log.info('Installed ncl CLI symlink', { target, source });
+  } catch (err) {
+    log.warn('Could not install ncl CLI symlink (non-fatal)', { err });
+  }
 }
 
 function setupLaunchd(

src/channels/chat-sdk-bridge.ts

@@ -307,8 +307,14 @@ export function createChatSdkBridge(config: ChatSdkBridgeConfig): ChannelAdapter
         // Start local HTTP server to receive forwarded Gateway events (including interactions)
         const webhookUrl = await startLocalWebhookServer(gatewayAdapter, setupConfig, config.botToken);
 
+        // Exponential backoff capped at 1h. Without this, an unrecoverable
+        // failure (e.g., TokenInvalid) restarts ~10×/sec and Discord's
+        // Cloudflare layer issues a multi-hour IP block. A run that lasts
+        // longer than 5 minutes counts as healthy and resets the counter.
+        let consecutiveFailures = 0;
         const startGateway = () => {
           if (gatewayAbort?.signal.aborted) return;
+          const startedAt = Date.now();
           // Capture the long-running listener promise via waitUntil
           let listenerPromise: Promise<unknown> | undefined;
           gatewayAdapter.startGatewayListener!(
@@ -323,21 +329,30 @@ export function createChatSdkBridge(config: ChatSdkBridgeConfig): ChannelAdapter
           ).then(() => {
             // startGatewayListener resolves immediately with a Response;
             // the actual work is in the listenerPromise passed to waitUntil
-            if (listenerPromise) {
-              listenerPromise
-                .then(() => {
-                  if (!gatewayAbort?.signal.aborted) {
-                    log.info('Gateway listener expired, restarting', { adapter: adapter.name });
-                    startGateway();
-                  }
-                })
-                .catch((err) => {
-                  if (!gatewayAbort?.signal.aborted) {
-                    log.error('Gateway listener error, restarting in 5s', { adapter: adapter.name, err });
-                    setTimeout(startGateway, 5000);
-                  }
+            if (!listenerPromise) return;
+            const reschedule = (err?: unknown) => {
+              if (gatewayAbort?.signal.aborted) return;
+              const ranForMs = Date.now() - startedAt;
+              if (ranForMs > 5 * 60 * 1000) consecutiveFailures = 0;
+              else consecutiveFailures++;
+              const delayMs = Math.min(60 * 60 * 1000, 2 ** consecutiveFailures * 1000);
+              if (err) {
+                log.error('Gateway listener error, retrying', {
+                  adapter: adapter.name,
+                  err,
+                  consecutiveFailures,
+                  delayMs,
                 });
-            }
+              } else {
+                log.info('Gateway listener expired, restarting', {
+                  adapter: adapter.name,
+                  consecutiveFailures,
+                  delayMs,
+                });
+              }
+              setTimeout(startGateway, delayMs);
+            };
+            listenerPromise.then(() => reschedule()).catch(reschedule);
           });
         };
         startGateway();

src/cli/client.ts

@@ -0,0 +1,135 @@
+/**
+ * `ncl` binary entry point.
+ *
+ * Parses argv, builds a request frame, sends it via the picked transport,
+ * formats the response, exits non-zero on error.
+ *
+ * Usage:
+ *   ncl <resource> <verb> [target] [--key value ...] [--json]
+ *
+ * Examples:
+ *   ncl groups list
+ *   ncl groups get abc123
+ *   ncl groups create --name foo --folder bar
+ *   ncl groups update abc123 --name baz
+ *   ncl help
+ *   ncl groups help
+ */
+import { randomUUID } from 'crypto';
+
+import { formatResponse } from './format.js';
+import type { RequestFrame } from './frame.js';
+import { SocketTransport } from './socket-client.js';
+import type { Transport } from './transport.js';
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const { command, args, json } = parseArgv(argv);
+  const req: RequestFrame = { id: randomUUID(), command, args };
+  const transport: Transport = pickTransport();
+
+  let res;
+  try {
+    res = await transport.sendFrame(req);
+  } catch (e) {
+    process.stderr.write(formatTransportError(e));
+    process.exit(2);
+  }
+
+  process.stdout.write(formatResponse(res, json ? 'json' : 'human'));
+  process.exit(res.ok ? 0 : 1);
+}
+
+function pickTransport(): Transport {
+  return new SocketTransport();
+}
+
+function parseArgv(argv: string[]): {
+  command: string;
+  args: Record<string, unknown>;
+  json: boolean;
+} {
+  const positional: string[] = [];
+  const args: Record<string, unknown> = {};
+  let json = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i++;
+      }
+      continue;
+    }
+    positional.push(a);
+  }
+
+  if (positional.length === 0) {
+    process.stderr.write('ncl: missing command\n');
+    printUsage();
+    process.exit(2);
+  }
+
+  // Single word: `ncl help`
+  // Two words: `ncl groups list`, `ncl groups help`
+  // Three words: `ncl groups get abc123`
+  let command: string;
+  if (positional.length === 1) {
+    command = positional[0];
+  } else {
+    command = `${positional[0]}-${positional[1]}`;
+  }
+
+  // Third positional is the target ID
+  if (positional.length >= 3) {
+    args.id = positional[2];
+  }
+
+  return { command, args, json };
+}
+
+function printUsage(): void {
+  process.stdout.write(
+    [
+      'Usage: ncl <resource> <verb> [target] [--key value ...] [--json]',
+      '',
+      'Run `ncl help` to list available resources and commands.',
+      '',
+    ].join('\n'),
+  );
+}
+
+function formatTransportError(e: unknown): string {
+  const msg = e instanceof Error ? e.message : String(e);
+  if (msg.includes('ENOENT') || msg.includes('ECONNREFUSED')) {
+    return [
+      `ncl: cannot reach NanoClaw host (${msg}).`,
+      `Is the host running? Start it with: pnpm run dev`,
+      `Or, if installed as a service:`,
+      `  macOS:  launchctl kickstart -k gui/$(id -u)/com.nanoclaw`,
+      `  Linux:  systemctl --user restart nanoclaw`,
+      ``,
+    ].join('\n');
+  }
+  return `ncl: transport error: ${msg}\n`;
+}
+
+main().catch((err) => {
+  process.stderr.write(`ncl: unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(2);
+});

src/cli/commands/help.ts

@@ -0,0 +1,106 @@
+/**
+ * Built-in help command. Introspects the resource and command registries.
+ *
+ *   ncl help               — list all resources and commands
+ *   ncl groups help         — show group resource details (verbs, columns, enums)
+ */
+import { getResource, getResources } from '../crud.js';
+import { listCommands, register } from '../registry.js';
+
+register({
+  name: 'help',
+  description: 'List available resources and commands.',
+  access: 'open',
+  parseArgs: () => ({}),
+  handler: async () => {
+    const resources = getResources();
+    const commands = listCommands().filter((c) => c.access !== 'hidden' && !c.resource);
+
+    const lines: string[] = [];
+    if (resources.length > 0) {
+      lines.push('Resources:');
+      for (const r of resources) {
+        const ops: string[] = [];
+        if (r.operations.list) ops.push('list');
+        if (r.operations.get) ops.push('get');
+        if (r.operations.create) ops.push('create');
+        if (r.operations.update) ops.push('update');
+        if (r.operations.delete) ops.push('delete');
+        if (r.customOperations) ops.push(...Object.keys(r.customOperations));
+        lines.push(`  ${r.plural.padEnd(20)} ${r.description}`);
+        lines.push(`  ${''.padEnd(20)} verbs: ${ops.join(', ')}`);
+      }
+    }
+
+    if (commands.length > 0) {
+      if (lines.length > 0) lines.push('');
+      lines.push('Commands:');
+      for (const c of commands) {
+        lines.push(`  ${c.name.padEnd(20)} ${c.description}`);
+      }
+    }
+
+    lines.push('');
+    lines.push('Run `ncl <resource> help` for detailed field information.');
+    return lines.join('\n');
+  },
+});
+
+// Register per-resource help commands. These are registered dynamically
+// after the resources barrel has been imported.
+// We use a lazy approach: register a catch-all pattern isn't possible with
+// the flat registry, so we register `<plural>-help` for each resource
+// in a post-import hook.
+export function registerResourceHelpCommands(): void {
+  for (const res of getResources()) {
+    // Skip if already registered (e.g. from a previous call)
+    try {
+      register({
+        name: `${res.plural}-help`,
+        description: `Show ${res.name} resource details.`,
+        access: 'open',
+        resource: res.plural,
+        parseArgs: () => ({}),
+        handler: async () => {
+          const lines: string[] = [];
+          lines.push(`${res.plural}: ${res.description}`);
+          lines.push('');
+
+          // Verbs
+          const verbs: string[] = [];
+          if (res.operations.list) verbs.push(`list [open]`);
+          if (res.operations.get) verbs.push(`get <id> [open]`);
+          if (res.operations.create) verbs.push(`create [approval]`);
+          if (res.operations.update) verbs.push(`update <id> [approval]`);
+          if (res.operations.delete) verbs.push(`delete <id> [approval]`);
+          if (res.customOperations) {
+            for (const [verb, op] of Object.entries(res.customOperations)) {
+              verbs.push(`${verb} [${op.access}] — ${op.description}`);
+            }
+          }
+          lines.push('Verbs:');
+          for (const v of verbs) lines.push(`  ${v}`);
+          lines.push('');
+
+          // Columns
+          lines.push('Fields:');
+          for (const col of res.columns) {
+            const tags: string[] = [];
+            if (col.generated) tags.push('auto');
+            if (col.required) tags.push('required');
+            if (col.updatable) tags.push('updatable');
+            if (col.default !== undefined && col.default !== null) tags.push(`default: ${col.default}`);
+            if (col.enum) tags.push(`values: ${col.enum.join(' | ')}`);
+
+            const flag = `--${col.name.replace(/_/g, '-')}`;
+            const tagStr = tags.length > 0 ? ` (${tags.join(', ')})` : '';
+            lines.push(`  ${flag.padEnd(28)} ${col.description}${tagStr}`);
+          }
+          return lines.join('\n');
+        },
+      });
+    } catch {
+      // Already registered — skip
+    }
+  }
+}

src/cli/commands/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Command barrel — populates the registry before the CLI server starts.
+ *
+ * Resource definitions register their CRUD commands on import.
+ * Help commands are registered after resources are loaded.
+ */
+import '../resources/index.js';
+import { registerResourceHelpCommands } from './help.js';
+
+registerResourceHelpCommands();

src/cli/crud.ts

@@ -0,0 +1,291 @@
+/**
+ * CRUD registration helper.
+ *
+ * Takes a declarative resource definition (table, columns, access levels)
+ * and auto-registers list/get/create/update/delete commands in the CLI
+ * registry. Column metadata doubles as documentation — `ncl <resource> help`
+ * is generated from the same definitions.
+ */
+import { randomUUID } from 'crypto';
+
+import { getDb } from '../db/connection.js';
+import { register } from './registry.js';
+import type { CallerContext } from './frame.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Access = 'open' | 'approval' | 'hidden';
+
+export interface ColumnDef {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'json';
+  description: string;
+  /** Auto-set on create — not user-provided. */
+  generated?: boolean;
+  /** Must be provided on create (ignored if generated). */
+  required?: boolean;
+  /** Can be changed via update. */
+  updatable?: boolean;
+  /** Default value on create when not provided. */
+  default?: unknown;
+  /** Allowed values (shown in help). */
+  enum?: string[];
+}
+
+export interface CustomOperation {
+  access: Access;
+  description: string;
+  args?: ColumnDef[];
+  handler: (args: Record<string, unknown>, ctx: CallerContext) => Promise<unknown>;
+}
+
+export interface ResourceDef {
+  /** Singular name: 'group'. */
+  name: string;
+  /** Plural name: 'groups'. Used in command names. */
+  plural: string;
+  /** DB table name. */
+  table: string;
+  /** One-line description shown in help. */
+  description: string;
+  /** Primary key column name. */
+  idColumn: string;
+  columns: ColumnDef[];
+  /** Which standard CRUD operations are enabled. */
+  operations: {
+    list?: Access;
+    get?: Access;
+    create?: Access;
+    update?: Access;
+    delete?: Access;
+  };
+  /** Non-standard verbs (grant, revoke, add, remove, restart, etc.). */
+  customOperations?: Record<string, CustomOperation>;
+}
+
+// ---------------------------------------------------------------------------
+// Resource registry (for help introspection)
+// ---------------------------------------------------------------------------
+
+const resources = new Map<string, ResourceDef>();
+
+export function getResources(): ResourceDef[] {
+  return [...resources.values()].sort((a, b) => a.plural.localeCompare(b.plural));
+}
+
+export function getResource(plural: string): ResourceDef | undefined {
+  return resources.get(plural);
+}
+
+// ---------------------------------------------------------------------------
+// Generic SQL handlers
+// ---------------------------------------------------------------------------
+
+function visibleColumns(def: ResourceDef): string[] {
+  return def.columns.map((c) => c.name);
+}
+
+function genericList(def: ResourceDef) {
+  const cols = visibleColumns(def).join(', ');
+  const filterableNames = new Set(def.columns.filter((c) => !c.generated).map((c) => c.name));
+  return async (args: Record<string, unknown>) => {
+    const limit = args.limit !== undefined ? Math.max(1, Number(args.limit)) : 200;
+    const filters: string[] = [];
+    const params: unknown[] = [];
+    for (const [k, v] of Object.entries(args)) {
+      if (k === 'id' || k === 'limit') continue;
+      if (filterableNames.has(k)) {
+        filters.push(`${k} = ?`);
+        params.push(v);
+      }
+    }
+    const where = filters.length > 0 ? ` WHERE ${filters.join(' AND ')}` : '';
+    params.push(limit);
+    return getDb()
+      .prepare(`SELECT ${cols} FROM ${def.table}${where} LIMIT ?`)
+      .all(...params);
+  };
+}
+
+function genericGet(def: ResourceDef) {
+  const cols = visibleColumns(def).join(', ');
+  return async (args: Record<string, unknown>) => {
+    const id = args.id as string;
+    if (!id) throw new Error(`${def.name} id is required`);
+    const row = getDb().prepare(`SELECT ${cols} FROM ${def.table} WHERE ${def.idColumn} = ?`).get(id);
+    if (!row) throw new Error(`${def.name} not found: ${id}`);
+    return row;
+  };
+}
+
+function genericCreate(def: ResourceDef) {
+  return async (args: Record<string, unknown>) => {
+    const values: Record<string, unknown> = {};
+
+    for (const col of def.columns) {
+      if (col.generated) {
+        if (col.name === def.idColumn) {
+          values[col.name] = randomUUID();
+        } else if (col.name.endsWith('_at')) {
+          values[col.name] = new Date().toISOString();
+        }
+        continue;
+      }
+
+      const v = args[col.name];
+      if (v !== undefined) {
+        if (col.enum && !col.enum.includes(String(v))) {
+          throw new Error(`${col.name} must be one of: ${col.enum.join(', ')}`);
+        }
+        values[col.name] = col.type === 'number' ? Number(v) : v;
+      } else if (col.required) {
+        throw new Error(`--${col.name.replace(/_/g, '-')} is required`);
+      } else if (col.default !== undefined) {
+        values[col.name] = col.default;
+      }
+    }
+
+    const colNames = Object.keys(values);
+    const placeholders = colNames.map((c) => `@${c}`);
+    getDb()
+      .prepare(`INSERT INTO ${def.table} (${colNames.join(', ')}) VALUES (${placeholders.join(', ')})`)
+      .run(values);
+    return values;
+  };
+}
+
+function genericUpdate(def: ResourceDef) {
+  const updatableCols = def.columns.filter((c) => c.updatable);
+  return async (args: Record<string, unknown>) => {
+    const id = args.id as string;
+    if (!id) throw new Error(`${def.name} id is required`);
+
+    const updates: Record<string, unknown> = {};
+    for (const col of updatableCols) {
+      const v = args[col.name];
+      if (v !== undefined) {
+        if (col.enum && !col.enum.includes(String(v))) {
+          throw new Error(`${col.name} must be one of: ${col.enum.join(', ')}`);
+        }
+        updates[col.name] = col.type === 'number' ? Number(v) : v;
+      }
+    }
+    if (Object.keys(updates).length === 0) {
+      throw new Error(
+        `nothing to update — provide at least one of: ${updatableCols.map((c) => '--' + c.name.replace(/_/g, '-')).join(', ')}`,
+      );
+    }
+
+    const setClause = Object.keys(updates)
+      .map((k) => `${k} = @${k}`)
+      .join(', ');
+    const result = getDb()
+      .prepare(`UPDATE ${def.table} SET ${setClause} WHERE ${def.idColumn} = @_id`)
+      .run({ ...updates, _id: id });
+    if (result.changes === 0) throw new Error(`${def.name} not found: ${id}`);
+
+    const cols = visibleColumns(def).join(', ');
+    return getDb().prepare(`SELECT ${cols} FROM ${def.table} WHERE ${def.idColumn} = ?`).get(id);
+  };
+}
+
+function genericDelete(def: ResourceDef) {
+  return async (args: Record<string, unknown>) => {
+    const id = args.id as string;
+    if (!id) throw new Error(`${def.name} id is required`);
+    const result = getDb().prepare(`DELETE FROM ${def.table} WHERE ${def.idColumn} = ?`).run(id);
+    if (result.changes === 0) throw new Error(`${def.name} not found: ${id}`);
+    return { deleted: id };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// parseArgs helper: normalizes --hyphen-keys to underscore_keys
+// ---------------------------------------------------------------------------
+
+function normalizeArgs(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;
+}
+
+// ---------------------------------------------------------------------------
+// registerResource
+// ---------------------------------------------------------------------------
+
+export function registerResource(def: ResourceDef): void {
+  resources.set(def.plural, def);
+
+  if (def.operations.list) {
+    register({
+      name: `${def.plural}-list`,
+      description: `List all ${def.plural}.`,
+      access: def.operations.list,
+      resource: def.plural,
+      parseArgs: (raw) => normalizeArgs(raw),
+      handler: genericList(def),
+    });
+  }
+
+  if (def.operations.get) {
+    register({
+      name: `${def.plural}-get`,
+      description: `Get a ${def.name} by ID.`,
+      access: def.operations.get,
+      resource: def.plural,
+      parseArgs: (raw) => normalizeArgs(raw),
+      handler: genericGet(def),
+    });
+  }
+
+  if (def.operations.create) {
+    register({
+      name: `${def.plural}-create`,
+      description: `Create a new ${def.name}.`,
+      access: def.operations.create,
+      resource: def.plural,
+      parseArgs: (raw) => normalizeArgs(raw),
+      handler: genericCreate(def),
+    });
+  }
+
+  if (def.operations.update) {
+    register({
+      name: `${def.plural}-update`,
+      description: `Update a ${def.name}.`,
+      access: def.operations.update,
+      resource: def.plural,
+      parseArgs: (raw) => normalizeArgs(raw),
+      handler: genericUpdate(def),
+    });
+  }
+
+  if (def.operations.delete) {
+    register({
+      name: `${def.plural}-delete`,
+      description: `Delete a ${def.name}.`,
+      access: def.operations.delete,
+      resource: def.plural,
+      parseArgs: (raw) => normalizeArgs(raw),
+      handler: genericDelete(def),
+    });
+  }
+
+  // Custom operations
+  if (def.customOperations) {
+    for (const [verb, op] of Object.entries(def.customOperations)) {
+      register({
+        name: `${def.plural}-${verb}`,
+        description: op.description,
+        access: op.access,
+        resource: def.plural,
+        parseArgs: (raw) => normalizeArgs(raw),
+        handler: async (args, ctx) => op.handler(args as Record<string, unknown>, ctx),
+      });
+    }
+  }
+}

src/cli/delivery-action.ts

@@ -0,0 +1,59 @@
+/**
+ * Delivery action handler for CLI requests from container agents.
+ *
+ * When an agent writes a `cli_request` system message to outbound.db,
+ * the delivery poll picks it up and calls this handler. We dispatch
+ * the command and write the response back to inbound.db.
+ */
+import type Database from 'better-sqlite3';
+
+import { registerDeliveryAction } from '../delivery.js';
+import { insertMessage } from '../db/session-db.js';
+import { log } from '../log.js';
+import { dispatch } from './dispatch.js';
+import type { RequestFrame } from './frame.js';
+import type { Session } from '../types.js';
+
+registerDeliveryAction('cli_request', async (content, session, inDb) => {
+  const requestId = content.requestId as string;
+  const command = content.command as string;
+  const args = (content.args as Record<string, unknown>) ?? {};
+
+  if (!requestId || !command) {
+    log.warn('cli_request missing requestId or command', { sessionId: session.id });
+    return;
+  }
+
+  const req: RequestFrame = { id: requestId, command, args };
+  const ctx = {
+    caller: 'agent' as const,
+    sessionId: session.id,
+    agentGroupId: session.agent_group_id,
+    messagingGroupId: session.messaging_group_id ?? '',
+  };
+
+  log.info('CLI request from agent', { requestId, command, sessionId: session.id });
+
+  const response = await dispatch(req, ctx);
+
+  // Write response to inbound.db so the container can read it.
+  // trigger=0: don't wake the agent — this is an inline response to a tool call.
+  insertMessage(inDb, {
+    id: `cli-resp-${requestId}`,
+    kind: 'system',
+    timestamp: new Date().toISOString(),
+    platformId: null,
+    channelType: null,
+    threadId: null,
+    content: JSON.stringify({
+      type: 'cli_response',
+      requestId,
+      frame: response,
+    }),
+    processAfter: null,
+    recurrence: null,
+    trigger: 0,
+  });
+
+  log.info('CLI response written', { requestId, ok: response.ok, sessionId: session.id });
+});

src/cli/dispatch.ts

@@ -0,0 +1,78 @@
+/**
+ * Transport-agnostic dispatcher. Both the socket server (host caller) and
+ * the per-session DB poller (container caller) call dispatch() with the
+ * same frame and a transport-supplied CallerContext.
+ *
+ * Approval gating for risky calls from the container is the only branch
+ * that differs by caller. Host callers and `open` commands run inline.
+ */
+import { getAgentGroup } from '../db/agent-groups.js';
+import { getSession } from '../db/sessions.js';
+import { registerApprovalHandler, requestApproval } from '../modules/approvals/index.js';
+import type { CallerContext, ErrorCode, RequestFrame, ResponseFrame } from './frame.js';
+import { lookup } from './registry.js';
+
+export async function dispatch(req: RequestFrame, ctx: CallerContext): Promise<ResponseFrame> {
+  const cmd = lookup(req.command);
+  if (!cmd) {
+    return err(req.id, 'unknown-command', `no command "${req.command}"`);
+  }
+
+  if (ctx.caller !== 'host' && cmd.access === 'approval') {
+    const session = getSession(ctx.sessionId);
+    if (!session) {
+      return err(req.id, 'handler-error', 'Session not found.');
+    }
+    const agentGroup = getAgentGroup(ctx.agentGroupId);
+    const agentName = agentGroup?.name ?? ctx.agentGroupId;
+
+    const argSummary = Object.entries(req.args)
+      .map(([k, v]) => `--${k} ${v}`)
+      .join(' ');
+
+    await requestApproval({
+      session,
+      agentName,
+      action: 'cli_command',
+      payload: { frame: { id: req.id, command: req.command, args: req.args } },
+      title: `CLI: ${req.command}`,
+      question: `Agent "${agentName}" wants to run:\n\`ncl ${req.command}${argSummary ? ' ' + argSummary : ''}\``,
+    });
+
+    return err(req.id, 'approval-pending', 'Approval request sent to admin. You will be notified of the result.');
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = cmd.parseArgs(req.args);
+  } catch (e) {
+    return err(req.id, 'invalid-args', errMsg(e));
+  }
+
+  try {
+    const data = await cmd.handler(parsed, ctx);
+    return { id: req.id, ok: true, data };
+  } catch (e) {
+    return err(req.id, 'handler-error', errMsg(e));
+  }
+}
+
+registerApprovalHandler('cli_command', async ({ session, payload, userId, notify }) => {
+  const frame = payload.frame as RequestFrame;
+  const response = await dispatch(frame, { caller: 'host' });
+
+  if (response.ok) {
+    const data = typeof response.data === 'string' ? response.data : JSON.stringify(response.data, null, 2);
+    notify(`Your \`ncl ${frame.command}\` request was approved and executed.\n\n${data}`);
+  } else {
+    notify(`Your \`ncl ${frame.command}\` request was approved but failed: ${response.error.message}`);
+  }
+});
+
+function err(id: string, code: ErrorCode, message: string): ResponseFrame {
+  return { id, ok: false, error: { code, message } };
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

src/cli/format.ts

@@ -0,0 +1,52 @@
+/**
+ * Output formatting for the `ncl` binary. Two modes:
+ *   - human (default): a small auto-table for arrays of flat records,
+ *     JSON.stringify for everything else, plain "error: ..." line for !ok.
+ *   - json: the response frame, pretty-printed.
+ *
+ * The MCP / agent side will always pass --json so it parses the frame
+ * itself. The DB transport (when it lands) skips this layer entirely —
+ * the agent sees frames directly.
+ */
+import type { ResponseFrame } from './frame.js';
+
+export type FormatMode = 'human' | 'json';
+
+export function formatResponse(res: ResponseFrame, mode: FormatMode): string {
+  if (mode === 'json') return JSON.stringify(res, null, 2) + '\n';
+
+  if (!res.ok) {
+    return `error (${res.error.code}): ${res.error.message}\n`;
+  }
+  return formatHuman(res.data) + '\n';
+}
+
+function formatHuman(data: unknown): string {
+  if (data === null || data === undefined) return '';
+  if (typeof data === 'string') return data;
+  if (Array.isArray(data) && data.every(isFlatRecord)) {
+    return renderTable(data as Record<string, unknown>[]);
+  }
+  return JSON.stringify(data, null, 2);
+}
+
+function isFlatRecord(x: unknown): x is Record<string, unknown> {
+  if (!x || typeof x !== 'object') return false;
+  for (const v of Object.values(x as Record<string, unknown>)) {
+    if (v !== null && typeof v === 'object') return false;
+  }
+  return true;
+}
+
+function renderTable(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) return '(no rows)';
+  const cols = Object.keys(rows[0]);
+  const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+  const fmtRow = (vals: string[]): string => vals.map((v, i) => v.padEnd(widths[i])).join('  ');
+  const lines = [
+    fmtRow(cols),
+    fmtRow(widths.map((w) => '─'.repeat(w))),
+    ...rows.map((r) => fmtRow(cols.map((c) => String(r[c] ?? '')))),
+  ];
+  return lines.join('\n');
+}

src/cli/frame.ts

@@ -0,0 +1,44 @@
+/**
+ * Wire format shared between the socket transport (host caller) and — when
+ * it lands — the DB transport (container agent caller).
+ *
+ * Same JSON whether it goes over a socket as a line or sits in a
+ * `frame_json TEXT` column on a session DB. Caller identity is NOT carried
+ * in the frame — it's filled in by whichever server-side adapter received
+ * the bytes (see CallerContext).
+ */
+
+export type RequestFrame = {
+  /** Correlation key set by the client. */
+  id: string;
+  /** Registry name, e.g. "list-groups". */
+  command: string;
+  /** Command-specific. Each command's parseArgs validates. */
+  args: Record<string, unknown>;
+};
+
+export type ResponseFrame =
+  | { id: string; ok: true; data: unknown }
+  | { id: string; ok: false; error: { code: ErrorCode; message: string } };
+
+export type ErrorCode =
+  | 'unknown-command'
+  | 'invalid-args'
+  | 'permission-denied'
+  | 'approval-pending'
+  | 'not-found'
+  | 'handler-error'
+  | 'transport-error';
+
+/**
+ * Filled in by the transport adapter on the server side. Handlers read
+ * caller identity from here, never from the frame.
+ */
+export type CallerContext =
+  | { caller: 'host' }
+  | {
+      caller: 'agent';
+      sessionId: string;
+      agentGroupId: string;
+      messagingGroupId: string;
+    };

src/cli/registry.ts

@@ -0,0 +1,38 @@
+/**
+ * Command registry — single source of truth for what `ncl` can do.
+ *
+ * Each command file under `commands/` calls `register()` at top level,
+ * and `commands/index.ts` imports them all for side effects so the
+ * registry is populated before the host's CLI server accepts connections.
+ */
+import type { CallerContext } from './frame.js';
+
+export type Access = 'open' | 'approval' | 'hidden';
+
+export type CommandDef<TArgs = unknown, TData = unknown> = {
+  name: string;
+  description: string;
+  access: Access;
+  /** Resource this command belongs to (for help grouping). */
+  resource?: string;
+  /** Validates `frame.args` and produces the typed handler input. Throws on invalid. */
+  parseArgs: (raw: Record<string, unknown>) => TArgs;
+  handler: (args: TArgs, ctx: CallerContext) => Promise<TData>;
+};
+
+const registry = new Map<string, CommandDef>();
+
+export function register<TArgs, TData>(def: CommandDef<TArgs, TData>): void {
+  if (registry.has(def.name)) {
+    throw new Error(`CLI command "${def.name}" already registered`);
+  }
+  registry.set(def.name, def as CommandDef);
+}
+
+export function lookup(name: string): CommandDef | undefined {
+  return registry.get(name);
+}
+
+export function listCommands(): CommandDef[] {
+  return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

src/cli/resources/approvals.ts

@@ -0,0 +1,53 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'approval',
+  plural: 'approvals',
+  table: 'pending_approvals',
+  description:
+    '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.',
+  idColumn: 'approval_id',
+  columns: [
+    {
+      name: 'approval_id',
+      type: 'string',
+      description: 'Unique approval identifier (also used as the card questionId).',
+    },
+    {
+      name: 'session_id',
+      type: 'string',
+      description: 'Session that requested the approval. Null for OneCLI credential approvals.',
+    },
+    {
+      name: 'request_id',
+      type: 'string',
+      description: 'Original request identifier (OneCLI request UUID or same as approval_id).',
+    },
+    {
+      name: 'action',
+      type: 'string',
+      description:
+        'Action type — matches the registered approval handler (e.g. install_packages, add_mcp_server, onecli_credential).',
+    },
+    { name: 'payload', type: 'json', description: 'JSON payload carried through to the approval handler.' },
+    { name: 'created_at', type: 'string', description: 'Auto-set.' },
+    { name: 'agent_group_id', type: 'string', description: 'Originating agent group.' },
+    { name: 'channel_type', type: 'string', description: 'Channel the approval card was delivered on.' },
+    { name: 'platform_id', type: 'string', description: 'Platform chat ID the card was delivered to.' },
+    {
+      name: 'platform_message_id',
+      type: 'string',
+      description: 'Platform message ID of the delivered card (for editing on expiry).',
+    },
+    { name: 'expires_at', type: 'string', description: 'When this approval expires (OneCLI gateway TTL).' },
+    {
+      name: 'status',
+      type: 'string',
+      description: 'Current status.',
+      enum: ['pending', 'approved', 'rejected', 'expired'],
+    },
+    { name: 'title', type: 'string', description: 'Card title shown to the admin.' },
+    { name: 'options_json', type: 'json', description: 'Card button options as JSON array.' },
+  ],
+  operations: { list: 'open', get: 'open' },
+});

src/cli/resources/destinations.ts

@@ -0,0 +1,77 @@
+import { getDb } from '../../db/connection.js';
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'destination',
+  plural: 'destinations',
+  table: 'agent_destinations',
+  description:
+    '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.',
+  idColumn: 'agent_group_id',
+  columns: [
+    {
+      name: 'agent_group_id',
+      type: 'string',
+      description: 'The agent that owns this destination. References agent_groups.id.',
+    },
+    {
+      name: 'local_name',
+      type: 'string',
+      description:
+        'Name the agent uses to address this target (e.g. <message to="local_name">). Unique per agent. Lowercase, dash-separated.',
+    },
+    {
+      name: 'target_type',
+      type: 'string',
+      description: '"channel" for messaging group targets, "agent" for agent-to-agent targets.',
+      enum: ['channel', 'agent'],
+    },
+    {
+      name: 'target_id',
+      type: 'string',
+      description: "The target's ID — messaging_groups.id for channels, agent_groups.id for agents.",
+    },
+    { name: 'created_at', type: 'string', description: 'Auto-set.' },
+  ],
+  operations: { list: 'open' },
+  customOperations: {
+    add: {
+      access: 'approval',
+      description: 'Add a destination for an agent. Use --agent-group-id, --local-name, --target-type, --target-id.',
+      handler: async (args) => {
+        const agentGroupId = args.agent_group_id as string;
+        const localName = args.local_name as string;
+        const targetType = args.target_type as string;
+        const targetId = args.target_id as string;
+        if (!agentGroupId) throw new Error('--agent-group-id is required');
+        if (!localName) throw new Error('--local-name is required');
+        if (!targetType || !['channel', 'agent'].includes(targetType)) {
+          throw new Error('--target-type must be channel or agent');
+        }
+        if (!targetId) throw new Error('--target-id is required');
+        getDb()
+          .prepare(
+            `INSERT INTO agent_destinations (agent_group_id, local_name, target_type, target_id, created_at)
+             VALUES (?, ?, ?, ?, datetime('now'))`,
+          )
+          .run(agentGroupId, localName, targetType, targetId);
+        return { agent_group_id: agentGroupId, local_name: localName, target_type: targetType, target_id: targetId };
+      },
+    },
+    remove: {
+      access: 'approval',
+      description: 'Remove a destination from an agent. Use --agent-group-id and --local-name.',
+      handler: async (args) => {
+        const agentGroupId = args.agent_group_id as string;
+        const localName = args.local_name as string;
+        if (!agentGroupId) throw new Error('--agent-group-id is required');
+        if (!localName) throw new Error('--local-name is required');
+        const result = getDb()
+          .prepare('DELETE FROM agent_destinations WHERE agent_group_id = ? AND local_name = ?')
+          .run(agentGroupId, localName);
+        if (result.changes === 0) throw new Error('destination not found');
+        return { removed: { agent_group_id: agentGroupId, local_name: localName } };
+      },
+    },
+  },
+});

src/cli/resources/dropped-messages.ts

@@ -0,0 +1,28 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'dropped-message',
+  plural: 'dropped-messages',
+  table: 'unregistered_senders',
+  description:
+    "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).",
+  idColumn: 'channel_type',
+  columns: [
+    { name: 'channel_type', type: 'string', description: 'Channel adapter type of the dropped message.' },
+    { name: 'platform_id', type: 'string', description: 'Platform chat ID where the message was dropped.' },
+    { name: 'user_id', type: 'string', description: 'Sender user ID if resolved, null otherwise.' },
+    { name: 'sender_name', type: 'string', description: 'Sender display name if available.' },
+    {
+      name: 'reason',
+      type: 'string',
+      description: 'Why the message was dropped.',
+      enum: ['no_agent_wired', 'no_agent_engaged', 'unknown_sender_strict', 'unknown_sender_request_approval'],
+    },
+    { name: 'messaging_group_id', type: 'string', description: 'Messaging group ID if resolved.' },
+    { name: 'agent_group_id', type: 'string', description: 'Target agent group ID if resolved.' },
+    { name: 'message_count', type: 'number', description: 'Number of dropped messages from this sender on this chat.' },
+    { name: 'first_seen', type: 'string', description: 'First drop timestamp.' },
+    { name: 'last_seen', type: 'string', description: 'Most recent drop timestamp.' },
+  ],
+  operations: { list: 'open' },
+});

src/cli/resources/groups.ts

@@ -0,0 +1,37 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'group',
+  plural: 'groups',
+  table: 'agent_groups',
+  description:
+    '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.',
+  idColumn: 'id',
+  columns: [
+    { name: 'id', type: 'string', description: 'UUID.', generated: true },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Display name shown in logs, help output, and channel adapters. Does not need to be unique.',
+      required: true,
+      updatable: true,
+    },
+    {
+      name: 'folder',
+      type: 'string',
+      description:
+        'Directory name under groups/ on the host. Must be unique. Contains CLAUDE.md, skills/, and container.json. Cannot be changed after creation.',
+      required: true,
+    },
+    {
+      name: 'agent_provider',
+      type: 'string',
+      description:
+        'LLM provider. Null means the default (claude). Skill-installed providers (e.g. opencode) register via /add-<provider>.',
+      updatable: true,
+      default: null,
+    },
+    { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
+  ],
+  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval', delete: 'approval' },
+});

src/cli/resources/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Resource barrel — imports each resource module for its side-effect
+ * `registerResource(...)` call.
+ */
+import './groups.js';
+import './messaging-groups.js';
+import './wirings.js';
+import './users.js';
+import './roles.js';
+import './members.js';
+import './destinations.js';
+import './user-dms.js';
+import './dropped-messages.js';
+import './approvals.js';
+import './sessions.js';

src/cli/resources/members.ts

@@ -0,0 +1,65 @@
+import { getDb } from '../../db/connection.js';
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'member',
+  plural: 'members',
+  table: 'agent_group_members',
+  description:
+    '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".',
+  idColumn: 'user_id',
+  columns: [
+    {
+      name: 'user_id',
+      type: 'string',
+      description: 'The user to grant membership. Must reference an existing user (users.id).',
+    },
+    {
+      name: 'agent_group_id',
+      type: 'string',
+      description: 'The agent group to grant access to. Must reference an existing agent group (agent_groups.id).',
+    },
+    {
+      name: 'added_by',
+      type: 'string',
+      description: 'User ID of whoever added this member. Informational — not enforced.',
+    },
+    { name: 'added_at', type: 'string', description: 'ISO 8601 timestamp of when the membership was granted.' },
+  ],
+  operations: { list: 'open' },
+  customOperations: {
+    add: {
+      access: 'approval',
+      description: 'Add a user as a member of an agent group. Use --user and --group.',
+      handler: async (args) => {
+        const userId = args.user as string;
+        const groupId = args.group as string;
+        const addedBy = (args.added_by as string) ?? null;
+        if (!userId) throw new Error('--user is required');
+        if (!groupId) throw new Error('--group is required');
+        getDb()
+          .prepare(
+            `INSERT OR IGNORE INTO agent_group_members (user_id, agent_group_id, added_by, added_at)
+             VALUES (?, ?, ?, datetime('now'))`,
+          )
+          .run(userId, groupId, addedBy);
+        return { user_id: userId, agent_group_id: groupId };
+      },
+    },
+    remove: {
+      access: 'approval',
+      description: 'Remove a user from an agent group. Use --user and --group.',
+      handler: async (args) => {
+        const userId = args.user as string;
+        const groupId = args.group as string;
+        if (!userId) throw new Error('--user is required');
+        if (!groupId) throw new Error('--group is required');
+        const result = getDb()
+          .prepare('DELETE FROM agent_group_members WHERE user_id = ? AND agent_group_id = ?')
+          .run(userId, groupId);
+        if (result.changes === 0) throw new Error('member not found');
+        return { removed: { user_id: userId, agent_group_id: groupId } };
+      },
+    },
+  },
+});

src/cli/resources/messaging-groups.ts

@@ -0,0 +1,58 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'messaging-group',
+  plural: 'messaging-groups',
+  table: 'messaging_groups',
+  description:
+    '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.',
+  idColumn: 'id',
+  columns: [
+    { name: 'id', type: 'string', description: 'UUID.', generated: true },
+    {
+      name: 'channel_type',
+      type: 'string',
+      description:
+        'Channel adapter type — matches the adapter registered by /add-<channel> (e.g. telegram, discord, slack, whatsapp).',
+      required: true,
+    },
+    {
+      name: 'platform_id',
+      type: 'string',
+      description:
+        'Platform-specific chat ID. Format varies: Telegram chat ID, Discord channel snowflake, Slack channel ID, phone number, email address.',
+      required: true,
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Display name. Often auto-populated by the channel adapter.',
+      updatable: true,
+    },
+    {
+      name: 'is_group',
+      type: 'number',
+      description: 'Multi-user group chat (1) or direct message (0). Affects session scoping.',
+      default: 0,
+      updatable: true,
+    },
+    {
+      name: 'unknown_sender_policy',
+      type: 'string',
+      description:
+        'What happens when an unrecognized sender posts. "strict" drops silently. "request_approval" sends an approval card to an admin. "public" allows anyone.',
+      enum: ['strict', 'request_approval', 'public'],
+      default: 'strict',
+      updatable: true,
+    },
+    {
+      name: 'denied_at',
+      type: 'string',
+      description:
+        'Set when the owner explicitly denies registering this channel. While set, the router drops all messages silently without re-escalating. Cleared by any explicit wiring mutation.',
+      updatable: true,
+    },
+    { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
+  ],
+  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval', delete: 'approval' },
+});

src/cli/resources/roles.ts

@@ -0,0 +1,67 @@
+import { getDb } from '../../db/connection.js';
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'role',
+  plural: 'roles',
+  table: 'user_roles',
+  description:
+    '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).',
+  idColumn: 'user_id',
+  columns: [
+    { name: 'user_id', type: 'string', description: 'User receiving the role. Must exist in users table.' },
+    {
+      name: 'role',
+      type: 'string',
+      description: '"owner" has full control, always global. "admin" can manage groups and approve actions.',
+      enum: ['owner', 'admin'],
+    },
+    {
+      name: 'agent_group_id',
+      type: 'string',
+      description:
+        'Null = global (all groups). A specific ID limits the role to that group. Owner must always be null.',
+    },
+    { name: 'granted_by', type: 'string', description: 'Who granted this role. Informational.' },
+    { name: 'granted_at', type: 'string', description: 'Auto-set.' },
+  ],
+  operations: { list: 'open' },
+  customOperations: {
+    grant: {
+      access: 'approval',
+      description: 'Grant a role. Use --user, --role, and optionally --group for scoped admin.',
+      handler: async (args) => {
+        const userId = args.user as string;
+        const role = args.role as string;
+        const groupId = (args.group as string) ?? null;
+        const grantedBy = (args.granted_by as string) ?? null;
+        if (!userId) throw new Error('--user is required');
+        if (!role || !['owner', 'admin'].includes(role)) throw new Error('--role must be owner or admin');
+        if (role === 'owner' && groupId) throw new Error('owner role is always global (do not pass --group)');
+        getDb()
+          .prepare(
+            `INSERT OR IGNORE INTO user_roles (user_id, role, agent_group_id, granted_by, granted_at)
+             VALUES (?, ?, ?, ?, datetime('now'))`,
+          )
+          .run(userId, role, groupId, grantedBy);
+        return { user_id: userId, role, agent_group_id: groupId };
+      },
+    },
+    revoke: {
+      access: 'approval',
+      description: 'Revoke a role. Use --user, --role, and --group if scoped.',
+      handler: async (args) => {
+        const userId = args.user as string;
+        const role = args.role as string;
+        const groupId = (args.group as string) ?? null;
+        if (!userId) throw new Error('--user is required');
+        if (!role) throw new Error('--role is required');
+        const result = getDb()
+          .prepare('DELETE FROM user_roles WHERE user_id = ? AND role = ? AND agent_group_id IS ?')
+          .run(userId, role, groupId);
+        if (result.changes === 0) throw new Error('role not found');
+        return { revoked: { user_id: userId, role, agent_group_id: groupId } };
+      },
+    },
+  },
+});

src/cli/resources/sessions.ts

@@ -0,0 +1,45 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'session',
+  plural: 'sessions',
+  table: 'sessions',
+  description:
+    '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.',
+  idColumn: 'id',
+  columns: [
+    { name: 'id', type: 'string', description: 'UUID.', generated: true },
+    { name: 'agent_group_id', type: 'string', description: 'Agent group this session runs.' },
+    {
+      name: 'messaging_group_id',
+      type: 'string',
+      description: 'Messaging group this session serves. Null for agent-shared sessions.',
+    },
+    {
+      name: 'thread_id',
+      type: 'string',
+      description: 'Thread ID. Only set for per-thread session mode.',
+    },
+    {
+      name: 'agent_provider',
+      type: 'string',
+      description: 'Provider override. Null means inherit from agent group.',
+    },
+    {
+      name: 'status',
+      type: 'string',
+      description: '"active" receives messages. "closed" is archived.',
+      enum: ['active', 'closed'],
+    },
+    {
+      name: 'container_status',
+      type: 'string',
+      description:
+        '"running" — container alive and polling. "stopped" — container exited; the sweep will restart it automatically when due messages arrive. "idle" — reserved, currently unused.',
+      enum: ['running', 'idle', 'stopped'],
+    },
+    { name: 'last_active', type: 'string', description: 'Last message or heartbeat. Used for stale detection.' },
+    { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
+  ],
+  operations: { list: 'open', get: 'open' },
+});

src/cli/resources/user-dms.ts

@@ -0,0 +1,21 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'user-dm',
+  plural: 'user-dms',
+  table: 'user_dms',
+  description:
+    "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.",
+  idColumn: 'user_id',
+  columns: [
+    { name: 'user_id', type: 'string', description: 'User this DM route is for.' },
+    { name: 'channel_type', type: 'string', description: 'Channel adapter type.' },
+    {
+      name: 'messaging_group_id',
+      type: 'string',
+      description: 'The messaging group used to deliver DMs to this user on this channel.',
+    },
+    { name: 'resolved_at', type: 'string', description: 'When this DM route was last resolved.' },
+  ],
+  operations: { list: 'open' },
+});

src/cli/resources/users.ts

@@ -0,0 +1,35 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'user',
+  plural: 'users',
+  table: 'users',
+  description:
+    '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).',
+  idColumn: 'id',
+  columns: [
+    {
+      name: 'id',
+      type: 'string',
+      description:
+        'Namespaced "channel_type:handle" — e.g. "tg:6037840640", "discord:123456789", "email:user@example.com". Must be provided on create.',
+      required: true,
+    },
+    {
+      name: 'kind',
+      type: 'string',
+      description:
+        'Channel type identifier (e.g. "telegram", "discord"). Used as a fallback for DM resolution when the id prefix doesn\'t match a registered adapter.',
+      required: true,
+    },
+    {
+      name: 'display_name',
+      type: 'string',
+      description:
+        'Human-readable name. Shown in approval cards and logs. Often auto-populated from the channel adapter.',
+      updatable: true,
+    },
+    { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
+  ],
+  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval' },
+});

src/cli/resources/wirings.ts

@@ -0,0 +1,70 @@
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'wiring',
+  plural: 'wirings',
+  table: 'messaging_group_agents',
+  description:
+    '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.',
+  idColumn: 'id',
+  columns: [
+    { name: 'id', type: 'string', description: 'UUID.', generated: true },
+    {
+      name: 'messaging_group_id',
+      type: 'string',
+      description: 'The chat/channel to route from. References messaging_groups.id.',
+      required: true,
+    },
+    {
+      name: 'agent_group_id',
+      type: 'string',
+      description: 'The agent that handles messages. References agent_groups.id.',
+      required: true,
+    },
+    {
+      name: 'engage_mode',
+      type: 'string',
+      description:
+        'When the agent engages. "mention" — only when @mentioned or in DMs. "mention-sticky" — once mentioned in a thread, the agent subscribes and responds to all subsequent messages in that thread without needing further mentions. "pattern" — matches every message against engage_pattern regex.',
+      enum: ['pattern', 'mention', 'mention-sticky'],
+      default: 'mention',
+      updatable: true,
+    },
+    {
+      name: 'engage_pattern',
+      type: 'string',
+      description:
+        'Regex for engage_mode=pattern. Required when mode is pattern. Use "." to match every message (always-on). Ignored for mention modes.',
+      updatable: true,
+    },
+    {
+      name: 'sender_scope',
+      type: 'string',
+      description:
+        '"all" — any sender (subject to unknown_sender_policy). "known" — only users with a role or membership in this agent group.',
+      enum: ['all', 'known'],
+      default: 'all',
+      updatable: true,
+    },
+    {
+      name: 'ignored_message_policy',
+      type: 'string',
+      description:
+        'What happens to messages that don\'t trigger engagement. "drop" — agent never sees them. "accumulate" — stored as background context (trigger=0) so the agent has prior context when eventually triggered.',
+      enum: ['drop', 'accumulate'],
+      default: 'drop',
+      updatable: true,
+    },
+    {
+      name: 'session_mode',
+      type: 'string',
+      description:
+        '"shared" — one session per (agent, messaging group). "per-thread" — separate session per thread/topic. "agent-shared" — one session across all messaging groups wired to this agent. Note: threaded adapters in group chats force per-thread regardless of this setting.',
+      enum: ['shared', 'per-thread', 'agent-shared'],
+      default: 'shared',
+      updatable: true,
+    },
+    { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
+  ],
+  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval', delete: 'approval' },
+});

src/cli/socket-client.ts

@@ -0,0 +1,63 @@
+/**
+ * SocketTransport — client side. Used by the `ncl` binary when running on
+ * the host (i.e. invoked from a shell or by Claude in the project).
+ *
+ * Wire format: line-delimited JSON. One request per connection; the server
+ * writes one response and closes.
+ */
+import net from 'net';
+import path from 'path';
+
+import { DATA_DIR } from '../config.js';
+import type { RequestFrame, ResponseFrame } from './frame.js';
+import type { Transport } from './transport.js';
+
+export const DEFAULT_SOCKET_PATH = path.join(DATA_DIR, 'ncl.sock');
+
+export class SocketTransport implements Transport {
+  constructor(private readonly socketPath: string = DEFAULT_SOCKET_PATH) {}
+
+  async sendFrame(req: RequestFrame): Promise<ResponseFrame> {
+    return new Promise((resolve, reject) => {
+      const client = net.createConnection(this.socketPath);
+      let buffer = '';
+      let settled = false;
+
+      const settle = (action: 'resolve' | 'reject', valueOrErr: ResponseFrame | Error): void => {
+        if (settled) return;
+        settled = true;
+        try {
+          client.end();
+        } catch (_e) {
+          // best-effort
+        }
+        if (action === 'resolve') resolve(valueOrErr as ResponseFrame);
+        else reject(valueOrErr as Error);
+      };
+
+      client.on('connect', () => {
+        client.write(JSON.stringify(req) + '\n');
+      });
+
+      client.on('data', (chunk) => {
+        buffer += chunk.toString('utf8');
+        const idx = buffer.indexOf('\n');
+        if (idx < 0) return;
+        const line = buffer.slice(0, idx);
+        try {
+          const frame = JSON.parse(line) as ResponseFrame;
+          settle('resolve', frame);
+        } catch (e) {
+          settle('reject', new Error(`malformed response from host: ${e instanceof Error ? e.message : String(e)}`));
+        }
+      });
+
+      client.on('error', (err) => settle('reject', err));
+      client.on('close', () => {
+        if (!settled) {
+          settle('reject', new Error('host closed connection before sending response'));
+        }
+      });
+    });
+  }
+}

src/cli/socket-server.ts

@@ -0,0 +1,111 @@
+/**
+ * Host-side socket listener. Started from src/index.ts, accepts one frame
+ * per connection, calls dispatch() with caller='host', writes the response
+ * frame, closes.
+ *
+ * Lives at data/ncl.sock (separate from data/cli.sock, which the existing
+ * chat-style CLI channel adapter owns). Socket file is chmod 0600 — only
+ * the user that started the host can connect.
+ */
+import fs from 'fs';
+import net from 'net';
+
+import { log } from '../log.js';
+import { dispatch } from './dispatch.js';
+import type { CallerContext, RequestFrame, ResponseFrame } from './frame.js';
+import { DEFAULT_SOCKET_PATH } from './socket-client.js';
+
+let server: net.Server | null = null;
+
+export async function startCliServer(socketPath: string = DEFAULT_SOCKET_PATH): Promise<void> {
+  // Stale-socket cleanup — a previous run that crashed may have left the
+  // file behind, and net.createServer refuses to bind to an existing path.
+  try {
+    fs.unlinkSync(socketPath);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code !== 'ENOENT') {
+      log.warn('Failed to unlink stale ncl socket (will try to bind anyway)', { socketPath, err });
+    }
+  }
+
+  const s = net.createServer((conn) => handleConnection(conn));
+  server = s;
+  await new Promise<void>((resolve, reject) => {
+    s.once('error', reject);
+    s.listen(socketPath, () => {
+      try {
+        fs.chmodSync(socketPath, 0o600);
+      } catch (err) {
+        log.warn('Failed to chmod ncl socket (continuing)', { socketPath, err });
+      }
+      log.info('ncl CLI server listening', { socketPath });
+      resolve();
+    });
+  });
+}
+
+export async function stopCliServer(): Promise<void> {
+  if (!server) return;
+  const s = server;
+  server = null;
+  await new Promise<void>((resolve) => s.close(() => resolve()));
+}
+
+function handleConnection(conn: net.Socket): void {
+  let buffer = '';
+  conn.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    let idx: number;
+    while ((idx = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, idx).trim();
+      buffer = buffer.slice(idx + 1);
+      if (!line) continue;
+      void handleFrame(conn, line);
+    }
+  });
+  conn.on('error', (err) => {
+    log.warn('ncl CLI server connection error', { err });
+  });
+}
+
+async function handleFrame(conn: net.Socket, line: string): Promise<void> {
+  let req: RequestFrame;
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (!isRequestFrame(parsed)) throw new Error('bad request shape');
+    req = parsed;
+  } catch (e) {
+    write(conn, {
+      id: 'unknown',
+      ok: false,
+      error: {
+        code: 'transport-error',
+        message: `bad frame: ${e instanceof Error ? e.message : String(e)}`,
+      },
+    });
+    return;
+  }
+
+  // Host caller — connecting to data/ncl.sock requires file-system access
+  // to a 0600 socket owned by the host user, so we treat the socket path
+  // itself as the auth boundary.
+  const ctx: CallerContext = { caller: 'host' };
+  const res = await dispatch(req, ctx);
+  write(conn, res);
+}
+
+function write(conn: net.Socket, frame: ResponseFrame): void {
+  try {
+    conn.write(JSON.stringify(frame) + '\n');
+    conn.end();
+  } catch (err) {
+    log.warn('Failed to write ncl CLI response', { err });
+  }
+}
+
+function isRequestFrame(x: unknown): x is RequestFrame {
+  if (!x || typeof x !== 'object') return false;
+  const o = x as Record<string, unknown>;
+  return typeof o.id === 'string' && typeof o.command === 'string' && typeof o.args === 'object' && o.args !== null;
+}

src/cli/transport.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-side transport interface. The `ncl` binary picks one of these and
+ * calls sendFrame; the caller doesn't know whether bytes traveled over a
+ * Unix socket (host) or through outbound.db / inbound.db rows (container).
+ */
+import type { RequestFrame, ResponseFrame } from './frame.js';
+
+export interface Transport {
+  sendFrame(req: RequestFrame): Promise<ResponseFrame>;
+}

src/db/schema.ts

@@ -171,7 +171,13 @@ CREATE TABLE IF NOT EXISTS messages_in (
   platform_id    TEXT,
   channel_type   TEXT,
   thread_id      TEXT,
-  content        TEXT NOT NULL
+  content        TEXT NOT NULL,
+  -- For agent-to-agent inbound rows: the source session that emitted the
+  -- triggering outbound. Used as a return path when the target replies —
+  -- the reply routes back to this exact session, not to the source agent
+  -- group's "newest" session. NULL on channel-side inbound and on a2a rows
+  -- written before this column existed.
+  source_session_id TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_messages_in_series ON messages_in(series_id);
 

src/db/session-db.test.ts

@@ -10,7 +10,7 @@ import fs from 'fs';
 import path from 'path';
 import { describe, it, expect, afterEach } from 'vitest';
 
-import { migrateMessagesInTable } from './session-db.js';
+import { getInboundSourceSessionId, migrateMessagesInTable } from './session-db.js';
 
 const TEST_DIR = '/tmp/nanoclaw-session-db-test';
 const DB_PATH = path.join(TEST_DIR, 'inbound.db');
@@ -55,4 +55,40 @@ describe('migrateMessagesInTable', () => {
     expect(row.series_id).toBe('legacy-1');
     db.close();
   });
+
+  it('adds source_session_id on a legacy DB, leaves existing rows NULL, is idempotent', () => {
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+
+    const db = new Database(DB_PATH);
+    db.exec(`
+      CREATE TABLE messages_in (
+        id             TEXT PRIMARY KEY,
+        seq            INTEGER UNIQUE,
+        kind           TEXT NOT NULL,
+        timestamp      TEXT NOT NULL,
+        status         TEXT DEFAULT 'pending',
+        process_after  TEXT,
+        recurrence     TEXT,
+        tries          INTEGER DEFAULT 0,
+        platform_id    TEXT,
+        channel_type   TEXT,
+        thread_id      TEXT,
+        content        TEXT NOT NULL
+      );
+    `);
+    db.prepare(
+      "INSERT INTO messages_in (id, seq, kind, timestamp, status, content) VALUES (?, ?, 'chat', datetime('now'), 'pending', '{}')",
+    ).run('legacy-2', 2);
+
+    migrateMessagesInTable(db);
+    migrateMessagesInTable(db); // idempotent
+
+    const cols = (db.prepare("PRAGMA table_info('messages_in')").all() as Array<{ name: string }>).map((c) => c.name);
+    expect(cols).toContain('source_session_id');
+
+    expect(getInboundSourceSessionId(db, 'legacy-2')).toBeNull();
+    expect(getInboundSourceSessionId(db, 'does-not-exist')).toBeNull();
+    db.close();
+  });
 });

src/db/session-db.ts

@@ -108,14 +108,21 @@ export function insertMessage(
      * Host countDueMessages gates on this; container reads everything.
      */
     trigger?: 0 | 1;
+    /**
+     * For agent-to-agent inbound: the source session id that emitted the
+     * outbound message which became this inbound row. Used as the return
+     * path for the target's reply. NULL on channel-side inbound.
+     */
+    sourceSessionId?: string | null;
   },
 ): void {
   db.prepare(
-    `INSERT INTO messages_in (id, seq, kind, timestamp, status, platform_id, channel_type, thread_id, content, process_after, recurrence, series_id, trigger)
-     VALUES (@id, @seq, @kind, @timestamp, 'pending', @platformId, @channelType, @threadId, @content, @processAfter, @recurrence, @id, @trigger)`,
+    `INSERT INTO messages_in (id, seq, kind, timestamp, status, platform_id, channel_type, thread_id, content, process_after, recurrence, series_id, trigger, source_session_id)
+     VALUES (@id, @seq, @kind, @timestamp, 'pending', @platformId, @channelType, @threadId, @content, @processAfter, @recurrence, @id, @trigger, @sourceSessionId)`,
   ).run({
     ...message,
     trigger: message.trigger ?? 1,
+    sourceSessionId: message.sourceSessionId ?? null,
     seq: nextEvenSeq(db),
   });
 }
@@ -239,6 +246,7 @@ export interface OutboundMessage {
   channel_type: string | null;
   thread_id: string | null;
   content: string;
+  in_reply_to: string | null;
 }
 
 export function getDueOutboundMessages(db: Database.Database): OutboundMessage[] {
@@ -305,4 +313,47 @@ export function migrateMessagesInTable(db: Database.Database): void {
     // the agent" semantics, so backfill 1 and default 1 for new inserts.
     db.prepare('ALTER TABLE messages_in ADD COLUMN trigger INTEGER NOT NULL DEFAULT 1').run();
   }
+  if (!cols.has('source_session_id')) {
+    // For agent-to-agent return-path routing. NULL on existing rows is fine —
+    // their replies fall back to the legacy "newest active session" lookup.
+    db.prepare('ALTER TABLE messages_in ADD COLUMN source_session_id TEXT').run();
+  }
+}
+
+/**
+ * Look up an inbound row's source_session_id by its message id. Returns null
+ * if the row doesn't exist or the column is NULL (channel inbound or
+ * pre-migration a2a inbound). Used by a2a routing to route replies back to
+ * the originating session.
+ */
+export function getInboundSourceSessionId(db: Database.Database, messageId: string): string | null {
+  const row = db.prepare('SELECT source_session_id FROM messages_in WHERE id = ?').get(messageId) as
+    | { source_session_id: string | null }
+    | undefined;
+  return row?.source_session_id ?? null;
+}
+
+/**
+ * Find the source_session_id of the most recent a2a inbound row from a
+ * specific peer (by agent group id). Used as a peer-affinity fallback in
+ * a2a routing when an outbound reply has no `in_reply_to` (e.g. the
+ * container's send_message MCP tool path didn't thread the batch's
+ * in_reply_to through).
+ *
+ * Heuristic: "the last time this peer talked to me, which session was it?"
+ * Returns null when no prior a2a inbound from that peer carries a
+ * non-null source_session_id (typical for pre-migration installs).
+ */
+export function getMostRecentPeerSourceSessionId(db: Database.Database, peerAgentGroupId: string): string | null {
+  const row = db
+    .prepare(
+      `SELECT source_session_id FROM messages_in
+        WHERE channel_type = 'agent'
+          AND platform_id = ?
+          AND source_session_id IS NOT NULL
+        ORDER BY seq DESC
+        LIMIT 1`,
+    )
+    .get(peerAgentGroupId) as { source_session_id: string | null } | undefined;
+  return row?.source_session_id ?? null;
 }

src/delivery.test.ts

@@ -26,8 +26,16 @@ vi.mock('./config.js', async () => {
 
 const TEST_DIR = '/tmp/nanoclaw-test-delivery';
 
-import { initTestDb, closeDb, runMigrations, createAgentGroup, createMessagingGroup } from './db/index.js';
-import { resolveSession, outboundDbPath } from './session-manager.js';
+import {
+  initTestDb,
+  closeDb,
+  runMigrations,
+  createAgentGroup,
+  createMessagingGroup,
+  createMessagingGroupAgent,
+} from './db/index.js';
+import { getDeliveredIds } from './db/session-db.js';
+import { resolveSession, outboundDbPath, openInboundDb } from './session-manager.js';
 import { deliverSessionMessages, setDeliveryAdapter } from './delivery.js';
 
 function now(): string {
@@ -146,3 +154,120 @@ describe('deliverSessionMessages — concurrent invocations', () => {
     expect(callCount).toBe(1);
   });
 });
+
+describe('deliverSessionMessages — retry and permanent failure', () => {
+  it('retries on adapter failure and marks failed after MAX_DELIVERY_ATTEMPTS (3)', async () => {
+    seedAgentAndChannel();
+    const { session } = resolveSession('ag-1', 'mg-1', null, 'shared');
+    insertOutbound('ag-1', session.id, 'out-flaky');
+
+    let callCount = 0;
+    setDeliveryAdapter({
+      async deliver() {
+        callCount++;
+        throw new Error('network timeout');
+      },
+    });
+
+    // Attempt 1
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(1);
+
+    // Attempt 2
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(2);
+
+    // Attempt 3 — should mark as permanently failed
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(3);
+
+    // Attempt 4 — message is now in delivered (as failed), adapter not called
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(3);
+
+    // Verify the message is in the delivered table with 'failed' status
+    const inDb = openInboundDb('ag-1', session.id);
+    const delivered = getDeliveredIds(inDb);
+    inDb.close();
+    expect(delivered.has('out-flaky')).toBe(true);
+  });
+
+  it('clears attempt counter on successful delivery', async () => {
+    seedAgentAndChannel();
+    const { session } = resolveSession('ag-1', 'mg-1', null, 'shared');
+    insertOutbound('ag-1', session.id, 'out-retry-ok');
+
+    let callCount = 0;
+    setDeliveryAdapter({
+      async deliver() {
+        callCount++;
+        if (callCount === 1) throw new Error('transient');
+        return 'plat-ok';
+      },
+    });
+
+    // Attempt 1 — fails
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(1);
+
+    // Attempt 2 — succeeds
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(2);
+
+    // Attempt 3 — not called, message already delivered
+    await deliverSessionMessages(session);
+    expect(callCount).toBe(2);
+  });
+});
+
+describe('deliverSessionMessages — permission check', () => {
+  it('rejects delivery to an unauthorized channel destination', async () => {
+    seedAgentAndChannel();
+
+    // Create a second messaging group that the agent is NOT wired to
+    createMessagingGroup({
+      id: 'mg-2',
+      channel_type: 'discord',
+      platform_id: 'discord:456',
+      name: 'Unauthorized Chat',
+      is_group: 0,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+
+    // Session is on mg-1 (telegram)
+    const { session } = resolveSession('ag-1', 'mg-1', null, 'shared');
+
+    // Insert an outbound message targeting mg-2 (discord) — not the origin chat
+    const outDb = new Database(outboundDbPath('ag-1', session.id));
+    outDb
+      .prepare(
+        `INSERT INTO messages_out (id, timestamp, kind, platform_id, channel_type, content)
+       VALUES (?, datetime('now'), 'chat', 'discord:456', 'discord', ?)`,
+      )
+      .run('out-unauth', JSON.stringify({ text: 'sneaky' }));
+    outDb.close();
+
+    const calls: string[] = [];
+    setDeliveryAdapter({
+      async deliver(_ct, _pid, _tid, _kind, content) {
+        calls.push(content);
+        return 'plat-msg';
+      },
+    });
+
+    // Deliver 3 times to exhaust retries
+    await deliverSessionMessages(session);
+    await deliverSessionMessages(session);
+    await deliverSessionMessages(session);
+
+    // Adapter never called — permission check throws before reaching it
+    expect(calls).toHaveLength(0);
+
+    // Message is marked as permanently failed
+    const inDb = openInboundDb('ag-1', session.id);
+    const delivered = getDeliveredIds(inDb);
+    inDb.close();
+    expect(delivered.has('out-unauth')).toBe(true);
+  });
+});

src/delivery.ts

@@ -239,6 +239,7 @@ async function deliverMessage(
     channel_type: string | null;
     thread_id: string | null;
     content: string;
+    in_reply_to: string | null;
   },
   session: Session,
   inDb: Database.Database,

src/host-core.test.ts

@@ -11,6 +11,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import {
   initTestDb,
   closeDb,
+  getDb,
   runMigrations,
   createAgentGroup,
   createMessagingGroup,
@@ -19,6 +20,7 @@ import {
 import {
   resolveSession,
   writeSessionMessage,
+  writeSessionRouting,
   initSessionFolder,
   sessionDir,
   inboundDbPath,
@@ -595,6 +597,400 @@ describe('router', () => {
   });
 });
 
+describe('routing metadata preservation', () => {
+  beforeEach(() => {
+    createAgentGroup({
+      id: 'ag-1',
+      name: 'Test Agent',
+      folder: 'test-agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+    createMessagingGroup({
+      id: 'mg-1',
+      channel_type: 'discord',
+      platform_id: 'chan-123',
+      name: 'General',
+      is_group: 1,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+    createMessagingGroupAgent({
+      id: 'mga-1',
+      messaging_group_id: 'mg-1',
+      agent_group_id: 'ag-1',
+      engage_mode: 'pattern',
+      engage_pattern: '.',
+      sender_scope: 'all',
+      ignored_message_policy: 'drop',
+      session_mode: 'shared',
+      priority: 0,
+      created_at: now(),
+    });
+  });
+
+  it('routed message carries platformId, channelType, threadId on the messages_in row', async () => {
+    const { routeInbound } = await import('./router.js');
+
+    await routeInbound({
+      channelType: 'discord',
+      platformId: 'chan-123',
+      threadId: 'thread-42',
+      message: { id: 'msg-r1', kind: 'chat', content: JSON.stringify({ sender: 'A', text: 'hi' }), timestamp: now() },
+    });
+
+    const session = findSession('mg-1', null);
+    const db = new Database(inboundDbPath('ag-1', session!.id));
+    const row = db
+      .prepare('SELECT platform_id, channel_type, thread_id FROM messages_in WHERE id LIKE ?')
+      .get('msg-r1%') as {
+      platform_id: string | null;
+      channel_type: string | null;
+      thread_id: string | null;
+    };
+    db.close();
+
+    expect(row.platform_id).toBe('chan-123');
+    expect(row.channel_type).toBe('discord');
+    expect(row.thread_id).toBe('thread-42');
+  });
+
+  it('fan-out gives each agent its own routing, not leaked from sibling', async () => {
+    const { routeInbound } = await import('./router.js');
+
+    createAgentGroup({
+      id: 'ag-2',
+      name: 'Agent Two',
+      folder: 'agent-two',
+      agent_provider: null,
+      created_at: now(),
+    });
+    createMessagingGroupAgent({
+      id: 'mga-2',
+      messaging_group_id: 'mg-1',
+      agent_group_id: 'ag-2',
+      engage_mode: 'pattern',
+      engage_pattern: '.',
+      sender_scope: 'all',
+      ignored_message_policy: 'drop',
+      session_mode: 'shared',
+      priority: 0,
+      created_at: now(),
+    });
+
+    await routeInbound({
+      channelType: 'discord',
+      platformId: 'chan-123',
+      threadId: 'thread-fanout',
+      message: { id: 'msg-fo', kind: 'chat', content: JSON.stringify({ text: 'fan' }), timestamp: now() },
+    });
+
+    // Both agents should have the message with correct routing
+    const { getSessionsByAgentGroup } = await import('./db/sessions.js');
+    for (const agId of ['ag-1', 'ag-2']) {
+      const sessions = getSessionsByAgentGroup(agId);
+      expect(sessions).toHaveLength(1);
+      const db = new Database(inboundDbPath(agId, sessions[0].id));
+      const row = db.prepare('SELECT platform_id, channel_type, thread_id FROM messages_in LIMIT 1').get() as {
+        platform_id: string | null;
+        channel_type: string | null;
+        thread_id: string | null;
+      };
+      db.close();
+      expect(row.platform_id).toBe('chan-123');
+      expect(row.channel_type).toBe('discord');
+      expect(row.thread_id).toBe('thread-fanout');
+    }
+  });
+});
+
+describe('writeSessionRouting', () => {
+  it('populates session_routing from the messaging group', () => {
+    createAgentGroup({
+      id: 'ag-1',
+      name: 'Agent',
+      folder: 'agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+    createMessagingGroup({
+      id: 'mg-1',
+      channel_type: 'telegram',
+      platform_id: 'tg:12345',
+      name: 'Chat',
+      is_group: 0,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+
+    const { session } = resolveSession('ag-1', 'mg-1', null, 'shared');
+    writeSessionRouting('ag-1', session.id);
+
+    const db = new Database(inboundDbPath('ag-1', session.id));
+    const row = db.prepare('SELECT channel_type, platform_id, thread_id FROM session_routing WHERE id = 1').get() as
+      | {
+          channel_type: string | null;
+          platform_id: string | null;
+          thread_id: string | null;
+        }
+      | undefined;
+    db.close();
+
+    expect(row).toBeDefined();
+    expect(row!.channel_type).toBe('telegram');
+    expect(row!.platform_id).toBe('tg:12345');
+    expect(row!.thread_id).toBeNull();
+  });
+
+  it('writes null routing for agent-shared session (no messaging group)', () => {
+    createAgentGroup({
+      id: 'ag-1',
+      name: 'Agent',
+      folder: 'agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+
+    const { session } = resolveSession('ag-1', null, null, 'agent-shared');
+    writeSessionRouting('ag-1', session.id);
+
+    const db = new Database(inboundDbPath('ag-1', session.id));
+    const row = db.prepare('SELECT channel_type, platform_id, thread_id FROM session_routing WHERE id = 1').get() as
+      | {
+          channel_type: string | null;
+          platform_id: string | null;
+          thread_id: string | null;
+        }
+      | undefined;
+    db.close();
+
+    expect(row).toBeDefined();
+    expect(row!.channel_type).toBeNull();
+    expect(row!.platform_id).toBeNull();
+    expect(row!.thread_id).toBeNull();
+  });
+
+  it('includes thread_id from per-thread session', () => {
+    createAgentGroup({
+      id: 'ag-1',
+      name: 'Agent',
+      folder: 'agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+    createMessagingGroup({
+      id: 'mg-1',
+      channel_type: 'discord',
+      platform_id: 'chan-123',
+      name: 'General',
+      is_group: 1,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+
+    const { session } = resolveSession('ag-1', 'mg-1', 'thread-77', 'per-thread');
+    writeSessionRouting('ag-1', session.id);
+
+    const db = new Database(inboundDbPath('ag-1', session.id));
+    const row = db.prepare('SELECT channel_type, platform_id, thread_id FROM session_routing WHERE id = 1').get() as
+      | {
+          channel_type: string | null;
+          platform_id: string | null;
+          thread_id: string | null;
+        }
+      | undefined;
+    db.close();
+
+    expect(row).toBeDefined();
+    expect(row!.channel_type).toBe('discord');
+    expect(row!.platform_id).toBe('chan-123');
+    expect(row!.thread_id).toBe('thread-77');
+  });
+});
+
+describe('agent-shared session resolution', () => {
+  it('resolves to the same session on repeated calls', () => {
+    createAgentGroup({
+      id: 'ag-1',
+      name: 'Agent',
+      folder: 'agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+
+    const { session: s1, created: c1 } = resolveSession('ag-1', null, null, 'agent-shared');
+    const { session: s2, created: c2 } = resolveSession('ag-1', null, null, 'agent-shared');
+
+    expect(c1).toBe(true);
+    expect(c2).toBe(false);
+    expect(s1.id).toBe(s2.id);
+  });
+
+  it('agent-shared session has null messaging_group_id', () => {
+    createAgentGroup({
+      id: 'ag-1',
+      name: 'Agent',
+      folder: 'agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+
+    const { session } = resolveSession('ag-1', null, null, 'agent-shared');
+    expect(session.messaging_group_id).toBeNull();
+  });
+});
+
+describe('agent-to-agent routing', () => {
+  beforeEach(() => {
+    createAgentGroup({
+      id: 'ag-pa',
+      name: 'PA',
+      folder: 'pa-agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+    createMessagingGroup({
+      id: 'mg-slack',
+      channel_type: 'slack',
+      platform_id: 'C-GENERAL',
+      name: 'Slack General',
+      is_group: 1,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+    createAgentGroup({
+      id: 'ag-researcher',
+      name: 'Researcher',
+      folder: 'researcher-agent',
+      agent_provider: null,
+      created_at: now(),
+    });
+
+    // Wire bidirectional A2A destinations (table created by runMigrations)
+    const db = getDb();
+    db.prepare(
+      `INSERT OR IGNORE INTO agent_destinations (agent_group_id, local_name, target_type, target_id, created_at)
+       VALUES ('ag-pa', 'researcher', 'agent', 'ag-researcher', ?)`,
+    ).run(now());
+    db.prepare(
+      `INSERT OR IGNORE INTO agent_destinations (agent_group_id, local_name, target_type, target_id, created_at)
+       VALUES ('ag-researcher', 'pa', 'agent', 'ag-pa', ?)`,
+    ).run(now());
+  });
+
+  it('A2A outbound lands in a session for the target agent', async () => {
+    const { routeAgentMessage } = await import('./modules/agent-to-agent/agent-route.js');
+
+    const { session: paSlackSession } = resolveSession('ag-pa', 'mg-slack', null, 'shared');
+
+    await routeAgentMessage(
+      {
+        id: 'out-a2a-1',
+        platform_id: 'ag-researcher',
+        content: JSON.stringify({ text: 'research this' }),
+        in_reply_to: null,
+      },
+      paSlackSession,
+    );
+
+    const { getSessionsByAgentGroup } = await import('./db/sessions.js');
+    const researcherSessions = getSessionsByAgentGroup('ag-researcher');
+    expect(researcherSessions.length).toBeGreaterThanOrEqual(1);
+
+    const rDb = new Database(inboundDbPath('ag-researcher', researcherSessions[0].id));
+    const rows = rDb.prepare('SELECT platform_id, channel_type, content FROM messages_in').all() as Array<{
+      platform_id: string | null;
+      channel_type: string | null;
+      content: string;
+    }>;
+    rDb.close();
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0].channel_type).toBe('agent');
+    expect(rows[0].platform_id).toBe('ag-pa');
+    expect(JSON.parse(rows[0].content).text).toBe('research this');
+  });
+
+  it('A2A return path routes to originating session, not newest (#2332)', async () => {
+    // PA has Slack session, then gets wired to Discord (newer session).
+    // Researcher responds to PA. With the return-path fix, the reply
+    // routes back to the Slack session (originator) not Discord (newest).
+    const { routeAgentMessage } = await import('./modules/agent-to-agent/agent-route.js');
+
+    const { session: paSlackSession } = resolveSession('ag-pa', 'mg-slack', null, 'shared');
+
+    createMessagingGroup({
+      id: 'mg-discord',
+      channel_type: 'discord',
+      platform_id: 'chan-discord',
+      name: 'Discord',
+      is_group: 0,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+    const { session: paDiscordSession } = resolveSession('ag-pa', 'mg-discord', null, 'shared');
+
+    // PA sends from Slack
+    await routeAgentMessage(
+      { id: 'out-fwd', platform_id: 'ag-researcher', content: JSON.stringify({ text: 'research' }), in_reply_to: null },
+      paSlackSession,
+    );
+
+    // Researcher responds back to PA
+    const { getSessionsByAgentGroup } = await import('./db/sessions.js');
+    const researcherSession = getSessionsByAgentGroup('ag-researcher')[0];
+
+    await routeAgentMessage(
+      { id: 'out-reply', platform_id: 'ag-pa', content: JSON.stringify({ text: 'found it' }), in_reply_to: null },
+      researcherSession,
+    );
+
+    const slackDb = new Database(inboundDbPath('ag-pa', paSlackSession.id));
+    const slackA2a = slackDb.prepare("SELECT * FROM messages_in WHERE channel_type = 'agent'").all();
+    slackDb.close();
+
+    const discordDb = new Database(inboundDbPath('ag-pa', paDiscordSession.id));
+    const discordA2a = discordDb.prepare("SELECT * FROM messages_in WHERE channel_type = 'agent'").all();
+    discordDb.close();
+
+    // Fixed: response lands in Slack (origin) not Discord (newest)
+    expect(slackA2a).toHaveLength(1);
+    expect(discordA2a).toHaveLength(0);
+  });
+
+  it('BUG: A2A-only session gets null session_routing (#2332)', async () => {
+    // Researcher only has an agent-shared session (no channel wiring).
+    // writeSessionRouting writes nulls because messaging_group_id is null.
+    const { routeAgentMessage } = await import('./modules/agent-to-agent/agent-route.js');
+
+    const { session: paSession } = resolveSession('ag-pa', 'mg-slack', null, 'shared');
+    await routeAgentMessage(
+      { id: 'out-1', platform_id: 'ag-researcher', content: JSON.stringify({ text: 'go' }), in_reply_to: null },
+      paSession,
+    );
+
+    const { getSessionsByAgentGroup } = await import('./db/sessions.js');
+    const researcherSessions = getSessionsByAgentGroup('ag-researcher');
+    expect(researcherSessions).toHaveLength(1);
+
+    writeSessionRouting('ag-researcher', researcherSessions[0].id);
+
+    const rDb = new Database(inboundDbPath('ag-researcher', researcherSessions[0].id));
+    const routing = rDb.prepare('SELECT channel_type, platform_id FROM session_routing WHERE id = 1').get() as
+      | {
+          channel_type: string | null;
+          platform_id: string | null;
+        }
+      | undefined;
+    rDb.close();
+
+    // BUG: session_routing is all null — researcher has no default routing
+    expect(routing).toBeDefined();
+    expect(routing!.channel_type).toBeNull();
+    expect(routing!.platform_id).toBeNull();
+  });
+});
+
 describe('delivery', () => {
   it('should detect undelivered messages in outbound DB', () => {
     createAgentGroup({

src/index.ts

@@ -53,6 +53,12 @@ import './channels/index.js';
 // append registry-based modules. Imported for side effects (registrations).
 import './modules/index.js';
 
+// CLI command barrel — populates the `ncl` registry before the CLI server
+// accepts connections.
+import './cli/commands/index.js';
+import './cli/delivery-action.js';
+import { startCliServer, stopCliServer } from './cli/socket-server.js';
+
 import type { ChannelAdapter, ChannelSetup } from './channels/adapter.js';
 import { initChannelAdapters, teardownChannelAdapters, getChannelAdapter } from './channels/channel-registry.js';
 
@@ -163,6 +169,9 @@ async function main(): Promise<void> {
   startHostSweep();
   log.info('Host sweep started');
 
+  // 7. Start the `ncl` CLI socket server (data/ncl.sock).
+  await startCliServer();
+
   log.info('NanoClaw running');
 }
 
@@ -178,6 +187,7 @@ async function shutdown(signal: string): Promise<void> {
   }
   stopDeliveryPolls();
   stopHostSweep();
+  await stopCliServer();
   try {
     await teardownChannelAdapters();
   } finally {

src/modules/agent-to-agent/agent-route.test.ts

@@ -1,20 +1,54 @@
-import { describe, expect, it } from 'vitest';
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
 
-import { isSafeAttachmentName } from './agent-route.js';
+import { isSafeAttachmentName, routeAgentMessage } from './agent-route.js';
+import { createDestination } from './db/agent-destinations.js';
+import { initTestDb, closeDb, runMigrations, createAgentGroup } from '../../db/index.js';
+import { createSession, updateSession } from '../../db/sessions.js';
+import { initSessionFolder, inboundDbPath, sessionDir, writeSessionMessage } from '../../session-manager.js';
+import type { Session } from '../../types.js';
+
+vi.mock('../../container-runner.js', () => ({
+  wakeContainer: vi.fn().mockResolvedValue(undefined),
+  isContainerRunning: vi.fn().mockReturnValue(false),
+  getActiveContainerCount: vi.fn().mockReturnValue(0),
+  killContainer: vi.fn(),
+}));
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/nanoclaw-test-a2a-route' };
+});
+
+const TEST_DIR = '/tmp/nanoclaw-test-a2a-route';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function readInbound(agentGroupId: string, sessionId: string) {
+  const db = new Database(inboundDbPath(agentGroupId, sessionId), { readonly: true });
+  const rows = db
+    .prepare('SELECT id, platform_id, channel_type, content, source_session_id FROM messages_in ORDER BY seq')
+    .all() as Array<{
+    id: string;
+    platform_id: string | null;
+    channel_type: string | null;
+    content: string;
+    source_session_id: string | null;
+  }>;
+  db.close();
+  return rows;
+}
 
-/**
- * `forwardAttachedFiles` has a filesystem side that's awkward to unit-test
- * without mocking DATA_DIR. The guarantee worth pinning is that the
- * filename validator rejects everything that could escape the inbox dir —
- * `forwardAttachedFiles` runs this guard before any I/O, so traversal is
- * impossible as long as this matrix holds.
- */
 describe('isSafeAttachmentName', () => {
   it('accepts plain filenames', () => {
     expect(isSafeAttachmentName('baby-duck.png')).toBe(true);
     expect(isSafeAttachmentName('file with spaces.pdf')).toBe(true);
     expect(isSafeAttachmentName('report.v2.docx')).toBe(true);
-    expect(isSafeAttachmentName('.hidden')).toBe(true); // leading dot is fine, just not `.` / `..`
+    expect(isSafeAttachmentName('.hidden')).toBe(true);
   });
 
   it('rejects empty / sentinel values', () => {
@@ -44,3 +78,369 @@ describe('isSafeAttachmentName', () => {
     expect(isSafeAttachmentName(undefined as unknown as string)).toBe(false);
   });
 });
+
+/**
+ * Return-path routing: when an a2a reply targets an agent group with multiple
+ * sessions, it must land in the *originating* session — not the newest one.
+ *
+ * Setup: agent A has two active sessions S1 (older) + S2 (newer).
+ * Agent B is the peer A talks to. Bidirectional destinations wired.
+ */
+describe('routeAgentMessage return-path', () => {
+  const A = 'ag-A';
+  const B = 'ag-B';
+  let S1: Session;
+  let S2: Session;
+  let SB: Session;
+
+  beforeEach(() => {
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+
+    const db = initTestDb();
+    runMigrations(db);
+
+    createAgentGroup({ id: A, name: 'A', folder: 'a', agent_provider: null, created_at: now() });
+    createAgentGroup({ id: B, name: 'B', folder: 'b', agent_provider: null, created_at: now() });
+
+    // S1 (older), S2 (newer) — both active sessions on A.
+    S1 = {
+      id: 'sess-A-old',
+      agent_group_id: A,
+      messaging_group_id: null,
+      thread_id: null,
+      agent_provider: null,
+      status: 'active',
+      container_status: 'stopped',
+      last_active: null,
+      created_at: '2026-01-01T00:00:00.000Z',
+    };
+    S2 = {
+      id: 'sess-A-new',
+      agent_group_id: A,
+      messaging_group_id: null,
+      thread_id: null,
+      agent_provider: null,
+      status: 'active',
+      container_status: 'stopped',
+      last_active: null,
+      created_at: '2026-02-01T00:00:00.000Z',
+    };
+    SB = {
+      id: 'sess-B',
+      agent_group_id: B,
+      messaging_group_id: null,
+      thread_id: null,
+      agent_provider: null,
+      status: 'active',
+      container_status: 'stopped',
+      last_active: null,
+      created_at: '2026-01-15T00:00:00.000Z',
+    };
+    createSession(S1);
+    createSession(S2);
+    createSession(SB);
+    initSessionFolder(A, S1.id);
+    initSessionFolder(A, S2.id);
+    initSessionFolder(B, SB.id);
+
+    createDestination({
+      agent_group_id: A,
+      local_name: 'b',
+      target_type: 'agent',
+      target_id: B,
+      created_at: now(),
+    });
+    createDestination({
+      agent_group_id: B,
+      local_name: 'a',
+      target_type: 'agent',
+      target_id: A,
+      created_at: now(),
+    });
+  });
+
+  afterEach(() => {
+    closeDb();
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  });
+
+  it('forward direction: stamps source_session_id on the target inbound row', async () => {
+    // A.S1 emits an outbound a2a to B.
+    await routeAgentMessage(
+      {
+        id: 'msg-from-A-S1',
+        platform_id: B,
+        content: JSON.stringify({ text: 'hello B' }),
+        in_reply_to: null,
+      },
+      S1,
+    );
+
+    const bRows = readInbound(B, SB.id);
+    expect(bRows).toHaveLength(1);
+    expect(bRows[0].platform_id).toBe(A);
+    expect(bRows[0].source_session_id).toBe(S1.id); // <- the return address
+  });
+
+  it('reply direction: routes back to the originating session, not the newest', async () => {
+    // A.S1 sends to B.
+    await routeAgentMessage(
+      {
+        id: 'msg-from-A-S1',
+        platform_id: B,
+        content: JSON.stringify({ text: 'ping' }),
+        in_reply_to: null,
+      },
+      S1,
+    );
+
+    // Capture the synthetic id the host stamped on B's inbound — that's what
+    // B's container would reference as `in_reply_to` when replying.
+    const bRows = readInbound(B, SB.id);
+    const yId = bRows[0].id;
+
+    // B replies to that message.
+    await routeAgentMessage(
+      {
+        id: 'msg-from-B',
+        platform_id: A,
+        content: JSON.stringify({ text: 'pong' }),
+        in_reply_to: yId,
+      },
+      SB,
+    );
+
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+
+    // The reply lands in S1 (originator) even though S2 is newer.
+    expect(s1Rows).toHaveLength(1);
+    expect(s1Rows[0].platform_id).toBe(B);
+    expect(JSON.parse(s1Rows[0].content).text).toBe('pong');
+    expect(s2Rows).toHaveLength(0);
+  });
+
+  it('fallback: a2a with no in_reply_to falls through to newest-session lookup', async () => {
+    // No prior conversation. B initiates an a2a to A out of the blue.
+    await routeAgentMessage(
+      {
+        id: 'msg-from-B-fresh',
+        platform_id: A,
+        content: JSON.stringify({ text: 'unsolicited' }),
+        in_reply_to: null,
+      },
+      SB,
+    );
+
+    // Newest session wins (current heuristic, preserved).
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+    expect(s1Rows).toHaveLength(0);
+    expect(s2Rows).toHaveLength(1);
+  });
+
+  it('peer-affinity fallback: with no in_reply_to, routes to most recent peer-source session', async () => {
+    // A.S1 sends to B (establishing affinity: B's last contact from A was via S1).
+    await routeAgentMessage(
+      {
+        id: 'msg-from-A-S1-pre',
+        platform_id: B,
+        content: JSON.stringify({ text: 'context-establishing' }),
+        in_reply_to: null,
+      },
+      S1,
+    );
+
+    // B sends a follow-up but its container forgot to set in_reply_to (e.g.
+    // emitted via an MCP tool path that doesn't thread the batch's in_reply_to
+    // through). The host should still route this to S1 because S1 is the
+    // session most recently in conversation with B — not the chronologically
+    // newest session of A.
+    await routeAgentMessage(
+      {
+        id: 'msg-from-B-followup',
+        platform_id: A,
+        content: JSON.stringify({ text: 'standing by' }),
+        in_reply_to: null,
+      },
+      SB,
+    );
+
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+    // Affinity wins: reply to S1, not the newer S2.
+    expect(s1Rows).toHaveLength(1);
+    expect(JSON.parse(s1Rows[0].content).text).toBe('standing by');
+    expect(s2Rows).toHaveLength(0);
+  });
+
+  it('stale origin fallback: closed origin session falls through to newest active', async () => {
+    // A.S1 sends to B, establishing source_session_id = S1.id on B's inbound.
+    await routeAgentMessage(
+      { id: 'msg-fwd', platform_id: B, content: JSON.stringify({ text: 'hello' }), in_reply_to: null },
+      S1,
+    );
+    const bRows = readInbound(B, SB.id);
+    const inboundId = bRows[0].id;
+
+    // Close S1 — simulates session cleanup or channel disconnect.
+    updateSession(S1.id, { status: 'closed' });
+
+    // B replies. origin points to S1 (closed), should fall through to S2.
+    await routeAgentMessage(
+      { id: 'msg-reply-stale', platform_id: A, content: JSON.stringify({ text: 'reply' }), in_reply_to: inboundId },
+      SB,
+    );
+
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+    expect(s1Rows).toHaveLength(0);
+    expect(s2Rows).toHaveLength(1);
+  });
+
+  it('cross-agent-group guard: origin session belonging to wrong agent group is rejected', async () => {
+    // Third agent group C sends to B, stamping source_session_id = SC on B's inbound.
+    const C = 'ag-C';
+    createAgentGroup({ id: C, name: 'C', folder: 'c', agent_provider: null, created_at: now() });
+    const SC: Session = {
+      id: 'sess-C',
+      agent_group_id: C,
+      messaging_group_id: null,
+      thread_id: null,
+      agent_provider: null,
+      status: 'active',
+      container_status: 'stopped',
+      last_active: null,
+      created_at: '2026-03-01T00:00:00.000Z',
+    };
+    createSession(SC);
+    initSessionFolder(C, SC.id);
+    createDestination({ agent_group_id: C, local_name: 'b', target_type: 'agent', target_id: B, created_at: now() });
+
+    await routeAgentMessage(
+      { id: 'msg-from-C', platform_id: B, content: JSON.stringify({ text: 'from C' }), in_reply_to: null },
+      SC,
+    );
+    const bRows = readInbound(B, SB.id);
+    const cInboundId = bRows.find((r) => r.platform_id === C)!.id;
+
+    // B replies to A, but in_reply_to references the C-originated row.
+    // Guard rejects (SC belongs to C, not A) → falls through to newest of A.
+    await routeAgentMessage(
+      {
+        id: 'msg-reply-tamper',
+        platform_id: A,
+        content: JSON.stringify({ text: 'misdirected' }),
+        in_reply_to: cInboundId,
+      },
+      SB,
+    );
+
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+    expect(s1Rows).toHaveLength(0);
+    expect(s2Rows).toHaveLength(1);
+  });
+
+  it('in_reply_to referencing a non-a2a row falls through to newest session', async () => {
+    // Write a channel message into B's inbound (no source_session_id).
+    writeSessionMessage(B, SB.id, {
+      id: 'channel-msg-1',
+      kind: 'chat',
+      timestamp: now(),
+      platformId: 'user-123',
+      channelType: 'slack',
+      threadId: null,
+      content: 'hello from slack',
+    });
+
+    // B replies to A with in_reply_to pointing to the channel message.
+    // source_session_id is null → peer-affinity finds nothing → newest of A.
+    await routeAgentMessage(
+      {
+        id: 'msg-reply-channel',
+        platform_id: A,
+        content: JSON.stringify({ text: 'response' }),
+        in_reply_to: 'channel-msg-1',
+      },
+      SB,
+    );
+
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+    expect(s1Rows).toHaveLength(0);
+    expect(s2Rows).toHaveLength(1);
+  });
+
+  it('self-message is allowed without a destination row', async () => {
+    // A targets itself — no agent_destinations row exists for A→A.
+    await routeAgentMessage(
+      { id: 'self-msg', platform_id: A, content: JSON.stringify({ text: 'self-note' }), in_reply_to: null },
+      S1,
+    );
+
+    // Lands in S2 (newest active session of A via resolveSession fallback).
+    const s2Rows = readInbound(A, S2.id);
+    expect(s2Rows).toHaveLength(1);
+    expect(JSON.parse(s2Rows[0].content).text).toBe('self-note');
+  });
+
+  it('BUG: no volume cap on a2a routing — unbounded ping-pong is allowed (#2063)', async () => {
+    // Two agents can exchange unlimited messages with no rate limit or loop
+    // detection. This test documents the gap — it should FAIL once #2063 lands.
+    const errors: string[] = [];
+    for (let i = 0; i < 20; i++) {
+      try {
+        await routeAgentMessage(
+          { id: `ping-${i}`, platform_id: B, content: JSON.stringify({ text: `ping ${i}` }), in_reply_to: null },
+          S1,
+        );
+        await routeAgentMessage(
+          { id: `pong-${i}`, platform_id: A, content: JSON.stringify({ text: `pong ${i}` }), in_reply_to: null },
+          SB,
+        );
+      } catch (e) {
+        errors.push((e as Error).message);
+        break;
+      }
+    }
+    // BUG: all 40 messages go through — no cap, no throttle.
+    // Once loop prevention lands, this should throw or reject after a threshold.
+    const bRows = readInbound(B, SB.id);
+    const s1Rows = readInbound(A, S1.id);
+    const s2Rows = readInbound(A, S2.id);
+    expect(errors).toHaveLength(0);
+    expect(bRows).toHaveLength(20);
+    expect(s1Rows.length + s2Rows.length).toBe(20);
+  });
+
+  it('file forwarding: copies bytes from source outbox to target inbox', async () => {
+    // Place a file in S1's outbox for the message.
+    const outboxDir = path.join(sessionDir(A, S1.id), 'outbox', 'msg-with-file');
+    fs.mkdirSync(outboxDir, { recursive: true });
+    fs.writeFileSync(path.join(outboxDir, 'report.pdf'), 'fake-pdf-bytes');
+
+    await routeAgentMessage(
+      {
+        id: 'msg-with-file',
+        platform_id: B,
+        content: JSON.stringify({ text: 'see attached', files: ['report.pdf'] }),
+        in_reply_to: null,
+      },
+      S1,
+    );
+
+    const bRows = readInbound(B, SB.id);
+    expect(bRows).toHaveLength(1);
+    const parsed = JSON.parse(bRows[0].content);
+    expect(parsed.attachments).toHaveLength(1);
+    expect(parsed.attachments[0].name).toBe('report.pdf');
+    expect(parsed.attachments[0].type).toBe('file');
+
+    // Verify actual file bytes were copied to the target inbox.
+    const targetPath = path.join(sessionDir(B, SB.id), parsed.attachments[0].localPath);
+    expect(fs.existsSync(targetPath)).toBe(true);
+    expect(fs.readFileSync(targetPath, 'utf-8')).toBe('fake-pdf-bytes');
+  });
+});

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

@@ -23,10 +23,11 @@ import path from 'path';
 
 import { isSafeAttachmentName } from '../../attachment-safety.js';
 import { getAgentGroup } from '../../db/agent-groups.js';
+import { getInboundSourceSessionId, getMostRecentPeerSourceSessionId } from '../../db/session-db.js';
 import { getSession } from '../../db/sessions.js';
 import { wakeContainer } from '../../container-runner.js';
 import { log } from '../../log.js';
-import { resolveSession, sessionDir, writeSessionMessage } from '../../session-manager.js';
+import { openInboundDb, resolveSession, sessionDir, writeSessionMessage } from '../../session-manager.js';
 import type { Session } from '../../types.js';
 import { hasDestination } from './db/agent-destinations.js';
 
@@ -101,6 +102,61 @@ export interface RoutableAgentMessage {
   id: string;
   platform_id: string | null;
   content: string;
+  /**
+   * For replies, the id of the inbound message being replied to. The
+   * container's formatter sets this from the first inbound in the batch
+   * (`container/agent-runner/src/formatter.ts`). Used here to route the
+   * reply back to the originating session — see `resolveTargetSession`.
+   */
+  in_reply_to: string | null;
+}
+
+/**
+ * Pick which session of `targetAgentGroupId` should receive this a2a message.
+ *
+ * Three layers, highest-fidelity first:
+ *
+ * 1. **Direct return-path** (in_reply_to lookup): if the message is a reply
+ *    (`in_reply_to` set), open the source agent's inbound DB and read the
+ *    triggering row's `source_session_id`. That column was stamped when the
+ *    original outbound was routed — it's the session that started the
+ *    conversation, and replies should land there even when the target has
+ *    multiple active sessions.
+ *
+ * 2. **Peer-affinity fallback**: if (1) misses (in_reply_to is null or the
+ *    referenced row isn't an a2a inbound), look up the most recent a2a
+ *    inbound *from the target agent group* in source's inbound and use its
+ *    `source_session_id`. The intuition: the last time this peer talked to
+ *    me, which target session was driving? Route the reply there, since
+ *    that's the session most plausibly in active conversation.
+ *
+ * 3. **Newest active session**: legacy heuristic. Used when no prior a2a
+ *    has been recorded with `source_session_id` (e.g. fresh installs,
+ *    pre-migration data).
+ */
+function resolveTargetSession(msg: RoutableAgentMessage, sourceSession: Session, targetAgentGroupId: string): Session {
+  const srcDb = openInboundDb(sourceSession.agent_group_id, sourceSession.id);
+  let originSessionId: string | null = null;
+  try {
+    if (msg.in_reply_to) {
+      originSessionId = getInboundSourceSessionId(srcDb, msg.in_reply_to);
+    }
+    if (!originSessionId) {
+      // Peer-affinity fallback — covers the case where the container's
+      // outbound write didn't carry in_reply_to (e.g. legacy MCP send_message
+      // path, container running pre-fix code).
+      originSessionId = getMostRecentPeerSourceSessionId(srcDb, targetAgentGroupId);
+    }
+  } finally {
+    srcDb.close();
+  }
+  if (originSessionId) {
+    const candidate = getSession(originSessionId);
+    if (candidate && candidate.agent_group_id === targetAgentGroupId && candidate.status === 'active') {
+      return candidate;
+    }
+  }
+  return resolveSession(targetAgentGroupId, null, null, 'agent-shared').session;
 }
 
 export async function routeAgentMessage(msg: RoutableAgentMessage, session: Session): Promise<void> {
@@ -119,7 +175,7 @@ export async function routeAgentMessage(msg: RoutableAgentMessage, session: Sess
   if (!getAgentGroup(targetAgentGroupId)) {
     throw new Error(`target agent group ${targetAgentGroupId} not found for message ${msg.id}`);
   }
-  const { session: targetSession } = resolveSession(targetAgentGroupId, null, null, 'agent-shared');
+  const targetSession = resolveTargetSession(msg, session, targetAgentGroupId);
   const a2aMsgId = `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
   // If the source message references files (via `send_file`), forward the
@@ -137,6 +193,7 @@ export async function routeAgentMessage(msg: RoutableAgentMessage, session: Sess
     channelType: 'agent',
     threadId: null,
     content: forwardedContent,
+    sourceSessionId: session.id,
   });
   log.info('Agent message routed', {
     from: session.agent_group_id,

src/session-manager.ts

@@ -210,6 +210,12 @@ export function writeSessionMessage(
      * a trigger-1 message does arrive.
      */
     trigger?: 0 | 1;
+    /**
+     * For agent-to-agent inbound: the source session id that emitted the
+     * outbound message which became this inbound row. Used as the return
+     * path so the target's reply routes back to that exact session.
+     */
+    sourceSessionId?: string | null;
   },
 ): void {
   // Extract base64 attachment data, save to inbox, replace with file paths
@@ -228,6 +234,7 @@ export function writeSessionMessage(
       processAfter: message.processAfter ?? null,
       recurrence: message.recurrence ?? null,
       trigger: message.trigger ?? 1,
+      sourceSessionId: message.sourceSessionId ?? null,
     });
   } finally {
     db.close();