Merge pull request #2536 from glifocat/docs/v2.0.64-release-notes

docs(changelog): add v2.0.64 entry
2026-06-04 10:14:47 +08:00 · 2026-05-18 18:55:06 +02:00 · 2026-05-18 12:56:51 +02:00 · 2026-05-17 11:50:33 +00:00 · 2026-05-17 14:50:20 +03:00 · 2026-05-16 10:49:16 +02:00
150 changed files with 6936 additions and 615 deletions
@@ -182,9 +182,12 @@ ATOMIC_CHAT_API_KEY=sk-...

 ### Restart the service

+Run from your NanoClaw project root:
+
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 ## Phase 4: Verify
@@ -93,10 +93,13 @@ Generate the secret: `node -e "console.log('nc-' + require('crypto').randomBytes

 ### 6. Build and restart

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-systemctl --user restart nanoclaw   # Linux
-# or: launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
+# or: launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
 ```

 ### 7. Verify
@@ -23,14 +23,17 @@ DC_SMTP_PORT

 ## 3. Rebuild and restart

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
+source setup/lib/install-slug.sh

 # Linux
-systemctl --user restart nanoclaw
+systemctl --user restart $(systemd_unit)

 # macOS
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)
 ```

 ## 4. Remove account data (optional)
@@ -98,12 +98,16 @@ The `/set-avatar` command (send an image with that caption) is the easiest way t

 ### Restart

+Run from your NanoClaw project root:
+
 ```bash
+source setup/lib/install-slug.sh
+
 # Linux
-systemctl --user restart nanoclaw
+systemctl --user restart $(systemd_unit)

 # macOS
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)
 ```

 On first start the adapter configures the email account (IMAP/SMTP credentials, calls `configure()`). Subsequent starts skip straight to `startIo()`. Account data is stored in `dc-account/` in the project root (or your `DC_ACCOUNT_DIR`).
@@ -232,7 +236,7 @@ Set `DC_SMTP_SECURITY=1` and `DC_SMTP_PORT=465` in `.env`, then restart.

 ```bash
 rm -f dc-account/accounts.lock
-systemctl --user restart nanoclaw
+systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"
 ```

 ### Bot not responding after restart
@@ -162,10 +162,13 @@ If you changed `EMACS_CHANNEL_PORT` from the default:

 ## Restart NanoClaw

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
-# systemctl --user restart nanoclaw                # Linux
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
+# systemctl --user restart $(systemd_unit)             # Linux
 ```

 ## Verify
@@ -240,7 +243,7 @@ grep -q "import './emacs.js'" src/channels/index.ts && echo "imported" || echo "

 ### No response from agent

-1. NanoClaw running: `launchctl list | grep nanoclaw` (macOS) / `systemctl --user status nanoclaw` (Linux)
+1. NanoClaw running: `launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) / `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (Linux)
 2. Messaging group wired: `pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id, ag.folder FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id JOIN agent_groups ag ON ag.id = mga.agent_group_id WHERE mg.channel_type = 'emacs'"`
 3. Logs show inbound: `grep 'channel_type=emacs\|Emacs' logs/nanoclaw.log | tail -20`

@@ -282,13 +285,16 @@ If an agent outputs org-mode directly, markers get double-converted and render i

 ## Removal

+Run from your NanoClaw project root:
+
 ```bash
 rm src/channels/emacs.ts src/channels/emacs.test.ts emacs/nanoclaw.el
 # Remove the `import './emacs.js';` line from src/channels/index.ts
 # Remove EMACS_* lines from .env
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
-# systemctl --user restart nanoclaw                # Linux
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # macOS
+# systemctl --user restart $(systemd_unit)             # Linux

 # Remove the NanoClaw block from your Emacs config
 # Optionally clean up the messaging group:
@@ -92,7 +92,6 @@ onecli agents list

 ```bash
 grep -q 'CALENDAR_MCP_VERSION' container/Dockerfile && \
-grep -q "mcp__calendar__\*" container/agent-runner/src/providers/claude.ts && \
 echo "ALREADY APPLIED — skip to Phase 3"
 ```

@@ -121,9 +120,7 @@ RUN --mount=type=cache,target=/root/.cache/pnpm \
    pnpm install -g "@cocal/google-calendar-mcp@${CALENDAR_MCP_VERSION}"
 ```

-### Add tools to allowlist
-
-Edit `container/agent-runner/src/providers/claude.ts`. Add `'mcp__calendar__*'` to `TOOL_ALLOWLIST` after `'mcp__nanoclaw__*'` (or after `'mcp__gmail__*'` if present).
+**No `TOOL_ALLOWLIST` edit needed.** `container/agent-runner/src/providers/claude.ts` derives the allow-pattern dynamically from each group's `mcpServers` map (`Object.keys(this.mcpServers).map(mcpAllowPattern)`), so registering `calendar` in Phase 3 automatically allows `mcp__calendar__*`. Earlier versions of this skill instructed a static `TOOL_ALLOWLIST` edit — that's now redundant.

 ### Rebuild the container image

@@ -133,40 +130,59 @@ Edit `container/agent-runner/src/providers/claude.ts`. Add `'mcp__calendar__*'`

 ## Phase 3: Wire Per-Agent-Group

-For each agent group, merge into `groups/<folder>/container.json`:
+For each agent group, persist two changes to the **central DB** (`data/v2.db`): the `mcpServers.calendar` entry and an `additionalMounts` entry for `.calendar-mcp`. Both flow through `materializeContainerJson` on every spawn, so editing `groups/<folder>/container.json` by hand does **not** stick — that file is regenerated from the DB.

-```jsonc
-{
-  "mcpServers": {
-    "calendar": {
-      "command": "google-calendar-mcp",
-      "args": [],
-      "env": {
-        "GOOGLE_OAUTH_CREDENTIALS": "/workspace/extra/.calendar-mcp/gcp-oauth.keys.json",
-        "GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/workspace/extra/.calendar-mcp/credentials.json"
-      }
-    }
-  },
-  "additionalMounts": [
-    {
-      "hostPath": "/home/<user>/.calendar-mcp",
-      "containerPath": ".calendar-mcp",
-      "readonly": false
-    }
-  ]
-}
+### Register the MCP server
+
+For each chosen `<group-id>` (use `ncl groups list` to enumerate):
+
+```bash
+ncl groups config add-mcp-server \
+  --id <group-id> \
+  --name calendar \
+  --command google-calendar-mcp \
+  --args '[]' \
+  --env '{"GOOGLE_OAUTH_CREDENTIALS":"/workspace/extra/.calendar-mcp/gcp-oauth.keys.json","GOOGLE_CALENDAR_MCP_TOKEN_PATH":"/workspace/extra/.calendar-mcp/credentials.json"}'
 ```

-Substitute `<user>` with `echo $HOME`. `containerPath` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`).
+Approval behaviour depends on where you run it: from inside an agent's container `ncl` write verbs are approval-gated (admin approves before it lands); from a host operator shell with full scope, it executes immediately. Either way, the response tells you which path it took.

-**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, **merge, don't replace** — both entries coexist in `mcpServers` and `additionalMounts`.
+### Add the `.calendar-mcp` mount
+
+There is no `ncl groups config add-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until that ships, edit the DB directly via the in-tree wrapper (`scripts/q.ts` — `setup/verify.ts:5` codifies that NanoClaw avoids depending on the `sqlite3` CLI binary, so don't shell out to it):
+
+```bash
+GROUP_ID='<group-id>'
+HOST_PATH="$HOME/.calendar-mcp"
+MOUNT=$(jq -cn --arg h "$HOST_PATH" '{hostPath:$h, containerPath:".calendar-mcp", readonly:false}')
+pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+  SET additional_mounts = json_insert(additional_mounts, '\$[#]', json('$MOUNT')), \
+      updated_at = datetime('now') \
+  WHERE agent_group_id = '$GROUP_ID';"
+```
+
+Run from your NanoClaw project root (where `data/v2.db` lives). The `$[#]` placeholder is SQLite JSON1's append-to-end notation; it's `\$`-escaped so bash doesn't arithmetic-expand it before sqlite sees it. `updated_at` is ISO-string everywhere else in the schema, so use `datetime('now')` — not `strftime('%s','now')`, which would silently mix epoch ints into a column of YYYY-MM-DD HH:MM:SS strings.
+
+**Switch to `ncl groups config add-mount` once #2395 lands.** Update this skill at that time.
+
+`containerPath` is relative (mount-security rejects absolute paths — additional mounts land at `/workspace/extra/<relative>`).
+
+**Why this can't be `groups/<folder>/container.json`:** post-migration `014-container-configs`, `materializeContainerJson` in `src/container-config.ts` rewrites that file from the DB on every spawn. Anything hand-edited there is silently overwritten on next restart.
+
+**Same-group-as-gmail tip:** if this group already has the gmail MCP + `.gmail-mcp` mount, both coexist — `ncl groups config add-mcp-server` only updates the named entry, and `json_insert` appends to `additional_mounts` without disturbing existing entries.

 ## Phase 4: Build and Restart

 ```bash
 pnpm run build
-systemctl --user restart nanoclaw   # Linux
-# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 Kill any existing agent containers so they respawn with the new mcpServers config:
@@ -193,16 +209,28 @@ Common signals:
 - `command not found: google-calendar-mcp` → image not rebuilt.
 - `ENOENT ...credentials.json` → mount missing. Check the mount allowlist.
 - `401 Unauthorized` from `*.googleapis.com` → OneCLI isn't injecting; verify agent's secret mode and that Google Calendar is connected.
- Agent says "I don't have calendar tools" → `mcp__calendar__*` missing from `TOOL_ALLOWLIST`, or image cache stale (`./container/build.sh` again).
+- Agent says "I don't have calendar tools" → the `calendar` MCP server isn't registered in this group's `mcpServers` (re-run the `ncl groups config add-mcp-server` step in Phase 3 for that group and restart it), or the agent-runner image is stale (`./container/build.sh`, `--no-cache` if suspicious).

 ## Removal

-1. Delete `"calendar"` from `mcpServers` and the `.calendar-mcp` mount from `additionalMounts` in each group's `container.json`.
-2. Remove `'mcp__calendar__*'` from `TOOL_ALLOWLIST`.
+1. For each group that had Calendar wired, remove the MCP server from the DB:
+   ```bash
+   ncl groups config remove-mcp-server --id <group-id> --name calendar
+   ```
+2. Remove the `.calendar-mcp` mount from the DB (no `remove-mount` verb yet — same #2395 dependency):
+   ```bash
+   pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+     SET additional_mounts = (SELECT json_group_array(value) FROM json_each(additional_mounts) \
+                              WHERE json_extract(value, '\$.containerPath') != '.calendar-mcp'), \
+         updated_at = datetime('now') \
+     WHERE agent_group_id = '<group-id>';"
+   ```
 3. Remove `CALENDAR_MCP_VERSION` ARG and the calendar package from the Dockerfile install block.
-4. `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw`.
+4. `pnpm run build && ./container/build.sh && systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`.
 5. Optional: `rm -rf ~/.calendar-mcp/` and `onecli apps disconnect --provider google-calendar`.

+No `TOOL_ALLOWLIST` removal step — Phase 2 no longer edits it.
+
 ## Credits & references

 - **MCP server:** [`@cocal/google-calendar-mcp`](https://github.com/cocal-com/google-calendar-mcp) — MIT-licensed, actively maintained, multi-account and multi-calendar.
@@ -136,7 +136,15 @@ Use `per-thread` session mode so each PR/issue gets its own agent session.

 If you're in the middle of `/setup`, return to the setup flow now.

-Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+Otherwise, restart the service to pick up the new channel.
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
+```

 ## Channel Info

@@ -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
@@ -95,7 +98,6 @@ onecli agents set-secrets --id <agent-id> --secret-ids <gmail-secret-id>

 ```bash
 grep -q 'GMAIL_MCP_VERSION' container/Dockerfile && \
-grep -q "mcp__gmail__\*" container/agent-runner/src/providers/claude.ts && \
 echo "ALREADY APPLIED — skip to Phase 3"
 ```

@@ -129,9 +131,7 @@ Pinned version matters — `minimumReleaseAge` in `pnpm-workspace.yaml` gates tr

 **Why the `zod-to-json-schema` pin:** `@gongrzhe/server-gmail-autoauth-mcp@1.1.11` has loose deps (`zod-to-json-schema: ^3.22.1`, `zod: ^3.22.4`). pnpm resolves `zod-to-json-schema` to the latest 3.25.x, which imports `zod/v3` — a subpath that only exists in `zod>=3.25`. But `zod` resolves to `3.24.x` (highest satisfying `^3.22.4` without breaking peer ranges). Result: `ERR_PACKAGE_PATH_NOT_EXPORTED` at import time. Pinning `zod-to-json-schema` to a pre-v3-subpath version avoids it. Re-check if you bump `GMAIL_MCP_VERSION`.

-### Add tools to allowlist
-
-Edit `container/agent-runner/src/providers/claude.ts`. Find `'mcp__nanoclaw__*',` in `TOOL_ALLOWLIST` and add `'mcp__gmail__*',` after it.
+**No `TOOL_ALLOWLIST` edit needed.** `container/agent-runner/src/providers/claude.ts` derives the allow-pattern dynamically from each group's `mcpServers` map (`Object.keys(this.mcpServers).map(mcpAllowPattern)`), so registering `gmail` in Phase 3 automatically allows `mcp__gmail__*`. Earlier versions of this skill instructed a static `TOOL_ALLOWLIST` edit — that's now redundant.

 ### Rebuild the container image

@@ -143,42 +143,63 @@ Must complete cleanly. The new `pnpm install -g` layer is ~60s first time (cache

 ## Phase 3: Wire Per-Agent-Group

-For each agent group that should have Gmail (ask the user — typically their personal DM and CLI agents, sometimes shared household agents), edit `groups/<folder>/container.json` to add the mount and MCP server.
+For each agent group that should have Gmail (ask the user — typically their personal DM and CLI agents, sometimes shared household agents), persist two changes to the **central DB** (`data/v2.db`): the `mcpServers.gmail` entry and an `additionalMounts` entry for `.gmail-mcp`. Both flow through `materializeContainerJson` on every spawn, so editing `groups/<folder>/container.json` by hand does **not** stick — that file is regenerated from the DB.

-Merge these into the group's `container.json`:
+### List groups, pick which ones get Gmail

-```jsonc
-{
-  "mcpServers": {
-    "gmail": {
-      "command": "gmail-mcp",
-      "args": [],
-      "env": {
-        "GMAIL_OAUTH_PATH": "/workspace/extra/.gmail-mcp/gcp-oauth.keys.json",
-        "GMAIL_CREDENTIALS_PATH": "/workspace/extra/.gmail-mcp/credentials.json"
-      }
-    }
-  },
-  "additionalMounts": [
-    {
-      "hostPath": "/home/<user>/.gmail-mcp",
-      "containerPath": ".gmail-mcp",
-      "readonly": false
-    }
-  ]
-}
+```bash
+ncl groups list
 ```

-Substitute `<user>` with the host user's home (use `echo $HOME`, don't assume `~` will expand — `container-runner.ts` does expand `~` via `expandPath`, but an explicit absolute path is clearer and matches what `/manage-mounts` writes).
+### Register the MCP server
+
+For each chosen `<group-id>`:
+
+```bash
+ncl groups config add-mcp-server \
+  --id <group-id> \
+  --name gmail \
+  --command gmail-mcp \
+  --args '[]' \
+  --env '{"GMAIL_OAUTH_PATH":"/workspace/extra/.gmail-mcp/gcp-oauth.keys.json","GMAIL_CREDENTIALS_PATH":"/workspace/extra/.gmail-mcp/credentials.json"}'
+```
+
+Approval behaviour depends on where you run it: from inside an agent's container `ncl` write verbs are approval-gated (admin approves before it lands); from a host operator shell with full scope, it executes immediately. Either way, the response tells you which path it took.
+
+### Add the `.gmail-mcp` mount
+
+There is no `ncl groups config add-mount` verb yet (tracked in [#2395](https://github.com/nanocoai/nanoclaw/issues/2395)). Until that ships, edit the DB directly via the in-tree wrapper (`scripts/q.ts` — `setup/verify.ts:5` codifies that NanoClaw avoids depending on the `sqlite3` CLI binary, so don't shell out to it):
+
+```bash
+GROUP_ID='<group-id>'
+HOST_PATH="$HOME/.gmail-mcp"
+MOUNT=$(jq -cn --arg h "$HOST_PATH" '{hostPath:$h, containerPath:".gmail-mcp", readonly:false}')
+pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+  SET additional_mounts = json_insert(additional_mounts, '\$[#]', json('$MOUNT')), \
+      updated_at = datetime('now') \
+  WHERE agent_group_id = '$GROUP_ID';"
+```
+
+Run from your NanoClaw project root (where `data/v2.db` lives). The `$[#]` placeholder is SQLite JSON1's append-to-end notation; it's `\$`-escaped so bash doesn't arithmetic-expand it before sqlite sees it. `updated_at` is ISO-string everywhere else in the schema, so use `datetime('now')` — not `strftime('%s','now')`, which would silently mix epoch ints into a column of YYYY-MM-DD HH:MM:SS strings.
+
+**Switch to `ncl groups config add-mount` once #2395 lands.** Update this skill at that time.

 **Why the container path is relative:** `mount-security` rejects absolute `containerPath` values. Additional mounts are prefixed with `/workspace/extra/`, so `containerPath: ".gmail-mcp"` lands at `/workspace/extra/.gmail-mcp`. The MCP server's `GMAIL_OAUTH_PATH` / `GMAIL_CREDENTIALS_PATH` env vars point at that absolute location inside the container.

+**Why this can't be `groups/<folder>/container.json`:** post-migration `014-container-configs`, `materializeContainerJson` in `src/container-config.ts` rewrites that file from the DB on every spawn. Anything hand-edited there is silently overwritten on next restart.
+
 ## Phase 4: Build and Restart

 ```bash
 pnpm run build
-systemctl --user restart nanoclaw  # Linux
-# launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+```
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 ## Phase 5: Verify
@@ -203,17 +224,29 @@ Common signals:
 - `command not found: gmail-mcp` → image wasn't rebuilt or PATH doesn't include `/pnpm` (should — `ENV PATH="$PNPM_HOME:$PATH"` in Dockerfile).
 - `ENOENT: no such file or directory, open '/workspace/extra/.gmail-mcp/credentials.json'` → mount is missing. Check `~/.config/nanoclaw/mount-allowlist.json` includes a parent of `~/.gmail-mcp`.
 - `401 Unauthorized` from `gmail.googleapis.com` → OneCLI isn't injecting. Check the agent's secret mode (`onecli agents secrets --id <agent-id>`) and that the Gmail app is connected (`onecli apps get --provider gmail`).
- Agent says "I don't have Gmail tools" → `mcp__gmail__*` wasn't added to `TOOL_ALLOWLIST`, or the agent-runner wasn't rebuilt (image cache — run `./container/build.sh` again with `--no-cache` if suspicious).
+- Agent says "I don't have Gmail tools" → the `gmail` MCP server isn't registered in this group's `mcpServers` (re-run the `ncl groups config add-mcp-server` step in Phase 3 for that group and restart it), or the agent-runner image is stale (rebuild with `./container/build.sh`, with `--no-cache` if suspicious).

 ## Removal

-1. Delete the `"gmail"` entry from `mcpServers` and the `.gmail-mcp` entry from `additionalMounts` in each group's `container.json`.
-2. Remove `'mcp__gmail__*'` from `TOOL_ALLOWLIST` in `container/agent-runner/src/providers/claude.ts`.
+1. For each group that had Gmail wired, remove the MCP server from the DB:
+   ```bash
+   ncl groups config remove-mcp-server --id <group-id> --name gmail
+   ```
+2. Remove the `.gmail-mcp` mount from the DB (no `remove-mount` verb yet — same #2395 dependency):
+   ```bash
+   pnpm exec tsx scripts/q.ts data/v2.db "UPDATE container_configs \
+     SET additional_mounts = (SELECT json_group_array(value) FROM json_each(additional_mounts) \
+                              WHERE json_extract(value, '\$.containerPath') != '.gmail-mcp'), \
+         updated_at = datetime('now') \
+     WHERE agent_group_id = '<group-id>';"
+   ```
 3. Remove the `GMAIL_MCP_VERSION` ARG and the `pnpm install -g @gongrzhe/server-gmail-autoauth-mcp` block from `container/Dockerfile`.
-4. `pnpm run build && ./container/build.sh && systemctl --user restart nanoclaw`.
+4. `pnpm run build && ./container/build.sh && systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`.
 5. (Optional) `rm -rf ~/.gmail-mcp/` if no other host-side tool needs the stubs.
 6. (Optional) Disconnect Gmail in OneCLI: `onecli apps disconnect --provider gmail`.

+No `TOOL_ALLOWLIST` removal step — Phase 2 no longer edits it.
+
 ## Notes

 - **Stub format is OneCLI-prescribed.** The `access_token: "onecli-managed"` pattern with `expiry_date: 99999999999999` tells the Google auth client the token is valid; OneCLI intercepts the outgoing Gmail API call and rewrites `Authorization: Bearer onecli-managed` to the real token. `expiry_date: 0` (refresh-interception) is an alternative the OneCLI docs describe — both work but OneCLI's own `migrate` command writes the far-future variant, which is what this skill assumes.
@@ -225,5 +258,5 @@ Common signals:
 - **MCP server:** [`@gongrzhe/server-gmail-autoauth-mcp`](https://github.com/GongRzhe/Gmail-MCP-Server) by GongRzhe — MIT-licensed.
 - **OneCLI credential stubs:** pattern documented at `https://onecli.sh/docs/guides/credential-stubs/gmail.md`.
 - **Skill pattern:** modeled on [`add-atomic-chat-tool`](../add-atomic-chat-tool/SKILL.md) and [`add-vercel`](../add-vercel/SKILL.md).
- **Addresses:** [issue #1500](https://github.com/qwibitai/nanoclaw/issues/1500) (proxy Gmail/Calendar OAuth tokens through credential proxy) for the Gmail side.
- **Related PRs:** [#1810](https://github.com/qwibitai/nanoclaw/pull/1810) (pre-install Gmail/Notion MCP) overlaps on the "install the MCP server in the image" idea but bundles many unrelated changes; this skill is the focused OneCLI-native version.
+- **Addresses:** [issue #1500](https://github.com/nanocoai/nanoclaw/issues/1500) (proxy Gmail/Calendar OAuth tokens through credential proxy) for the Gmail side.
+- **Related PRs:** [#1810](https://github.com/nanocoai/nanoclaw/pull/1810) (pre-install Gmail/Notion MCP) overlaps on the "install the MCP server in the image" idea but bundles many unrelated changes; this skill is the focused OneCLI-native version.
@@ -75,9 +75,12 @@ If yes, ask the agent to schedule the lint task using the `schedule_task` MCP to

 ## Step 6: Restart

+Run from your NanoClaw project root:
+
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 Tell the user to test by sending a source to the wiki group.
@@ -156,7 +156,15 @@ The `platform_id` must be `linear:<TEAM_KEY>` matching the `LINEAR_TEAM_KEY` env

 If you're in the middle of `/setup`, return to the setup flow now.

-Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+Otherwise, restart the service to pick up the new channel.
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
+```

 ## Channel Info

@@ -0,0 +1,211 @@
+---
+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
+
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
+# launchctl kickstart -k gui/$(id -u)/$(launchd_label)   # 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
+```
@@ -130,12 +130,15 @@ file, not from env vars. This file is bind-mounted into the container as `~/.cla

 ## 5. Build and restart

+Run from your NanoClaw project root:
+
 ```bash
 export PATH="/opt/homebrew/bin:$PATH"
 pnpm run build
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl unload ~/Library/LaunchAgents/$(launchd_label).plist
+launchctl load   ~/Library/LaunchAgents/$(launchd_label).plist
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 ## 6. Verify
@@ -54,7 +54,7 @@ git remote -v
 If `upstream` is missing, add it:

 ```bash
-git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git remote add upstream https://github.com/nanocoai/nanoclaw.git
 ```

 ### Merge the skill branch
@@ -122,9 +122,12 @@ OLLAMA_HOST=http://your-ollama-host:11434

 ### Restart the service

+Run from your NanoClaw project root:
+
 ```bash
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
 ```

 ## Phase 4: Verify
@@ -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

@@ -229,19 +229,22 @@ echo '{}' | docker run -i --entrypoint /bin/echo nanoclaw-agent:latest "Containe

 ### 7. Restart Service

-Rebuild the main app and restart:
+Rebuild the main app and restart.
+
+Run from your NanoClaw project root:

 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 Wait 3 seconds for service to start, then verify:
 ```bash
 sleep 3
-launchctl list | grep nanoclaw  # macOS
-# Linux: systemctl --user status nanoclaw
+launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"  # macOS
+# Linux: systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"
 ```

 ### 8. Test Integration
@@ -287,4 +290,4 @@ To remove Parallel AI integration:
 2. Revert changes to container-runner.ts and agent-runner/src/index.ts
 3. Remove Web Research Tools section from groups/main/CLAUDE.md
 4. Rebuild: `./container/build.sh && pnpm run build`
-5. Restart: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)
+5. Restart: `source setup/lib/install-slug.sh && launchctl kickstart -k gui/$(id -u)/$(launchd_label)` (macOS) or `source setup/lib/install-slug.sh && systemctl --user restart $(systemd_unit)` (Linux)
@@ -90,17 +90,21 @@ No output = success.

 > ⚠ Stop NanoClaw before running signal-cli commands — the daemon holds an exclusive lock on its data directory while running.

+Run from your NanoClaw project root:
+
 ```bash
+source setup/lib/install-slug.sh
+
 # macOS
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl unload ~/Library/LaunchAgents/$(launchd_label).plist
 signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
 # optionally: --avatar /path/to/avatar.jpg
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl load ~/Library/LaunchAgents/$(launchd_label).plist

 # Linux
-systemctl --user stop nanoclaw
+systemctl --user stop $(systemd_unit)
 signal-cli -a +1YOURNUMBER updateProfile --name "YourBotName"
-systemctl --user start nanoclaw
+systemctl --user start $(systemd_unit)
 ```

 ### Path B: Link as secondary device
@@ -185,12 +189,16 @@ Sync to container: `mkdir -p data/env && cp .env data/env/env`

 ### Restart

+Run from your NanoClaw project root:
+
 ```bash
+source setup/lib/install-slug.sh
+
 # macOS
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)

 # Linux
-systemctl --user restart nanoclaw
+systemctl --user restart $(systemd_unit)
 ```

 ## Wiring
@@ -283,7 +291,12 @@ 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)
+3. Service running: `launchctl print gui/$(id -u)/"$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) / `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (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

@@ -60,7 +60,7 @@ pnpm run build
 1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** > **From scratch**
 2. Name it (e.g., "NanoClaw") and select your workspace
 3. Go to **OAuth & Permissions** and add Bot Token Scopes:
-   - `chat:write`, `im:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`
+   - `chat:write`, `im:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`, `files:read`, `files:write`
 4. Click **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-...`)
 5. Go to **Basic Information** and copy the **Signing Secret**

@@ -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
 ```

@@ -41,9 +41,12 @@ DELETE FROM messaging_groups WHERE channel_type = 'wechat';

 ### 6. Rebuild and restart

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-systemctl --user restart nanoclaw   # Linux
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
 # or
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
 ```
@@ -82,12 +82,15 @@ Sync to container: `mkdir -p data/env && cp .env data/env/env`

 ### 2. Start the service and scan the QR

-Restart NanoClaw:
+Restart NanoClaw.
+
+Run from your NanoClaw project root:

 ```bash
-systemctl --user restart nanoclaw   # Linux
+source setup/lib/install-slug.sh
+systemctl --user restart $(systemd_unit)              # Linux
 # or
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
 ```

 The adapter will print a **QR URL** to the logs and save it to `data/wechat/qr.txt`:
@@ -244,12 +244,15 @@ rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --met

 ### "waiting for this message" on reactions

-Signal sessions corrupted from rapid restarts. Clear sessions:
+Signal sessions corrupted from rapid restarts. Clear sessions.
+
+Run from your NanoClaw project root:

 ```bash
-systemctl --user stop nanoclaw
+source setup/lib/install-slug.sh
+systemctl --user stop $(systemd_unit)
 rm store/auth/session-*.json
-systemctl --user start nanoclaw
+systemctl --user start $(systemd_unit)
 ```

 ### Bot not responding
@@ -257,7 +260,7 @@ systemctl --user start nanoclaw
 1. Auth exists: `test -f store/auth/creds.json`
 2. Connected: `grep "Connected to WhatsApp" logs/nanoclaw.log | tail -1`
 3. 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='whatsapp'"`
-4. Service running: `systemctl --user status nanoclaw`
+4. Service running: `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"`

 ### "conflict" disconnection

@@ -58,7 +58,7 @@ git remote -v
 If `upstream` is missing, add it:

 ```bash
-git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git remote add upstream https://github.com/nanocoai/nanoclaw.git
 ```

 ### Merge the skill branch
@@ -171,9 +171,12 @@ Expected: Both operations succeed.

 ### Full integration test

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)
 ```

 Send a message via WhatsApp and verify the agent responds.
@@ -88,15 +88,19 @@ Implementation:

 ## After Changes

-Always tell the user:
+Always tell the user.
+
+Run from your NanoClaw project root:
+
 ```bash
 # Rebuild and restart
 pnpm run build
+source setup/lib/install-slug.sh
 # macOS:
-launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
-launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl unload ~/Library/LaunchAgents/$(launchd_label).plist
+launchctl load ~/Library/LaunchAgents/$(launchd_label).plist
 # Linux:
-# systemctl --user restart nanoclaw
+# systemctl --user restart $(systemd_unit)
 ```

 ## Example Interaction
@@ -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`

@@ -9,7 +9,7 @@ Stand up the first NanoClaw agent for a channel and verify end-to-end delivery b

 ## Prerequisites

- **Service running.** Check: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux). If stopped, tell the user to run `/setup` first.
+- **Service running.** Check: `launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) or `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (Linux). If stopped, tell the user to run `/setup` first.
 - **Target channel installed.** At least one `/add-<channel>` skill has run, credentials are in `.env`, and the adapter is uncommented in `src/channels/index.ts`.
 - **Adapter connected.** Tail `logs/nanoclaw.log` — look for a recent `channel setup` / `adapter connected` line for the target channel.

@@ -236,9 +236,12 @@ pnpm run build

 If build fails, diagnose and fix. Common issue: `@onecli-sh/sdk` not installed — run `pnpm install` first.

-Restart the service:
- macOS (launchd): `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
- Linux (systemd): `systemctl --user restart nanoclaw`
+Restart the service.
+
+Run from your NanoClaw project root:
+
+- macOS (launchd): `launchctl kickstart -k gui/$(id -u)/"$(. setup/lib/install-slug.sh && launchd_label)"`
+- Linux (systemd): `systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`
 - WSL/manual: stop and re-run `bash start-nanoclaw.sh`

 ## Phase 5: Verify
@@ -259,6 +262,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.
@@ -41,7 +41,12 @@ npx tsx setup/index.ts --step mounts --force -- --empty

 ## After Changes

-Restart the service so containers pick up the new config:
+Restart the service so containers pick up the new config (the unit/label names are per-install — see `setup/lib/install-slug.sh`).

- macOS: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
- Linux: `systemctl --user restart nanoclaw`
+Run from your NanoClaw project root:
+
+```bash
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+systemctl --user restart $(systemd_unit)              # Linux
+```
@@ -34,7 +34,7 @@ Two phases: **Extract** (build the migration guide) and **Upgrade** (use it). If

 Run `git status --porcelain`. If non-empty, offer to stash or commit for them (AskUserQuestion: "Stash changes" / "Commit changes" / "I'll handle it"). If they want to commit, stage and commit with a descriptive message. If they want to stash, run `git stash push -m "pre-migration stash"`.

-Check remotes with `git remote -v`. If `upstream` is missing, ask for the URL (default: `https://github.com/qwibitai/nanoclaw.git`), add it, then `git fetch upstream --prune`.
+Check remotes with `git remote -v`. If `upstream` is missing, ask for the URL (default: `https://github.com/nanocoai/nanoclaw.git`), add it, then `git fetch upstream --prune`.

 Detect upstream branch: check `git branch -r | grep upstream/` for `main` or `master`. Store as UPSTREAM_BRANCH.

@@ -11,7 +11,7 @@ Run `/update-nanoclaw` in Claude Code.

 ## How it works

-**Preflight**: checks for clean working tree (`git status --porcelain`). If `upstream` remote is missing, asks you for the URL (defaults to `https://github.com/qwibitai/nanoclaw.git`) and adds it. Detects the upstream branch name (`main` or `master`).
+**Preflight**: checks for clean working tree (`git status --porcelain`). If `upstream` remote is missing, asks you for the URL (defaults to `https://github.com/nanocoai/nanoclaw.git`) and adds it. Detects the upstream branch name (`main` or `master`).

 **Backup**: creates a timestamped backup branch and tag (`backup/pre-update-<hash>-<timestamp>`, `pre-update-<hash>-<timestamp>`) before touching anything. Safe to run multiple times.

@@ -69,7 +69,7 @@ If output is non-empty:
 Confirm remotes:
 - `git remote -v`
 If `upstream` is missing:
- Ask the user for the upstream repo URL (default: `https://github.com/qwibitai/nanoclaw.git`).
+- Ask the user for the upstream repo URL (default: `https://github.com/nanocoai/nanoclaw.git`).
 - Add it: `git remote add upstream <user-provided-url>`
 - Then: `git fetch upstream --prune`

@@ -270,9 +270,9 @@ Show:
 Tell the user:
 - To rollback: `git reset --hard <backup-tag-from-step-1>`
 - Backup branch also exists: `backup/pre-update-<HASH>-<TIMESTAMP>`
- Restart the service to apply changes. Detect platform with `uname -s`:
-  - **macOS (Darwin)**: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
-  - **Linux**: detect the service name with `systemctl --user list-units --type=service | grep nanoclaw | awk '{print $1}'`, then `systemctl --user restart <detected-name>`
+- Restart the service to apply changes. The unit/label names are per-install — derive them with `setup/lib/install-slug.sh`. Run from your NanoClaw project root:
+  - **macOS (Darwin)**: `source setup/lib/install-slug.sh && launchctl kickstart -k gui/$(id -u)/$(launchd_label)`
+  - **Linux**: `source setup/lib/install-slug.sh && systemctl --user restart $(systemd_unit)` (or, if you want to confirm the unit name first: `systemctl --user list-units --type=service | grep "$(. setup/lib/install-slug.sh && systemd_unit)"`)
  - **Manual** (no service found): restart `pnpm run dev`


@@ -42,7 +42,7 @@ Check remotes:
 - `git remote -v`

 If `upstream` is missing:
- Ask the user for the upstream repo URL (default: `https://github.com/qwibitai/nanoclaw.git`).
+- Ask the user for the upstream repo URL (default: `https://github.com/nanocoai/nanoclaw.git`).
 - `git remote add upstream <url>`

 Fetch:
@@ -40,7 +40,7 @@ git remote -v
 If `upstream` is missing, add it:

 ```bash
-git remote add upstream https://github.com/qwibitai/nanoclaw.git
+git remote add upstream https://github.com/nanocoai/nanoclaw.git
 ```

 ### Merge the skill branch
@@ -128,9 +128,12 @@ echo 'ANTHROPIC_API_KEY=<key>' >> .env
 pnpm run build
 ```

-Then restart the service:
- macOS: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
- Linux: `systemctl --user restart nanoclaw`
+Then restart the service.
+
+Run from your NanoClaw project root:
+
+- macOS: `launchctl kickstart -k gui/$(id -u)/"$(. setup/lib/install-slug.sh && launchd_label)"`
+- Linux: `systemctl --user restart "$(. setup/lib/install-slug.sh && systemd_unit)"`
 - WSL/manual: stop and re-run `bash start-nanoclaw.sh`

 2. Check logs for successful proxy startup:
@@ -38,6 +38,8 @@ Before using this skill, ensure:

 ## Quick Start

+Run from your NanoClaw project root:
+
 ```bash
 # 1. Setup authentication (interactive)
 pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
@@ -49,9 +51,10 @@ pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/s

 # 3. Rebuild host and restart service
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
-# Verify: launchctl list | grep nanoclaw (macOS) or systemctl --user status nanoclaw (Linux)
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
+# Verify: launchctl list | grep "$(launchd_label)" (macOS) or systemctl --user status $(systemd_unit) (Linux)
 ```

 ## Configuration
@@ -270,16 +273,23 @@ cat data/x-auth.json  # Should show {"authenticated": true, ...}

 ### 4. Restart Service

+Run from your NanoClaw project root:
+
 ```bash
 pnpm run build
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

-**Verify success:**
+**Verify success.**
+
+Run from your NanoClaw project root:
+
 ```bash
-launchctl list | grep nanoclaw  # macOS — should show PID and exit code 0 or -
-# Linux: systemctl --user status nanoclaw
+source setup/lib/install-slug.sh
+launchctl list | grep "$(launchd_label)"  # macOS — should show PID and exit code 0 or -
+# Linux: systemctl --user status $(systemd_unit)
 ```

 ## Usage via WhatsApp
@@ -343,10 +353,13 @@ echo '{"content":"Test"}' | pnpm exec tsx .claude/skills/x-integration/scripts/p

 ### Authentication Expired

+Run from your NanoClaw project root:
+
 ```bash
 pnpm exec dotenv -e .env -- pnpm exec tsx .claude/skills/x-integration/scripts/setup.ts
-launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
-# Linux: systemctl --user restart nanoclaw
+source setup/lib/install-slug.sh
+launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
+# Linux: systemctl --user restart $(systemd_unit)
 ```

 ### Browser Lock Files
@@ -7,7 +7,7 @@ on:

 jobs:
  bump-version:
-    if: github.repository == 'qwibitai/nanoclaw'
+    if: github.repository == 'nanocoai/nanoclaw'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v1
@@ -8,7 +8,7 @@ on:

 jobs:
  update-tokens:
-    if: github.repository == 'qwibitai/nanoclaw'
+    if: github.repository == 'nanocoai/nanoclaw'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v1
@@ -1 +1,5 @@
+staged=$(git diff --cached --name-only --diff-filter=ACM -- 'src/**/*.ts')
 pnpm run format:fix
+if [ -n "$staged" ]; then
+  echo "$staged" | xargs git add
+fi
@@ -2,12 +2,41 @@

 All notable changes to NanoClaw will be documented in this file.

-For detailed release notes, see the [full changelog on the documentation site](https://docs.nanoclaw.dev/changelog).
+## [2.0.64] - 2026-05-18

-## [Unreleased]
+- **`ncl destinations add` and `remove` through the approval flow now reach the receiver immediately.** Approved destinations weren't being projected into the receiving agent's local session state, so a freshly-added destination silently failed at `send_message` with `unknown destination`, and a removed destination stayed resolvable until the next container restart. Both now take effect the moment the approval executes. Direct (non-approval) calls were unaffected.

+## [2.0.63] - 2026-05-15
+
+Rollup release covering v2.0.55 through v2.0.63 — everything merged since the v2.0.54 tag. Starting with this release, the goal is to publish a GitHub Release for every `package.json` version bump that lands on `main`; see [RELEASING.md](RELEASING.md).
+
+- [BREAKING] **Service names are now per-install.** On v2 installs the launchd label and systemd unit are slugged to your project root: `com.nanoclaw.<sha1(projectRoot)[:8]>` and `nanoclaw-<slug>.service`. The old `com.nanoclaw` / `nanoclaw.service` names no longer match a real service — update any copy-pasted restart or status commands. Find your install's names with `source setup/lib/install-slug.sh && launchd_label` (macOS) or `systemd_unit` (Linux). The `ncl` transport-error help text and 26 skill files now use the canonical helper-driven pattern; see [setup/lib/install-slug.sh](setup/lib/install-slug.sh).
+- **Compaction destination reminder placement fixed.** The reminder injected after SDK auto-compaction now appears at the end of the compaction summary so it isn't stripped during truncation. Replaces the placement shipped in v2.0.54.
+- **Stronger message-wrapping enforcement.** The poll loop nudges the agent when its output lacks `<message>` wrapping, and `CLAUDE.md` core instructions now require wrapping even for single-destination agents. The welcome flow no longer double-greets.
+- **OneCLI credentials after MCP install.** MCP servers added through `add_mcp_server` now inherit OneCLI gateway routing — fixes the case where the agent kept asking for API keys after installing a new server.
+- **CLI scope hardening.** `scopeField` now fails closed when scope is missing, and `sessions get` is guarded against cross-group oracle access from group-scoped agents.
+- **gmail/gcal skills aligned with v2.** `/add-gmail-tool` and `/add-gcal-tool` now reflect the v2 container-config model — DB-backed mounts, no dead `TOOL_ALLOWLIST` edits, no `container.json` writes that get clobbered on next spawn. Manual sqlite3/JSON1 invocations corrected.
+- **Repo-rename cleanup.** Remaining `qwibitai/nanoclaw` references swept to `nanocoai/nanoclaw` across code and docs; CI workflow guards updated so they no longer no-op after the rename.
+- Slack scope checklist now includes `files:read` and `files:write` for skills that read or post attachments.
+- The internal-tag description in destination instructions no longer mentions scratchpads (which confused agents into routing them incorrectly).
+- Container startup is now graceful when the `on_wake` column is missing on older sessions DBs.
+
+## [2.0.54] - 2026-05-10
+
+- **Per-group model and effort overrides.** Agent groups can now run a specific Claude model and effort level, set via `ncl groups config update --model <model> --effort <level>`. Defaults to the host-configured model when unset.
+- **Claude Code 2.1.128.** Container claude-code bumped from 2.1.116 to 2.1.128.
+- CLI help text improvements for `ncl groups config` and `ncl groups restart`.
+
+## [2.0.48] - 2026-05-09
+
+- **Container config moved to DB.** Per-agent-group container runtime config (provider, model, packages, MCP servers, mounts, skills) now lives in the `container_configs` table instead of `groups/<folder>/container.json`. Existing filesystem configs are backfilled automatically on startup. Managed via `ncl groups config get/update` and `config add-mcp-server/remove-mcp-server/add-package/remove-package`.
+- **Explicit restart with on-wake messages.** Config CLI operations no longer auto-kill containers. New `ncl groups restart` command with `--rebuild` and `--message` flags. On-wake messages (`on_wake` column on `messages_in`) are only picked up by a fresh container's first poll, preventing dying containers from stealing them during the SIGTERM grace period. Self-mod approval handlers (`install_packages`, `add_mcp_server`) use the same race-free mechanism.
+- **Per-group CLI scope.** New `cli_scope` setting on container config (`disabled` / `group` / `global`, default `group`). Controls what the agent can access via `ncl` from inside the container. `disabled` excludes CLI instructions from CLAUDE.md and blocks all requests. `group` (default) restricts to own-group resources with auto-filled args. `global` gives unrestricted access (set automatically for owner agent groups). Includes post-handler result filtering to prevent cross-group data leaks and blocks `cli_scope` escalation from group-scoped agents.
+
+## [2.0.45] - 2026-05-08
+
+- **Admin CLI (`ncl`).** New `ncl` command for querying and modifying the central DB — agent groups, messaging groups, wirings, users, roles, members, destinations, sessions, approvals, and dropped messages. Host-side transport via Unix socket; container-side transport via session DB. Write operations from inside containers go through the approval flow. `list` supports column filtering and `--limit`. Run `ncl help` for usage.
 - **v1 → v2 migration.** Run `bash migrate-v2.sh` from the v2 checkout. Finds your v1 install (sibling directory or `NANOCLAW_V1_PATH`), merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders (`CLAUDE.md` → `CLAUDE.local.md`), copies session data with conversation continuity, ports scheduled tasks, interactively selects and installs channels (clack multiselect), copies container skills, builds the agent container, and offers a service switchover to test. Hands off to Claude (`/migrate-from-v1`) for owner seeding, access policy, CLAUDE.md cleanup, and fork customization porting. See [docs/migration-dev.md](docs/migration-dev.md) and [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md).
- **Migration fixes.** `1b-db` now resolves Discord DMs as `discord:@me:<id>` (previously skipped any v1 chat that wasn't a guild channel — a blocker for personal-bot installs). `1c-groups` skips symlinks instead of following them (a single broken `.claude-shared.md → /app/CLAUDE.md` no longer aborts the whole copy). When `1b-db` reuses an auto-created `messaging_group` with no wired agents, its `unknown_sender_policy` is now reconciled to the migration's `public` default.

 ## [2.0.0] - 2026-04-22

@@ -72,15 +72,44 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
 | `src/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |
 | `src/user-dm.ts` | Cold-DM resolution + `user_dms` cache |
 | `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills, agent-runner-src overlay) |
-| `src/db/` | DB layer — agent_groups, messaging_groups, sessions, user_roles, user_dms, pending_*, migrations |
+| `src/db/container-configs.ts` | CRUD for `container_configs` table (per-group container runtime config) |
+| `src/backfill-container-configs.ts` | Migrates legacy `container.json` files into the DB on startup |
+| `src/container-restart.ts` | Kill + on-wake respawn for agent group containers |
+| `src/db/` | DB layer — agent_groups, messaging_groups, sessions, container_configs, user_roles, user_dms, pending_*, migrations |
 | `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, restart, config get/update, config add-mcp-server/remove-mcp-server, config add-package/remove-package | 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:
@@ -94,13 +123,35 @@ Each `/add-<name>` skill is idempotent: `git fetch origin <branch>` → copy mod

 One tier of agent self-modification today:

-1. **`install_packages` / `add_mcp_server`** — changes to the per-agent-group container config only (apt/npm deps, wire an existing MCP server). Single admin approval per request; on approve, the handler in `src/modules/self-mod/apply.ts` rebuilds the image when needed (`install_packages` only) and restarts the container. `container/agent-runner/src/mcp-tools/self-mod.ts`.
+1. **`install_packages` / `add_mcp_server`** — changes to the per-agent-group container config in the DB (apt/npm deps, wire an existing MCP server). Single admin approval per request; on approve, the handler in `src/modules/self-mod/apply.ts` rebuilds the image when needed (`install_packages` only), writes an `on_wake` message, kills the container, and respawns via `onExit` callback. The on-wake message is only picked up by the fresh container's first poll — dying containers can never steal it. `container/agent-runner/src/mcp-tools/self-mod.ts`.

 A second tier (direct source-level self-edits via a draft/activate flow) is planned but not yet implemented.

+## Container Config
+
+Per-agent-group container runtime config (provider, model, packages, MCP servers, mounts, etc.) lives in the `container_configs` table in the central DB. Materialized to `groups/<folder>/container.json` at spawn time so the container runner can read it. Managed via `ncl groups config get/update` and the self-mod MCP tools.
+
+**`cli_scope`** — controls what the agent can do with `ncl` from inside the container:
+
+| Value | Behavior |
+|-------|----------|
+| `disabled` | Agent never learns about ncl (instructions excluded from CLAUDE.md). Host dispatch rejects any `cli_request`. |
+| `group` (default) | Agent can access `groups`, `sessions`, `destinations`, `members` only, scoped to its own agent group. `--id` and group args are auto-filled. Cross-group access rejected. `cli_scope` changes blocked. |
+| `global` | Unrestricted. Set automatically for owner agent groups via `init-first-agent`. |
+
+Key files: `src/db/container-configs.ts`, `src/container-config.ts`, `src/cli/dispatch.ts` (scope enforcement), `src/claude-md-compose.ts` (instructions exclusion).
+
+## Container Restart
+
+`ncl groups restart --id <group-id> [--rebuild] [--message <text>]`. Kills running containers; if `--message` is provided, writes an `on_wake` message and respawns via `onExit` callback. Without `--message`, containers come back on the next user message. From inside a container, `--id` is auto-filled and only the calling session is restarted.
+
+The `on_wake` column on `messages_in` ensures wake messages are only picked up by a fresh container's first poll iteration. This prevents the race where a dying container (still in its SIGTERM grace period) could steal the message. `killContainer` accepts an optional `onExit` callback that fires after the process exits, guaranteeing the old container is gone before the new one spawns.
+
+Key files: `src/container-restart.ts`, `src/container-runner.ts` (`killContainer`), `container/agent-runner/src/db/messages-in.ts` (`getPendingMessages`).
+
 ## 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 +195,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 |
 |-------|-------------|
@@ -4,8 +4,8 @@

 1. **Check for existing work.** Search open PRs and issues before starting:
   ```bash
-   gh pr list --repo qwibitai/nanoclaw --search "<your feature>"
-   gh issue list --repo qwibitai/nanoclaw --search "<your feature>"
+   gh pr list --repo nanocoai/nanoclaw --search "<your feature>"
+   gh issue list --repo nanocoai/nanoclaw --search "<your feature>"
   ```
   If a related PR or issue exists, build on it rather than duplicating effort.

@@ -43,7 +43,7 @@ Add capabilities to NanoClaw by merging a git branch. The SKILL.md contains setu
 3. Claude walks through interactive setup (env vars, bot creation, etc.)

 **Contributing a feature skill:**
-1. Fork `qwibitai/nanoclaw` and branch from `main`
+1. Fork `nanocoai/nanoclaw` and branch from `main`
 2. Make the code changes (new files, modified source, updated `package.json`, etc.)
 3. Add a SKILL.md in `.claude/skills/<name>/` with setup instructions — step 1 should be merging the branch
 4. Open a PR. We'll create the `skill/<name>` branch from your work
@@ -26,7 +26,7 @@ NanoClaw provides that same core functionality, but in a codebase small enough t
 ## Quick Start

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash nanoclaw.sh
 ```
@@ -39,7 +39,7 @@ bash nanoclaw.sh
 Run from a fresh v2 checkout next to your v1 install:

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash migrate-v2.sh
 ```
@@ -26,7 +26,7 @@ NanoClawは同じコア機能を提供しますが、理解できる規模のコ
 ## クイックスタート

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash nanoclaw.sh
 ```
@@ -26,7 +26,7 @@ NanoClaw 用一个您能轻松理解的代码库提供了同样的核心功能
 ## 快速开始

 ```bash
-git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
 cd nanoclaw-v2
 bash nanoclaw.sh
 ```
@@ -0,0 +1,50 @@
+# Releasing NanoClaw
+
+Starting with v2.0.63, the goal is to publish a GitHub Release for every `package.json` version bump that lands on `main`. Releases are cut manually by a maintainer, so there can be lag between a bump merging and its release being published. The intent is *timeliness*, not strict 1:1 correlation with every bump.
+
+Each release ships:
+
+- A tagged commit on `main` (`vX.Y.Z`).
+- A `CHANGELOG.md` entry under `## [<version>] - <YYYY-MM-DD>`.
+- A GitHub Release whose body mirrors the CHANGELOG entry plus a contributors section.
+
+## When to cut a release
+
+A release is cut by a maintainer publishing it. The trigger is a `package.json` bump on `main`, but the publish step is manual — there is no fixed schedule, and bumps that land back-to-back may be rolled into a single release (as v2.0.55 through v2.0.63 were). Cutting more frequently is preferable to batching: smaller releases are easier to read, pin, and revert.
+
+## What goes in a release
+
+`CHANGELOG.md` is the canonical record of user-visible change. The release body on GitHub mirrors it. Aim for:
+
+- **Bold lead-ins** per major feature or fix, then a sentence-case prose explanation.
+- **`[BREAKING]` prefix** for any change that requires user action. Always include the workaround inline — never link to a separate doc for the fix.
+- **Doc links** for major features (relative paths into the repo, e.g. `[setup/lib/install-slug.sh](setup/lib/install-slug.sh)`).
+- **Inline commands** for actionable steps, in backticks.
+- **Minor items** as single plain bullets at the bottom of the entry, no bold lead-in.
+- **No PR numbers** in the user-facing prose. PR references can live in the GitHub Release's `## Contributors` section.
+
+## Publishing the release
+
+1. Bump `package.json` and add a `CHANGELOG.md` entry in the same commit (commit message: `chore: bump version to vX.Y.Z`).
+2. Once the bump commit lands on `main`, open a draft GitHub Release:
+   - **Tag:** `vX.Y.Z`, target `main`.
+   - **Title:** `vX.Y.Z` (bare version — descriptive content lives in the body, matching the CHANGELOG header pattern).
+   - **Body:** copy the CHANGELOG entry verbatim. Append a `## Contributors` section listing every PR author who landed work in the release window. Append a `**Full Changelog**: https://github.com/nanocoai/nanoclaw/compare/<prev-tag>...vX.Y.Z` line at the bottom.
+3. If anyone in the window opened their first NanoClaw PR, add a `## New Contributors` section above `## Contributors`, with each first-timer's first PR link and an invite to Discord.
+4. Publish (not just save draft).
+
+## Rollup releases
+
+If multiple `package.json` bumps land between two GitHub Releases (as happened between v2.0.54 and v2.0.63), the next release is a rollup: its CHANGELOG entry covers everything merged since the last released tag, and the body opens with a one-line "Rollup release covering vX.Y.Z through vX.Y.W." note. After the catchup, return to one release per bump.
+
+## Channels and stability
+
+NanoClaw currently ships a single channel: every published release is a stable release.
+
+- **Latest** — the most recent release on `main`, shown as "Latest release" on the GitHub Releases page. Consumers that want auto-bump follow GitHub's `/releases/latest` pointer.
+- **Stable** — currently identical to latest. NanoClaw has no separate stable branch and no pre-release/RC channel.
+- **Pinned** — any tagged release. Reproducible and the recommended choice for packagers and forks; published tags are not moved or retracted.
+
+If a pre-release channel is introduced later (e.g. `vX.Y.Z-rc.N`), those releases will be marked "Pre-release" on GitHub so they do not become the `latest` pointer, and this section will be updated to describe the promotion path.
+
+The tag is the source of truth — a GitHub Release's `target_commitish` always points to a tagged commit.
@@ -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 "$@"
@@ -19,7 +19,7 @@ ARG INSTALL_CJK_FONTS=false
 # Pin CLI versions for reproducibility. Bump deliberately — unpinned installs
 # mean every rebuild silently picks up the latest and can break in lockstep
 # across all users.
-ARG CLAUDE_CODE_VERSION=2.1.116
+ARG CLAUDE_CODE_VERSION=2.1.128
 ARG AGENT_BROWSER_VERSION=latest
 ARG VERCEL_VERSION=52.2.1
 ARG BUN_VERSION=1.3.12
@@ -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
@@ -5,7 +5,7 @@
    "": {
      "name": "nanoclaw-agent-runner",
      "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.2.116",
+        "@anthropic-ai/claude-agent-sdk": "^0.2.128",
        "@modelcontextprotocol/sdk": "^1.12.1",
        "cron-parser": "^5.0.0",
        "zod": "^4.0.0",
@@ -18,23 +18,23 @@
    },
  },
  "packages": {
-    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.116", "", { "dependencies": { "@anthropic-ai/sdk": "^0.81.0", "@modelcontextprotocol/sdk": "^1.29.0" }, "optionalDependencies": { "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.2.116", "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.2.116", "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.2.116", "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.2.116", "@anthropic-ai/claude-agent-sdk-linux-x64": "0.2.116", "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.2.116", "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.2.116", "@anthropic-ai/claude-agent-sdk-win32-x64": "0.2.116" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-5NKpgaOZkzNCGCvLxJZUVGimf5IcYmpQ2x2XrR9ilK+2UkWrnnwcUfIWo8bBz9e7lSYcUf9XleGigq2eOOF7aw=="],
+    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.138", "", { "dependencies": { "@anthropic-ai/sdk": "^0.81.0", "@modelcontextprotocol/sdk": "^1.29.0" }, "optionalDependencies": { "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.2.138", "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.2.138", "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.2.138", "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.2.138", "@anthropic-ai/claude-agent-sdk-linux-x64": "0.2.138", "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.2.138", "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.2.138", "@anthropic-ai/claude-agent-sdk-win32-x64": "0.2.138" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-rH6dFI3DBBsPBPcHTBdTZCHA14OCt2t4+6XYi2MJB/GlFrnZvlWmMIk2z9uxAiZ05Txg8YbftgSuE5A1qpAXwg=="],

-    "@anthropic-ai/claude-agent-sdk-darwin-arm64": ["@anthropic-ai/claude-agent-sdk-darwin-arm64@0.2.116", "", { "os": "darwin", "cpu": "arm64" }, "sha512-mG19ovtXCpETmd5KmTU1JO2iIHZBG09IP8DmgZjLA3wLmTzpgn9Au9veRaeJeXb1EqiHiFZU+z+mNB79+w5v9g=="],
+    "@anthropic-ai/claude-agent-sdk-darwin-arm64": ["@anthropic-ai/claude-agent-sdk-darwin-arm64@0.2.138", "", { "os": "darwin", "cpu": "arm64" }, "sha512-aObxJ/GeJ5UxT9N8XypUHPYQKpwYsRT5THiJl5E2pKEUk/Xt42gT55N5GV0TOjtgxVAnDMWjxTAgGCGoDzjgpg=="],

-    "@anthropic-ai/claude-agent-sdk-darwin-x64": ["@anthropic-ai/claude-agent-sdk-darwin-x64@0.2.116", "", { "os": "darwin", "cpu": "x64" }, "sha512-qC25N0HRM8IXbM4Qi4svH9f51Y6DciDvjLV+oNYnxkdPgDG8p/+b7vQirN7qPxytIQb2TPdoFgUeCsSe7lrQyw=="],
+    "@anthropic-ai/claude-agent-sdk-darwin-x64": ["@anthropic-ai/claude-agent-sdk-darwin-x64@0.2.138", "", { "os": "darwin", "cpu": "x64" }, "sha512-ou3i1/gAf2PEgVl2WYJb7ZdE+KGwoB1I46JRhWHSC3uD6lb9HMZam233T/rlKCVX9e5dzfkujUOnmCkmXjgVGQ=="],

-    "@anthropic-ai/claude-agent-sdk-linux-arm64": ["@anthropic-ai/claude-agent-sdk-linux-arm64@0.2.116", "", { "os": "linux", "cpu": "arm64" }, "sha512-MQIcJhhPM+RPJ7kMQdOQarkJ2FlJqOiu953c08YyJOoWdHykd3DIiHws3mf1Mwl/dfFeIyshOVpNND3hyIy5Dg=="],
+    "@anthropic-ai/claude-agent-sdk-linux-arm64": ["@anthropic-ai/claude-agent-sdk-linux-arm64@0.2.138", "", { "os": "linux", "cpu": "arm64" }, "sha512-jp8lmAVe9uI9X5o+IYWFajLbN+Z80XogVX7NeyaenLHdpHkxg29Yf8pb6Os4OvHMjJOAdwDhPpXajf6RtBeEDA=="],

-    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": ["@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.2.116", "", { "os": "linux", "cpu": "arm64" }, "sha512-Dg/T3NkSp35ODiwdhj0KquvC6Xu+DMbyWFNkfepA3bz4oF2SVSgyOPYwVmfoJerzEUnYDldP4YhOxRrhbt0vXA=="],
+    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": ["@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.2.138", "", { "os": "linux", "cpu": "arm64" }, "sha512-uZaEFND1pl7KD9tdYqj2hd6ktjlYizVmkHRgU2Aj/P1CC6WMDsKG+rqPP7dsVXO77gMXhL4xjjwwqMjxx83HkA=="],

-    "@anthropic-ai/claude-agent-sdk-linux-x64": ["@anthropic-ai/claude-agent-sdk-linux-x64@0.2.116", "", { "os": "linux", "cpu": "x64" }, "sha512-Bww1fzQB+vcF0tRhmCAlwSsN4wR2HgX7pBT9AWuwzJj6DKsVC23N54Ea80lsnM7dTUtUTrGYMTwVUHTWqfYnfQ=="],
+    "@anthropic-ai/claude-agent-sdk-linux-x64": ["@anthropic-ai/claude-agent-sdk-linux-x64@0.2.138", "", { "os": "linux", "cpu": "x64" }, "sha512-SLuUmu/nH1Wh0wnoXj/Bwh0nbDfEn9PgXqMsZHEUk3x1zxeR+6aRqFLjKZ8TawBey7xod7nfYUIjPnQx6IWDzg=="],

-    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": ["@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.2.116", "", { "os": "linux", "cpu": "x64" }, "sha512-LMYxUMa1nK4N9BPRJdcGBAvl9rjTI4ZHo+kfAKrJ3MlfB6VFF1tRIubwsWOaOtkuNazMdAYovsZJg4bdzOBBTQ=="],
+    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": ["@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.2.138", "", { "os": "linux", "cpu": "x64" }, "sha512-T16F8Vkikb98E781ZM6Cx84yEBk+loSCqAObjaZ1hzQ1eKcpnxzSTF4rH2bz6N91dhFuCfIjFaBfNYg+oQA+yQ=="],

-    "@anthropic-ai/claude-agent-sdk-win32-arm64": ["@anthropic-ai/claude-agent-sdk-win32-arm64@0.2.116", "", { "os": "win32", "cpu": "arm64" }, "sha512-h0YO1vkTIeUtffQhONrYbNC1pXmk1yjb1xxMEw7bAwucqtFoFpLDWe+q4+RhxaQr8ZOj6LtRE/U3dzPWHOlshA=="],
+    "@anthropic-ai/claude-agent-sdk-win32-arm64": ["@anthropic-ai/claude-agent-sdk-win32-arm64@0.2.138", "", { "os": "win32", "cpu": "arm64" }, "sha512-H/sD25fmMyEeJWamYmBKRS3E7jaIrg2S8KWxyR37P+xTZgkLe19sDTp7gYYywMXf1X9CJZJ8jJZ93qxINZoCeA=="],

-    "@anthropic-ai/claude-agent-sdk-win32-x64": ["@anthropic-ai/claude-agent-sdk-win32-x64@0.2.116", "", { "os": "win32", "cpu": "x64" }, "sha512-3lllmtDFHgpW0ZM3iNvxsEjblrgRzF9Qm1lxTOtunP3hIn+pA/IkWMtKlN1ixxWiaBguLVQkJ90V6JHsvJJIvw=="],
+    "@anthropic-ai/claude-agent-sdk-win32-x64": ["@anthropic-ai/claude-agent-sdk-win32-x64@0.2.138", "", { "os": "win32", "cpu": "x64" }, "sha512-cSOdTH1OfIamVdJit9laWZiXne81ewgdP8MGh5HzLLLci0NGHkME7YxCWd0lYkCNkfiOEcToKU9axaZ+84jGiw=="],

    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.81.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-D4K5PvEV6wPiRtVlVsJHIUhHAmOZ6IT/I9rKlTf84gR7GyyAurPJK7z9BOf/AZqC5d1DhYQGJNKRmV+q8dGhgw=="],

@@ -9,7 +9,7 @@
    "test": "bun test"
  },
  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.116",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.128",
    "@modelcontextprotocol/sdk": "^1.12.1",
    "cron-parser": "^5.0.0",
    "zod": "^4.0.0"
@@ -0,0 +1,254 @@
+#!/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);
+  }
+
+  // Join all positionals with dashes. The dispatcher trims the last
+  // segment as a target ID if the full name isn't a registered command.
+  const command = positional.join('-');
+
+  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);
+}
@@ -0,0 +1,34 @@
+/**
+ * PreCompact hook script — outputs custom compaction instructions to stdout.
+ *
+ * Claude Code captures the stdout of PreCompact shell hooks and passes it
+ * as `customInstructions` to the compaction prompt. This ensures the
+ * compaction summary preserves message routing context that the agent needs
+ * to correctly address responses.
+ *
+ * Invoked by the PreCompact hook in .claude-shared/settings.json:
+ *   "command": "bun /app/src/compact-instructions.ts"
+ */
+import { getAllDestinations } from './destinations.js';
+
+const destinations = getAllDestinations();
+const names = destinations.map((d) => d.name);
+
+const instructions = [
+  'Preserve the following in the compaction summary:',
+  '',
+  '1. For recent messages, keep the full XML structure including all attributes:',
+  '   - <message from="..." sender="..." time="..."> for chat messages',
+  '   - <task from="..." time="..."> for scheduled tasks',
+  '   - <webhook from="..." source="..." event="..."> for webhooks',
+  '   The message content can be summarized if long, but the XML tags and attributes must remain.',
+  '',
+  '2. Preserve the chronological message/reply sequence of recent exchanges.',
+  '   The agent needs to see: who said what, in what order, and from which destination.',
+  '',
+  '3. At the END of the compaction summary, include this verbatim reminder:',
+  '   "You MUST wrap all responses in <message to="name">...</message> blocks.',
+  `   Available destinations: ${names.length > 0 ? names.map((n) => `\`${n}\``).join(', ') : '(none)'}."`,
+];
+
+console.log(instructions.join('\n'));
@@ -16,6 +16,8 @@ export interface RunnerConfig {
  agentGroupId: string;
  maxMessagesPerPrompt: number;
  mcpServers: Record<string, { command: string; args: string[]; env: Record<string, string> }>;
+  model?: string;
+  effort?: string;
 }

 const DEFAULT_MAX_MESSAGES = 10;
@@ -43,6 +45,8 @@ export function loadConfig(): RunnerConfig {
    agentGroupId: (raw.agentGroupId as string) || '',
    maxMessagesPerPrompt: (raw.maxMessagesPerPrompt as number) || DEFAULT_MAX_MESSAGES,
    mcpServers: (raw.mcpServers as RunnerConfig['mcpServers']) || {},
+    model: (raw.model as string) || undefined,
+    effort: (raw.effort as string) || undefined,
  };

  return _config;
@@ -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;
+}
+
@@ -196,7 +196,8 @@ export function initTestSessionDb(): { inbound: Database; outbound: Database } {
      platform_id    TEXT,
      channel_type   TEXT,
      thread_id      TEXT,
-      content        TEXT NOT NULL
+      content        TEXT NOT NULL,
+      on_wake        INTEGER NOT NULL DEFAULT 0
    );
    CREATE TABLE delivered (
      message_out_id      TEXT PRIMARY KEY,
@@ -10,6 +10,19 @@
 import { getConfig } from '../config.js';
 import { openInboundDb, getOutboundDb } from './connection.js';

+// Cache whether inbound.db has the on_wake column (added in v2.0.48).
+// The container opens inbound.db read-only, so it can't ALTER —
+// gracefully degrade when running against an older session DB.
+let _hasOnWake: boolean | null = null;
+function hasOnWakeColumn(db: ReturnType<typeof openInboundDb>): boolean {
+  if (_hasOnWake !== null) return _hasOnWake;
+  const cols = new Set(
+    (db.prepare("PRAGMA table_info('messages_in')").all() as Array<{ name: string }>).map((c) => c.name),
+  );
+  _hasOnWake = cols.has('on_wake');
+  return _hasOnWake;
+}
+
 export interface MessageInRow {
  id: string;
  seq: number | null;
@@ -49,20 +62,22 @@ function getMaxMessagesPerPrompt(): number {
 * sees the prior context it missed. Host's countDueMessages gates waking on
 * trigger=1 separately (see src/db/session-db.ts).
 */
-export function getPendingMessages(): MessageInRow[] {
+export function getPendingMessages(isFirstPoll = false): MessageInRow[] {
  const inbound = openInboundDb();
  const outbound = getOutboundDb();

  try {
+    const onWakeFilter = hasOnWakeColumn(inbound) ? 'AND (on_wake = 0 OR ?1 = 1)' : '';
    const pending = inbound
      .prepare(
        `SELECT * FROM messages_in
         WHERE status = 'pending'
           AND (process_after IS NULL OR datetime(process_after) <= datetime('now'))
+           ${onWakeFilter}
         ORDER BY seq DESC
-         LIMIT ?`,
+         LIMIT ?2`,
      )
-      .all(getMaxMessagesPerPrompt()) as MessageInRow[];
+      .all(isFirstPoll ? 1 : 0, getMaxMessagesPerPrompt()) as MessageInRow[];

    if (pending.length === 0) return [];

@@ -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 to addressing the destination it came `from`');
+    expect(prompt).toContain('from="name"');
+    expect(prompt).toContain('`casa`');
+    expect(prompt).toContain('`whatsapp-mg-17780`');
+  });
+
+  it('describes message wrapping for a single destination', () => {
+    seedDestination('casa', 'Casa', 'whatsapp', 'group-1@g.us');
+
+    const prompt = buildSystemPromptAddendum('Casa');
+
+    expect(prompt).toContain('Wrap each delivered message');
+    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 to addressing');
+  });
+
+  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('Wrap each delivered message');
+    expect(prompt).toContain('<message to="name">');
+    expect(prompt).toContain('default to addressing the destination it came `from`');
+    expect(prompt).toContain('`casa`');
+  });
+});
@@ -102,34 +102,29 @@ function buildDestinationsSection(): string {
    ].join('\n');
  }

-  // Single-destination shortcut: the agent just writes its response normally.
+  const lines = ['## Sending messages', ''];
  if (all.length === 1) {
    const d = all[0];
    const label = d.displayName && d.displayName !== d.name ? ` (${d.displayName})` : '';
-    return [
-      '## Sending messages',
-      '',
-      `Your messages are delivered to \`${d.name}\`${label}. Just write your response directly — no special wrapping needed.`,
-      '',
-      'To mark something as scratchpad (logged but not sent), wrap it in `<internal>...</internal>`.',
-      '',
-      'To send a message mid-response (e.g., an acknowledgment before a long task), call the `send_message` MCP tool.',
-    ].join('\n');
+    lines.push(`Your destination is \`${d.name}\`${label}.`);
+  } else {
+    lines.push('You can send messages to the following destinations:', '');
+    for (const d of all) {
+      const label = d.displayName && d.displayName !== d.name ? ` (${d.displayName})` : '';
+      lines.push(`- \`${d.name}\`${label}`);
+    }
  }
-
-  const lines = ['## Sending messages', '', 'You can send messages to the following destinations:', ''];
-  for (const d of all) {
-    const label = d.displayName && d.displayName !== d.name ? ` (${d.displayName})` : '';
-    lines.push(`- \`${d.name}\`${label}`);
-  }
-  lines.push('');
-  lines.push('To send a message, wrap it in a `<message to="name">...</message>` block.');
-  lines.push('You can include multiple `<message>` blocks in one response to send to multiple destinations.');
-  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(
-    '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.',
+    'Wrap each delivered message in a `<message to="name">…</message>` block; include several blocks in one response to address several destinations. `<internal>…</internal>` marks thinking you don\'t want sent.',
+  );
+  lines.push('');
+  lines.push(
+    'When replying to an incoming message, default to addressing the destination it came `from` (every inbound `<message>` tag carries a `from="name"` attribute). Pick a different destination when the request asks for it (e.g., "tell Laura that…").',
+  );
+  lines.push('');
+  lines.push(
+    'The `send_message` MCP tool is the same delivery, available mid-turn — handy for a quick acknowledgment ("on it") before a slow tool call. Each `send_message` call and each final-response `<message>` block lands as its own message in the conversation, so they read as a sequence rather than as one combined reply.',
  );
  return lines.join('\n');
 }
@@ -177,40 +177,49 @@ function formatSingleChat(msg: MessageInRow): string {
  const replyPrefix = formatReplyContext(content.replyTo);
  const attachmentsSuffix = formatAttachments(content.attachments);

-  // Look up the destination name for the origin (reverse map lookup).
-  // If not found, fall back to a raw channel:platform_id marker so nothing
-  // gets silently dropped — this should only happen if the destination was
-  // removed between when the message was received and when it's being processed.
-  const fromDest = findByRouting(msg.channel_type, msg.platform_id);
-  const fromAttr = fromDest
-    ? ` from="${escapeXml(fromDest.name)}"`
-    : msg.channel_type || msg.platform_id
-      ? ` from="unknown:${escapeXml(msg.channel_type || '')}:${escapeXml(msg.platform_id || '')}"`
-      : '';
+  const fromAttr = originAttr(msg);

  return `<message${idAttr}${fromAttr} sender="${escapeXml(sender)}" time="${escapeXml(time)}"${replyAttr}>${replyPrefix}${escapeXml(text)}${attachmentsSuffix}</message>`;
 }

+/**
+ * Build a ` from="destination_name"` attribute string from a message's routing
+ * fields. Shared by all formatters so the agent always knows where a message
+ * originated — critical for explicit addressing.
+ */
+function originAttr(msg: MessageInRow): string {
+  const fromDest = findByRouting(msg.channel_type, msg.platform_id);
+  if (fromDest) return ` from="${escapeXml(fromDest.name)}"`;
+  if (msg.channel_type || msg.platform_id) {
+    return ` from="unknown:${escapeXml(msg.channel_type || '')}:${escapeXml(msg.platform_id || '')}"`;
+  }
+  return '';
+}
+
 function formatTaskMessage(msg: MessageInRow): string {
  const content = parseContent(msg.content);
-  const parts = ['[SCHEDULED TASK]'];
+  const from = originAttr(msg);
+  const time = formatLocalTime(msg.timestamp, TIMEZONE);
+  const parts: string[] = [];
  if (content.scriptOutput) {
-    parts.push('', 'Script output:', JSON.stringify(content.scriptOutput, null, 2));
+    parts.push('Script output:', JSON.stringify(content.scriptOutput, null, 2), '');
  }
-  parts.push('', 'Instructions:', content.prompt || '');
-  return parts.join('\n');
+  parts.push('Instructions:', content.prompt || '');
+  return `<task${from} time="${escapeXml(time)}">${parts.join('\n')}</task>`;
 }

 function formatWebhookMessage(msg: MessageInRow): string {
  const content = parseContent(msg.content);
  const source = content.source || 'unknown';
  const event = content.event || 'unknown';
-  return `[WEBHOOK: ${source}/${event}]\n\n${JSON.stringify(content.payload || content, null, 2)}`;
+  const from = originAttr(msg);
+  return `<webhook${from} source="${escapeXml(source)}" event="${escapeXml(event)}">${JSON.stringify(content.payload || content, null, 2)}</webhook>`;
 }

 function formatSystemMessage(msg: MessageInRow): string {
  const content = parseContent(msg.content);
-  return `[SYSTEM RESPONSE]\n\nAction: ${content.action || 'unknown'}\nStatus: ${content.status || 'unknown'}\nResult: ${JSON.stringify(content.result || null)}`;
+  const from = originAttr(msg);
+  return `<system_response${from} action="${escapeXml(content.action || 'unknown')}" status="${escapeXml(content.status || 'unknown')}">${JSON.stringify(content.result || null)}</system_response>`;
 }

 /**
@@ -91,6 +91,8 @@ async function main(): Promise<void> {
    mcpServers,
    env: { ...process.env },
    additionalDirectories: additionalDirectories.length > 0 ? additionalDirectories : undefined,
+    model: config.model,
+    effort: config.effort,
  });

  await runPollLoop({
@@ -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';

@@ -74,6 +75,163 @@ describe('poll loop integration', () => {
    await loopPromise.catch(() => {});
  });

+  it('should resolve thread_id per-destination, not from global routing', async () => {
+    // Seed a second destination
+    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();
+
+    // Insert messages from each destination with distinct thread IDs
+    insertMessage('m-discord', { sender: 'Alice', text: 'from discord' }, { platformId: 'chan-1', channelType: 'discord', threadId: 'discord-thread-1' });
+    insertMessage('m-slack', { sender: 'Bob', text: 'from slack' }, { platformId: 'chan-2', channelType: 'slack', threadId: 'slack-thread-99' });
+
+    // Agent replies to both destinations
+    const provider = new MockProvider({}, () =>
+      '<message to="discord-test">reply-d</message><message to="slack-test">reply-s</message>',
+    );
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length >= 2, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    const discordOut = out.find((m) => m.platform_id === 'chan-1');
+    const slackOut = out.find((m) => m.platform_id === 'chan-2');
+
+    expect(discordOut).toBeDefined();
+    expect(discordOut!.thread_id).toBe('discord-thread-1');
+    expect(discordOut!.in_reply_to).toBe('m-discord');
+
+    expect(slackOut).toBeDefined();
+    expect(slackOut!.thread_id).toBe('slack-thread-99');
+    expect(slackOut!.in_reply_to).toBe('m-slack');
+
+    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();
@@ -91,6 +249,52 @@ 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(() => {});
+  });
+
 });

 // Helper: run poll loop until aborted or timeout
@@ -119,3 +323,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');
+      })(),
+    };
+  }
+}
@@ -0,0 +1,83 @@
+## Admin CLI (`ncl`)
+
+The `ncl` command is available at `/usr/local/bin/ncl`. It lets you query and modify NanoClaw's central configuration.
+
+### Usage
+
+```
+ncl <resource> <verb> [--flags]
+ncl <resource> help
+ncl help
+```
+
+### Scope
+
+Your CLI access may be scoped. Run `ncl help` to see which resources are available and whether args are auto-filled. Under `group` scope (the default), `--id` and group-related args are auto-filled to your agent group — you don't need to pass them.
+
+### Resources
+
+Run `ncl help` for the full list. Common resources:
+
+| Resource | Verbs | What it is |
+|----------|-------|------------|
+| groups | list, get, create, update, delete, restart, config get/update, config add-mcp-server/remove-mcp-server, config add-package/remove-package | Agent groups (workspace, personality, container config) |
+| sessions | list, get | Active sessions (read-only) |
+| destinations | list, add, remove | Where an agent group can send messages |
+| members | list, add, remove | Unprivileged access gate for an agent group |
+
+Additional resources (available under `global` scope only): messaging-groups, wirings, users, roles, user-dms, dropped-messages, approvals.
+
+### When to use
+
+- **Looking up your own config** — `ncl groups get` or `ncl groups config get` to see your container config.
+- **Restarting your container** — `ncl groups restart` (with optional `--rebuild` and `--message`).
+- **Checking who's in your group** — `ncl members list`.
+- **Seeing your destinations** — `ncl destinations list`.
+- **Answering questions about the system** — query `ncl` rather than guessing.
+
+### Access rules
+
+Read commands (list, get) are open. Write commands (create, update, delete, restart, config update, add, remove) require admin approval — the request is held until an admin approves it.
+
+### Approval flow
+
+Write commands require admin approval. Here's what happens:
+
+1. You run the command (e.g. `ncl groups config update --model claude-sonnet-4-5-20250514`).
+2. The command returns immediately with an `approval-pending` response — it has **not** been executed yet.
+3. An admin or owner gets a notification 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 get
+ncl groups config get
+ncl sessions list
+ncl destinations list
+ncl members list
+
+# Write commands (approval required)
+ncl groups restart
+ncl groups restart --rebuild --message "Config updated."
+ncl groups config update --model claude-sonnet-4-5-20250514
+ncl groups config add-mcp-server --name rss --command npx --args '["some-rss-mcp"]'
+ncl groups config add-package --npm some-package
+ncl members add --user telegram:jane
+```
+
+### Important
+
+Config changes via `ncl groups config update` do not take effect until `ncl groups restart`. Run `ncl groups config help` for details.
+
+### Tips
+
+- Use `ncl <resource> help` to see all available fields, types, enums, and which fields are auto-filled.
+- Flags use `--hyphen-case` (e.g. `--agent-group-id`), mapped to `underscore_case` DB columns automatically.
+- `list` supports filtering by any non-auto column. Default limit is 200 rows; override with `--limit N`.
+- Write commands return `approval-pending` immediately — don't treat this as an error. Wait for the system message with the result.
@@ -1,6 +1,6 @@
 ## Sending messages

-Your final response is delivered via the `## Sending messages` rules in your runtime system prompt (single-destination: just write; multi-destination: use `<message to="name">...</message>` blocks). See that section for the current destination list.
+**Every response** must be wrapped in `<message to="name">...</message>` blocks — even if you only have one destination. Bare text outside of `<message>` blocks is scratchpad (logged but never sent). See the `## Sending messages` section in your runtime system prompt for the current destination list and names.

 ### Mid-turn updates (`send_message`)

@@ -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();
+  });
+});
@@ -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,
@@ -22,4 +22,4 @@ Use **`add_mcp_server`** to add an MCP server to your configuration. Browse avai
 add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
 ```

-Do not ask the user to give you credentials. Credentials are managed by the user in the OneCLI agent vault. Add a "placeholder" string instead of the credential, and ask the user to add the credential to the vault. You can make a test request before the secret is added and the vault proxy will respond with the local url of the vault dashboard on the user's machine and a link to a form for adding that specific credential.
+Do not ask the user to give you credentials or tell them how to create credentials (OAuth, API keys, etc.) — NEVER fabricate credential setup instructions. Credentials are handled by the OneCLI gateway. Use `"onecli-managed"` as the placeholder value for any credential env vars or config fields. After the MCP server is installed and the container restarts, load `/onecli-gateway` for the full credential-handling flow (connect URLs, stubs, error recovery).
@@ -14,13 +14,18 @@ afterEach(() => {
  closeSessionDb();
 });

-function insertMessage(id: string, kind: string, content: object, opts?: { processAfter?: string; trigger?: 0 | 1 }) {
+function insertMessage(
+  id: string,
+  kind: string,
+  content: object,
+  opts?: { processAfter?: string; trigger?: 0 | 1; onWake?: 0 | 1 },
+) {
  getInboundDb()
    .prepare(
-      `INSERT INTO messages_in (id, kind, timestamp, status, process_after, trigger, content)
-     VALUES (?, ?, datetime('now'), 'pending', ?, ?, ?)`,
+      `INSERT INTO messages_in (id, kind, timestamp, status, process_after, trigger, on_wake, content)
+     VALUES (?, ?, datetime('now'), 'pending', ?, ?, ?, ?)`,
    )
-    .run(id, kind, opts?.processAfter ?? null, opts?.trigger ?? 1, JSON.stringify(content));
+    .run(id, kind, opts?.processAfter ?? null, opts?.trigger ?? 1, opts?.onWake ?? 0, JSON.stringify(content));
 }

 describe('formatter', () => {
@@ -47,7 +52,7 @@ describe('formatter', () => {
    insertMessage('m1', 'task', { prompt: 'Review open PRs' });
    const messages = getPendingMessages();
    const prompt = formatMessages(messages);
-    expect(prompt).toContain('[SCHEDULED TASK]');
+    expect(prompt).toContain('<task');
    expect(prompt).toContain('Review open PRs');
  });

@@ -55,15 +60,17 @@ describe('formatter', () => {
    insertMessage('m1', 'webhook', { source: 'github', event: 'push', payload: { ref: 'main' } });
    const messages = getPendingMessages();
    const prompt = formatMessages(messages);
-    expect(prompt).toContain('[WEBHOOK: github/push]');
+    expect(prompt).toContain('<webhook');
+    expect(prompt).toContain('source="github"');
+    expect(prompt).toContain('event="push"');
  });

  it('should format system messages', () => {
    insertMessage('m1', 'system', { action: 'register_group', status: 'success', result: { id: 'ag-1' } });
    const messages = getPendingMessages();
    const prompt = formatMessages(messages);
-    expect(prompt).toContain('[SYSTEM RESPONSE]');
-    expect(prompt).toContain('register_group');
+    expect(prompt).toContain('<system_response');
+    expect(prompt).toContain('action="register_group"');
  });

  it('should handle mixed kinds', () => {
@@ -72,7 +79,7 @@ describe('formatter', () => {
    const messages = getPendingMessages();
    const prompt = formatMessages(messages);
    expect(prompt).toContain('sender="John"');
-    expect(prompt).toContain('[SYSTEM RESPONSE]');
+    expect(prompt).toContain('<system_response');
  });

  it('should escape XML in content', () => {
@@ -129,6 +136,58 @@ describe('accumulate gate (trigger column)', () => {
  });
 });

+describe('on_wake filtering', () => {
+  it('first poll returns on_wake=1 messages', () => {
+    insertMessage('m1', 'chat', { sender: 'system', text: 'Resuming.' }, { onWake: 1 });
+    const messages = getPendingMessages(true);
+    expect(messages).toHaveLength(1);
+    expect(messages[0].id).toBe('m1');
+  });
+
+  it('subsequent polls skip on_wake=1 messages', () => {
+    insertMessage('m1', 'chat', { sender: 'system', text: 'Resuming.' }, { onWake: 1 });
+    const messages = getPendingMessages(false);
+    expect(messages).toHaveLength(0);
+  });
+
+  it('normal messages returned regardless of isFirstPoll', () => {
+    insertMessage('m1', 'chat', { sender: 'A', text: 'hello' });
+    expect(getPendingMessages(true)).toHaveLength(1);
+
+    // Reset: mark completed so we can re-test with a fresh message
+    markCompleted(['m1']);
+    insertMessage('m2', 'chat', { sender: 'A', text: 'hello again' });
+    expect(getPendingMessages(false)).toHaveLength(1);
+  });
+
+  it('mixed batch: first poll returns both normal and on_wake messages', () => {
+    insertMessage('m1', 'chat', { sender: 'A', text: 'user msg' });
+    insertMessage('m2', 'chat', { sender: 'system', text: 'Resuming.' }, { onWake: 1 });
+    const messages = getPendingMessages(true);
+    expect(messages).toHaveLength(2);
+    expect(messages.map((m) => m.id).sort()).toEqual(['m1', 'm2']);
+  });
+
+  it('mixed batch: subsequent poll returns only normal messages', () => {
+    insertMessage('m1', 'chat', { sender: 'A', text: 'user msg' });
+    insertMessage('m2', 'chat', { sender: 'system', text: 'Resuming.' }, { onWake: 1 });
+    const messages = getPendingMessages(false);
+    expect(messages).toHaveLength(1);
+    expect(messages[0].id).toBe('m1');
+  });
+
+  it('on_wake defaults to 0 for inserts without explicit value', () => {
+    getInboundDb()
+      .prepare(
+        `INSERT INTO messages_in (id, kind, timestamp, status, content)
+         VALUES ('m1', 'chat', datetime('now'), 'pending', '{"text":"hi"}')`,
+      )
+      .run();
+    // Should be returned even on non-first poll (on_wake=0)
+    expect(getPendingMessages(false)).toHaveLength(1);
+  });
+});
+
 describe('routing', () => {
  it('should extract routing from messages', () => {
    getInboundDb()
@@ -147,6 +206,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}`);
@@ -1,13 +1,18 @@
 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 { touchHeartbeat, clearStaleProcessingAcks } from './db/connection.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;
@@ -62,9 +67,11 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
  clearStaleProcessingAcks();

  let pollCount = 0;
+  let isFirstPoll = true;
  while (true) {
    // Skip system messages — they're responses for MCP tools (e.g., ask_user_question)
-    const messages = getPendingMessages().filter((m) => m.kind !== 'system');
+    const messages = getPendingMessages(isFirstPoll).filter((m) => m.kind !== 'system');
+    isFirstPoll = false;
    pollCount++;

    // Periodic heartbeat so we know the loop is alive
@@ -170,6 +177,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 +208,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
@@ -253,6 +265,7 @@ async function processQuery(
 ): Promise<QueryResult> {
  let queryContinuation: string | undefined;
  let done = false;
+  let unwrappedNudged = false;

  // Concurrent polling: push follow-ups into the active query as they arrive.
  // We do NOT force-end the stream on silence — keeping the query open avoids
@@ -326,6 +339,7 @@ async function processQuery(
        const keptIds = keep.map((m) => m.id);
        const prompt = formatMessages(keep);
        log(`Pushing ${keep.length} follow-up message(s) into active query`);
+        unwrappedNudged = false;
        query.push(prompt);
        markCompleted(keptIds);
      } catch (err) {
@@ -364,7 +378,18 @@ async function processQuery(
        // at all — either way the turn is finished.
        markCompleted(initialBatchIds);
        if (event.text) {
-          dispatchResultText(event.text, routing);
+          const { hasUnwrapped } = dispatchResultText(event.text, routing);
+          if (hasUnwrapped && !unwrappedNudged) {
+            unwrappedNudged = true;
+            const destinations = getAllDestinations();
+            const names = destinations.map((d) => d.name).join(', ');
+            query.push(
+              `<system>Your response was not delivered — it was not wrapped in <message to="name">...</message> blocks. ` +
+                `All output must be wrapped: use <message to="name"> for content to send, or <internal> for scratchpad. ` +
+                `Your destinations: ${names}. ` +
+                `Please re-send your response with the correct wrapping.</system>`,
+            );
+          }
        }
      }
    }
@@ -385,7 +410,9 @@ 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}`);
@@ -396,16 +423,12 @@ function handleEvent(event: ProviderEvent, _routing: RoutingContext): void {
 /**
 * Parse the agent's final text for <message to="name">...</message> blocks
 * and dispatch each one to its resolved destination. Text outside of blocks
- * (including <internal>...</internal>) is normally scratchpad — logged but
- * not sent.
+ * (including <internal>...</internal>) is scratchpad — logged but not sent.
 *
- * Single-destination shortcut: if the agent has exactly one configured
- * destination AND the output contains zero <message> blocks, the entire
- * cleaned text (with <internal> tags stripped) is sent to that destination.
- * This preserves the simple case of one user on one channel — the agent
- * doesn't need to know about wrapping syntax at all.
+ * The agent must always wrap output in <message to="name">...</message>
+ * blocks, even with a single destination. Bare text is scratchpad only.
 */
-function dispatchResultText(text: string, routing: RoutingContext): void {
+function dispatchResultText(text: string, routing: RoutingContext): { sent: number; hasUnwrapped: boolean } {
  const MESSAGE_RE = /<message\s+to="([^"]+)"\s*>([\s\S]*?)<\/message>/g;

  let match: RegExpExecArray | null;
@@ -436,56 +459,60 @@ function dispatchResultText(text: string, routing: RoutingContext): void {

  const scratchpad = stripInternalTags(scratchpadParts.join(''));

-  // Single-destination shortcut: the agent wrote plain text — send to
-  // the session's originating channel (from session_routing) if available,
-  // otherwise fall back to the single destination.
-  if (sent === 0 && scratchpad) {
-    if (routing.channelType && routing.platformId) {
-      // Reply to the channel/thread the message came from
-      writeMessageOut({
-        id: generateId(),
-        in_reply_to: routing.inReplyTo,
-        kind: 'chat',
-        platform_id: routing.platformId,
-        channel_type: routing.channelType,
-        thread_id: routing.threadId,
-        content: JSON.stringify({ text: scratchpad }),
-      });
-      return;
-    }
-    const all = getAllDestinations();
-    if (all.length === 1) {
-      sendToDestination(all[0], scratchpad, routing);
-      return;
-    }
-  }
-
  if (scratchpad) {
    log(`[scratchpad] ${scratchpad.slice(0, 500)}${scratchpad.length > 500 ? '…' : ''}`);
  }

-  if (sent === 0 && text.trim()) {
+  const hasUnwrapped = sent === 0 && !!scratchpad;
+  if (hasUnwrapped) {
    log(`WARNING: agent output had no <message to="..."> blocks — nothing was sent`);
  }
+  return { sent, hasUnwrapped };
 }

 function sendToDestination(dest: DestinationEntry, body: string, routing: RoutingContext): void {
  const platformId = dest.type === 'channel' ? dest.platformId! : dest.agentGroupId!;
  const channelType = dest.type === 'channel' ? dest.channelType! : 'agent';
-  // Inherit thread_id from the inbound routing context so replies land in the
-  // same thread the conversation is in. For non-threaded adapters the router
-  // strips thread_id at ingest, so this will already be null.
+  // Resolve thread_id per-destination from the most recent inbound message
+  // that came from this same channel+platform. In agent-shared sessions,
+  // different destinations have different thread contexts — using a single
+  // routing.threadId would stamp one channel's thread onto another.
+  const destRouting = resolveDestinationThread(channelType, platformId);
  writeMessageOut({
    id: generateId(),
-    in_reply_to: routing.inReplyTo,
+    in_reply_to: destRouting?.inReplyTo ?? routing.inReplyTo,
    kind: 'chat',
    platform_id: platformId,
    channel_type: channelType,
-    thread_id: routing.threadId,
+    thread_id: destRouting?.threadId ?? null,
    content: JSON.stringify({ text: body }),
  });
 }

+/**
+ * Find the thread_id and message id from the most recent inbound message
+ * matching the given channel+platform. Returns null if no match found.
+ */
+function resolveDestinationThread(
+  channelType: string,
+  platformId: string,
+): { threadId: string | null; inReplyTo: string | null } | null {
+  try {
+    const db = getInboundDb();
+    const row = db
+      .prepare(
+        `SELECT thread_id, id FROM messages_in
+         WHERE channel_type = ? AND platform_id = ?
+         ORDER BY seq DESC LIMIT 1`,
+      )
+      .get(channelType, platformId) as { thread_id: string | null; id: string } | undefined;
+    if (row) return { threadId: row.thread_id, inReplyTo: row.id };
+  } catch (err) {
+    log(`resolveDestinationThread error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return null;
+}
+
 function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -257,11 +257,15 @@ export class ClaudeProvider implements AgentProvider {
  private mcpServers: Record<string, McpServerConfig>;
  private env: Record<string, string | undefined>;
  private additionalDirectories?: string[];
+  private model?: string;
+  private effort?: string;

  constructor(options: ProviderOptions = {}) {
    this.assistantName = options.assistantName;
    this.mcpServers = options.mcpServers ?? {};
    this.additionalDirectories = options.additionalDirectories;
+    this.model = options.model;
+    this.effort = options.effort;
    this.env = {
      ...(options.env ?? {}),
      CLAUDE_CODE_AUTO_COMPACT_WINDOW,
@@ -293,6 +297,9 @@ export class ClaudeProvider implements AgentProvider {
        ],
        disallowedTools: SDK_DISALLOWED_TOOLS,
        env: this.env,
+        model: this.model,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        effort: this.effort as any,
        permissionMode: 'bypassPermissions',
        allowDangerouslySkipPermissions: true,
        settingSources: ['project', 'user'],
@@ -25,6 +25,16 @@ export interface ProviderOptions {
  mcpServers?: Record<string, McpServerConfig>;
  env?: Record<string, string | undefined>;
  additionalDirectories?: string[];
+  /**
+   * Model alias (`sonnet`, `opus`, `haiku`) or full model ID. Passed through
+   * to the underlying SDK. If omitted, the SDK default is used.
+   */
+  model?: string;
+  /**
+   * Reasoning effort (`'low' | 'medium' | 'high' | 'xhigh' | 'max'`). Passed
+   * through to the underlying SDK. If omitted, the SDK default is used.
+   */
+  effort?: string;
 }

 export interface QueryInput {
@@ -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.
@@ -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`, the error response contains a `connect_url` — you MUST show it to the user as a bare URL on its own line (no angle brackets, no markdown link syntax) so they can click to connect. Run `/onecli-gateway` for the full error-handling flow. Never ask the user for API keys or tokens.
@@ -9,7 +9,7 @@ You've just been connected to a new user. This your time to shine and make a str

 ## What to do

-1. Send a short, warm greeting using `send_message`
+1. Send a short, warm greeting
 2. State your name (from your system prompt / CLAUDE.md)
 3. Signal that you're capable of a lot — but don't list everything upfront. Be intriguing, not encyclopedic
 4. Ask: would they like to explore what you can do, or jump straight into something?
@@ -2,7 +2,7 @@

 ## Structure

-**`qwibitai/nanoclaw`** (upstream) — core engine with skill definitions (`.claude/skills/`). No channel code on `main`.
+**`nanocoai/nanoclaw`** (upstream) — core engine with skill definitions (`.claude/skills/`). No channel code on `main`.

 **Channel forks** (`nanoclaw-whatsapp`, `nanoclaw-telegram`, `nanoclaw-slack`, etc.) — each fork = upstream + one channel's code applied. Users clone upstream, then merge a fork into their clone to add a channel.

@@ -10,7 +10,7 @@ Access layer: `src/db/`. Authoritative schema reference: `src/db/schema.ts` (com

 ### 1.1 `agent_groups`

-Agent workspaces. Each maps 1:1 to a `groups/<folder>/` directory containing `CLAUDE.md`, skills, and `container.json`. Container config lives on disk, not in the DB.
+Agent workspaces. Each maps 1:1 to a `groups/<folder>/` directory containing `CLAUDE.md` and skills. Container config lives in `container_configs` (see §1.x below); a `container.json` file is materialized at spawn time for the container runner to read.

 ```sql
 CREATE TABLE agent_groups (
@@ -294,6 +294,32 @@ CREATE TABLE schema_version (
 );
 ```

+### 1.15 `container_configs`
+
+Per-agent-group container runtime config. Source of truth for provider, model, packages, MCP servers, mounts, CLI scope, etc. Materialized to `groups/<folder>/container.json` at spawn time.
+
+```sql
+CREATE TABLE container_configs (
+  agent_group_id         TEXT PRIMARY KEY REFERENCES agent_groups(id) ON DELETE CASCADE,
+  provider               TEXT,
+  model                  TEXT,
+  effort                 TEXT,
+  image_tag              TEXT,
+  assistant_name         TEXT,
+  max_messages_per_prompt INTEGER,
+  skills                 TEXT NOT NULL DEFAULT '"all"',
+  mcp_servers            TEXT NOT NULL DEFAULT '{}',
+  packages_apt           TEXT NOT NULL DEFAULT '[]',
+  packages_npm           TEXT NOT NULL DEFAULT '[]',
+  additional_mounts      TEXT NOT NULL DEFAULT '[]',
+  cli_scope              TEXT NOT NULL DEFAULT 'group',   -- disabled | group | global
+  updated_at             TEXT NOT NULL
+);
+```
+
+- **Readers:** `src/container-config.ts`, `src/container-runner.ts`, `src/cli/dispatch.ts` (scope enforcement), `src/claude-md-compose.ts`
+- **Writers:** `src/db/container-configs.ts`, `src/modules/self-mod/apply.ts`, `src/backfill-container-configs.ts`
+
 ---

 ## 2. Migration system
@@ -313,6 +339,8 @@ Migrations live in `src/db/migrations/`, one file per migration. Runner: `runMig
 | 007 | `007-pending-approvals-title-options.ts` | `ALTER TABLE pending_approvals` add `title`, `options_json` (retrofits DBs created between 003 and 007) |
 | 008 | `008-dropped-messages.ts` | `unregistered_senders` |
 | 009 | `009-drop-pending-credentials.ts` | Drop the defunct `pending_credentials` table |
+| 014 | `014-container-configs.ts` | `container_configs` — per-agent-group container runtime config |
+| 015 | `015-cli-scope.ts` | `ALTER TABLE container_configs ADD COLUMN cli_scope` |

 Numbers 005 and 006 are intentionally absent — migrations were renumbered during early development.

@@ -33,19 +33,22 @@ Every message landing in the session: user chat, scheduled task, recurring task,

 ```sql
 CREATE TABLE messages_in (
-  id            TEXT PRIMARY KEY,
-  seq           INTEGER UNIQUE,           -- EVEN only (host assigns) — see §3
-  kind          TEXT NOT NULL,
-  timestamp     TEXT NOT NULL,
-  status        TEXT DEFAULT 'pending',   -- pending|completed|failed|paused
-  process_after TEXT,
-  recurrence    TEXT,                     -- cron expr for recurring
-  series_id     TEXT,                     -- groups occurrences of a recurring task
-  tries         INTEGER DEFAULT 0,
-  platform_id   TEXT,
-  channel_type  TEXT,
-  thread_id     TEXT,
-  content       TEXT NOT NULL             -- JSON; shape depends on kind
+  id             TEXT PRIMARY KEY,
+  seq            INTEGER UNIQUE,           -- EVEN only (host assigns) — see §3
+  kind           TEXT NOT NULL,
+  timestamp      TEXT NOT NULL,
+  status         TEXT DEFAULT 'pending',   -- pending|completed|failed|paused
+  process_after  TEXT,
+  recurrence     TEXT,                     -- cron expr for recurring
+  series_id      TEXT,                     -- groups occurrences of a recurring task
+  tries          INTEGER DEFAULT 0,
+  trigger        INTEGER NOT NULL DEFAULT 1, -- 0 = context only (don't wake), 1 = wake agent
+  platform_id    TEXT,
+  channel_type   TEXT,
+  thread_id      TEXT,
+  content        TEXT NOT NULL,            -- JSON; shape depends on kind
+  source_session_id TEXT,                  -- agent-to-agent return path
+  on_wake        INTEGER NOT NULL DEFAULT 0 -- 1 = only deliver on container's first poll
 );
 CREATE INDEX idx_messages_in_series ON messages_in(series_id);
 ```
@@ -77,7 +77,7 @@ NanoClaw must live inside the workspace directory — Docker-in-Docker can only
 ```bash
 # Clone to home first (virtiofs can corrupt git pack files during clone)
 cd ~
-git clone https://github.com/qwibitai/nanoclaw.git
+git clone https://github.com/nanocoai/nanoclaw.git

 # Replace with YOUR workspace path (the host path you passed to `docker sandbox create`)
 WORKSPACE=/Users/you/nanoclaw-workspace
@@ -347,7 +347,7 @@ docker sandbox network proxy <sandbox-name> \
 ### Git clone fails with "inflate: data stream error"
 Clone to a non-workspace path first, then move:
 ```bash
-cd ~ && git clone https://github.com/qwibitai/nanoclaw.git && mv nanoclaw /path/to/workspace/nanoclaw
+cd ~ && git clone https://github.com/nanocoai/nanoclaw.git && mv nanoclaw /path/to/workspace/nanoclaw
 ```

 ### WhatsApp QR code doesn't display
@@ -23,7 +23,7 @@ This replaces the previous `skills-engine/` system (three-way file merging, `.na

 ### Repository structure

-The upstream repo (`qwibitai/nanoclaw`) maintains:
+The upstream repo (`nanocoai/nanoclaw`) maintains:

 - `main` — core NanoClaw (no skill code)
 - `skill/discord` — main + Discord integration
@@ -46,7 +46,7 @@ Skills are split into two categories:
 **Feature skills** (in marketplace, installed on demand):
 - `/add-discord`, `/add-telegram`, `/add-slack`, `/add-gmail`, etc.
 - Each has a SKILL.md with setup instructions and a corresponding `skill/*` branch with code
- Live in the marketplace repo (`qwibitai/nanoclaw-skills`)
+- Live in the marketplace repo (`nanocoai/nanoclaw-skills`)

 Users never interact with the marketplace directly. The operational skills `/setup` and `/customize` handle plugin installation transparently:

@@ -78,7 +78,7 @@ NanoClaw's `.claude/settings.json` registers the official marketplace:
    "nanoclaw-skills": {
      "source": {
        "source": "github",
-        "repo": "qwibitai/nanoclaw-skills"
+        "repo": "nanocoai/nanoclaw-skills"
      }
    }
  }
@@ -88,7 +88,7 @@ NanoClaw's `.claude/settings.json` registers the official marketplace:
 The marketplace repo uses Claude Code's plugin structure:

 ```
-qwibitai/nanoclaw-skills/
+nanocoai/nanoclaw-skills/
  .claude-plugin/
    marketplace.json              # Plugin catalog
  plugins/
@@ -213,7 +213,7 @@ A GitHub Action runs on every push to `main`:

 ### New users (recommended)

-1. Fork `qwibitai/nanoclaw` on GitHub (click the Fork button)
+1. Fork `nanocoai/nanoclaw` on GitHub (click the Fork button)
 2. Clone your fork:
   ```bash
   git clone https://github.com/<you>/nanoclaw.git
@@ -229,9 +229,9 @@ Forking is recommended because it gives users a remote to push their customizati

 ### Existing users migrating from clone

-Users who previously ran `git clone https://github.com/qwibitai/nanoclaw.git` and have local customizations:
+Users who previously ran `git clone https://github.com/nanocoai/nanoclaw.git` and have local customizations:

-1. Fork `qwibitai/nanoclaw` on GitHub
+1. Fork `nanocoai/nanoclaw` on GitHub
 2. Reroute remotes:
   ```bash
   git remote rename origin upstream
@@ -239,7 +239,7 @@ Users who previously ran `git clone https://github.com/qwibitai/nanoclaw.git` an
   git push --force origin main
   ```
   The `--force` is needed because the fresh fork's main is at upstream's latest, but the user wants their (possibly behind) version. The fork was just created so there's nothing to lose.
-3. From this point, `origin` = their fork, `upstream` = qwibitai/nanoclaw
+3. From this point, `origin` = their fork, `upstream` = nanocoai/nanoclaw

 ### Existing users migrating from the old skills engine

@@ -316,7 +316,7 @@ git fetch upstream main
 git checkout -b my-fix upstream/main
 # Make changes
 git push origin my-fix
-# Create PR from my-fix to qwibitai/nanoclaw:main
+# Create PR from my-fix to nanocoai/nanoclaw:main
 ```

 Standard fork contribution workflow. Their custom changes stay on their main and don't leak into the PR.
@@ -327,7 +327,7 @@ The flow below is for **feature skills** (branch-based). For utility skills (sel

 ### Contributor flow (feature skills)

-1. Fork `qwibitai/nanoclaw`
+1. Fork `nanocoai/nanoclaw`
 2. Branch from `main`
 3. Make the code changes (new channel file, modified integration points, updated package.json, .env.example additions, etc.)
 4. Open a PR to `main`
@@ -345,7 +345,7 @@ When a skill PR is reviewed and approved:
   ```
 2. Force-push to the contributor's PR branch, replacing it with a single commit that adds the contributor to `CONTRIBUTORS.md` (removing all code changes)
 3. Merge the slimmed PR into `main` (just the contributor addition)
-4. Add the skill's SKILL.md to the marketplace repo (`qwibitai/nanoclaw-skills`)
+4. Add the skill's SKILL.md to the marketplace repo (`nanocoai/nanoclaw-skills`)

 This way:
 - The contributor gets merge credit (their PR is merged)
@@ -388,7 +388,7 @@ If the community contributor is trusted, they can open a PR to add their marketp
    "nanoclaw-skills": {
      "source": {
        "source": "github",
-        "repo": "qwibitai/nanoclaw-skills"
+        "repo": "nanocoai/nanoclaw-skills"
      }
    },
    "alice-nanoclaw-skills": {
@@ -434,7 +434,7 @@ A flavor is a curated fork of NanoClaw — a combination of skills, custom chang

 ### Creating a flavor

-1. Fork `qwibitai/nanoclaw`
+1. Fork `nanocoai/nanoclaw`
 2. Merge in the skills you want
 3. Make custom changes (trigger word, prompts, integrations, etc.)
 4. Your fork's `main` IS the flavor
@@ -462,7 +462,7 @@ Then setup continues normally (dependencies, auth, container, service).

 After installation, the user's fork has three remotes:
 - `origin` — their fork (push customizations here)
- `upstream` — `qwibitai/nanoclaw` (core updates)
+- `upstream` — `nanocoai/nanoclaw` (core updates)
 - `<flavor-name>` — the flavor fork (flavor updates)

 ### Updating a flavor
@@ -538,14 +538,14 @@ Operational skills (`setup`, `debug`, `update-nanoclaw`, `customize`, `update-sk

 Before:
 ```bash
-git clone https://github.com/qwibitai/NanoClaw.git
+git clone https://github.com/nanocoai/NanoClaw.git
 cd NanoClaw
 claude
 ```

 After:
 ```
-1. Fork qwibitai/nanoclaw on GitHub
+1. Fork nanocoai/nanoclaw on GitHub
 2. git clone https://github.com/<you>/nanoclaw.git
 3. cd nanoclaw
 4. claude
@@ -556,8 +556,8 @@ After:

 Updates to the setup flow:

- Check if `upstream` remote exists; if not, add it: `git remote add upstream https://github.com/qwibitai/nanoclaw.git`
- Check if `origin` points to the user's fork (not qwibitai). If it points to qwibitai, guide them through the fork migration.
+- Check if `upstream` remote exists; if not, add it: `git remote add upstream https://github.com/nanocoai/nanoclaw.git`
+- Check if `origin` points to the user's fork (not nanocoai). If it points to nanocoai, guide them through the fork migration.
 - **Install marketplace plugin:** `claude plugin install nanoclaw-skills@nanoclaw-skills --scope project` — makes all feature skills available (hot-loaded, no restart)
 - **Ask which channels to add:** present channel options (Discord, Telegram, Slack, WhatsApp, Gmail), run corresponding `/add-*` skills for selected channels
 - **Offer dependent skills:** after a channel is set up, offer relevant add-ons (e.g., Agent Swarm after Telegram, voice transcription after WhatsApp)
@@ -573,7 +573,7 @@ Marketplace configuration so the official marketplace is auto-registered:
    "nanoclaw-skills": {
      "source": {
        "source": "github",
-        "repo": "qwibitai/nanoclaw-skills"
+        "repo": "nanocoai/nanoclaw-skills"
      }
    }
  }
@@ -601,7 +601,7 @@ Operational skills (`setup`, `debug`, `update-nanoclaw`, `customize`, `update-sk

 ### New infrastructure

- **Marketplace repo** (`qwibitai/nanoclaw-skills`) — single Claude Code plugin bundling SKILL.md files for all feature skills
+- **Marketplace repo** (`nanocoai/nanoclaw-skills`) — single Claude Code plugin bundling SKILL.md files for all feature skills
 - **CI GitHub Action** — merge-forward `main` into all `skill/*` branches on every push to `main`, using Claude (Haiku) for conflict resolution
 - **`/update-skills` skill** — checks for and applies skill branch updates using git history
 - **`CONTRIBUTORS.md`** — tracks skill contributors
@@ -650,7 +650,7 @@ Users only need to re-merge a skill branch if the skill itself was updated (not
 > **We now recommend forking instead of cloning.** This gives you a remote to push your customizations to.
 >
 > **If you currently have a clone with local changes**, migrate to a fork:
-> 1. Fork `qwibitai/nanoclaw` on GitHub
+> 1. Fork `nanocoai/nanoclaw` on GitHub
 > 2. Run:
 >    ```
 >    git remote rename origin upstream
@@ -668,7 +668,7 @@ Users only need to re-merge a skill branch if the skill itself was updated (not
 > **Contributing skills**
 >
 > To contribute a skill:
-> 1. Fork `qwibitai/nanoclaw`
+> 1. Fork `nanocoai/nanoclaw`
 > 2. Branch from `main` and make your code changes
 > 3. Open a regular PR
 >
@@ -240,7 +240,7 @@ if [ "$(uname -s)" = "Linux" ] && [ "$(id -u)" -eq 0 ]; then
      printf '  %s\n' "$(dim '3. Enable passwordless sudo:    echo "nanoclaw ALL=(ALL) NOPASSWD:ALL" | tee /etc/sudoers.d/nanoclaw')"
      printf '  %s\n' "$(dim '4. Log out:                     exit')"
      printf '  %s\n' "$(dim '5. Log back in as the new user: ssh nanoclaw@your-server')"
-      printf '  %s\n' "$(dim '6. Clone the repo:              git clone https://github.com/qwibitai/nanoclaw.git && cd nanoclaw')"
+      printf '  %s\n' "$(dim '6. Clone the repo:              git clone https://github.com/nanocoai/nanoclaw.git && cd nanoclaw')"
      printf '  %s\n\n' "$(dim '7. Re-run setup:               bash nanoclaw.sh')"
      exit 1
      ;;
@@ -1,10 +1,13 @@
 {
  "name": "nanoclaw",
-  "version": "2.0.33",
+  "version": "2.0.64",
  "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",
@@ -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': {}

@@ -12,7 +12,7 @@ A GitHub Action that calculates the size of your codebase in terms of tokens and
 ## Usage

 ```yaml
- uses: qwibitai/nanoclaw/repo-tokens@v1
+- uses: nanocoai/nanoclaw/repo-tokens@v1
  with:
    include: 'src/**/*.ts'
    exclude: 'src/**/*.test.ts'
@@ -34,7 +34,7 @@ Repos using repo-tokens:

 | Repo | Badge |
 |------|-------|
-| [NanoClaw](https://github.com/qwibitai/NanoClaw) | ![tokens](https://raw.githubusercontent.com/qwibitai/NanoClaw/main/repo-tokens/badge.svg) |
+| [NanoClaw](https://github.com/nanocoai/NanoClaw) | ![tokens](https://raw.githubusercontent.com/nanocoai/NanoClaw/main/repo-tokens/badge.svg) |

 ### Full workflow example

@@ -59,7 +59,7 @@ jobs:
        with:
          python-version: '3.12'

-      - uses: qwibitai/nanoclaw/repo-tokens@v1
+      - uses: nanocoai/nanoclaw/repo-tokens@v1
        id: tokens
        with:
          include: 'src/**/*.ts'
@@ -114,7 +114,7 @@ runs:
        with open(readme_path, "r", encoding="utf-8") as f:
            content = f.read()

-        repo_tokens_url = "https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"
+        repo_tokens_url = "https://github.com/nanocoai/nanoclaw/tree/main/repo-tokens"
        linked_badge = f'<a href="{repo_tokens_url}">{badge}</a>'
        new_content = marker_re.sub(rf"\1{linked_badge}\2", content)

@@ -148,7 +148,7 @@ runs:
            lx = label_w // 2
            vx = label_w + value_w // 2

-            repo_tokens_url = "https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"
+            repo_tokens_url = "https://github.com/nanocoai/nanoclaw/tree/main/repo-tokens"

            svg = f'''<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="{total_w}" height="20" role="img" aria-label="{full_desc}">
          <title>{full_desc}</title>
@@ -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="174k tokens, 87% of context window">
+  <title>174k tokens, 87% 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"/>
@@ -7,7 +7,7 @@
  <clipPath id="r">
    <rect width="90" height="20" rx="3" fill="#fff"/>
  </clipPath>
-  <a xlink:href="https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens">
+  <a xlink:href="https://github.com/nanocoai/nanoclaw/tree/main/repo-tokens">
    <g clip-path="url(#r)">
      <rect width="52" height="20" fill="#555"/>
      <rect x="52" width="38" height="20" fill="#e05d44"/>
@@ -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">174k</text>
+        <text x="71" y="14">174k</text>
      </g>
    </g>
  </a>
@@ -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);
    }
@@ -47,6 +47,7 @@ import { normalizeName } from '../src/modules/agent-to-agent/db/agent-destinatio
 import { addMember } from '../src/modules/permissions/db/agent-group-members.js';
 import { getUserRoles, grantRole } from '../src/modules/permissions/db/user-roles.js';
 import { upsertUser } from '../src/modules/permissions/db/users.js';
+import { updateContainerConfigScalars } from '../src/db/container-configs.js';
 import { initGroupFilesystem } from '../src/group-init.js';
 import { namespacedPlatformId } from '../src/platform-id.js';
 import type { AgentGroup, MessagingGroup } from '../src/types.js';
@@ -231,6 +232,8 @@ async function main(): Promise<void> {
        granted_at: now,
      });
    }
+    // Owner's agent group gets global CLI access
+    updateContainerConfigScalars(ag.id, { cli_scope: 'global' });
  } else if (args.role === 'admin') {
    const alreadyAdmin = existingRoles.some(
      (r) => r.role === 'admin' && r.agent_group_id === ag.id,
@@ -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',
    }),
  );
@@ -290,7 +290,8 @@ async function askOperatorHandle(): Promise<string> {
      "What phone number or email do you iMessage with?",
      "That's where your assistant will send its welcome message.",
      '',
-      k.dim('  • Phone: full E.164, e.g. +15551234567'),
+      k.dim('  • Phone: start with + and your country code, no spaces or dashes'),
+      k.dim('    Example: +14155551234 (country code 1, then 4155551234)'),
      k.dim('  • Email: whatever iMessage recognises (Apple ID, iCloud alias, …)'),
    ].join('\n'),
    'Your iMessage handle',
@@ -146,6 +146,7 @@ async function walkThroughAppCreation(): Promise<'continue' | 'back'> {
      '     • chat:write',
      '     • users:read',
      '     • reactions:write',
+      '     • files:read, files:write',
      '  3. App Home → enable "Messages Tab" and "Allow users to send',
      '     slash commands and messages from the messages tab"',
      '  4. Basic Information → copy the "Signing Secret"',
@@ -317,9 +318,9 @@ async function collectSlackUserId(): Promise<string> {
    [
      "To get your Slack member ID:",
      '',
-      '  1. In Slack, click your profile picture (top right)',
+      '  1. In Slack, click your profile picture (bottom left)',
      '  2. Click "Profile"',
-      '  3. Click the three dots (⋯) → "Copy member ID"',
+      '  3. Click the three dots (⋮) → "Copy member ID"',
    ].join('\n'),
    'Find your Slack user ID',
  );
@@ -6,10 +6,10 @@
 # `upstream`, with `origin` pointing at the user's fork. The channels branch
 # only lives upstream, so a hardcoded `git fetch origin channels` fails for
 # forks. This helper walks `git remote -v`, picks the remote whose URL points
-# at qwibitai/nanoclaw, and prints its name.
+# at nanocoai/nanoclaw, and prints its name.
 #
 # Fallback: if no existing remote matches, add `upstream` pointing at
-# github.com/qwibitai/nanoclaw and return that — keeps forks without an
+# github.com/nanocoai/nanoclaw and return that — keeps forks without an
 # explicit upstream configured working on the first try.
 #
 # Explicit override: set NANOCLAW_CHANNELS_REMOTE=<name> to skip detection.
@@ -23,7 +23,7 @@ resolve_channels_remote() {
  local remote url
  while IFS=$'\t' read -r remote url; do
    case "$url" in
-      *qwibitai/nanoclaw*)
+      *qwibitai/nanoclaw*|*nanocoai/nanoclaw*)
        printf '%s' "$remote"
        return 0
        ;;
@@ -33,6 +33,6 @@ resolve_channels_remote() {
  # No matching remote — add `upstream` and use it. Silent on failure so
  # callers see the eventual `git fetch` error rather than a cryptic
  # remote-add failure.
-  git remote add upstream https://github.com/qwibitai/nanoclaw.git 2>/dev/null || true
+  git remote add upstream https://github.com/nanocoai/nanoclaw.git 2>/dev/null || true
  printf '%s' "upstream"
 }
@@ -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({
@@ -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');
+}
@@ -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
@@ -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 ───────────────────────────────────────────────────
@@ -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.',
@@ -66,7 +66,7 @@ async function getJson<T>(url: string, token: string, fetchImpl: FetchFn): Promi
  const res = await fetchImpl(url, {
    headers: {
      Authorization: `Bot ${token}`,
-      'User-Agent': 'NanoClaw-Migration (https://github.com/qwibitai/nanoclaw, 2.x)',
+      'User-Agent': 'NanoClaw-Migration (https://github.com/nanocoai/nanoclaw, 2.x)',
    },
  });
  if (!res.ok) {
@@ -105,6 +105,7 @@ function writeEnvOnecliUrl(url: string): void {
 // Last-known-good CLI release. Used only if BOTH the upstream installer
 // and the redirect-based version probe fail. Bump deliberately when a
 // new CLI release ships.
+const ONECLI_GATEWAY_VERSION = '1.23.0';
 const ONECLI_CLI_FALLBACK_VERSION = '1.3.0';
 const ONECLI_CLI_REPO = 'onecli/onecli-cli';

@@ -153,7 +154,7 @@ function installOnecli(): { stdout: string; ok: boolean } {
  if (cleanup) stdout += cleanup + '\n';

  // Gateway install (docker-compose based, no rate-limit concerns).
-  const gw = runInstall('curl -fsSL onecli.sh/install | sh');
+  const gw = runInstall(`export ONECLI_VERSION=${ONECLI_GATEWAY_VERSION} && curl -fsSL onecli.sh/install | sh`);
  stdout += gw.stdout;
  if (!gw.ok) {
    log.error('OneCLI gateway install failed', { stderr: gw.stderr });
@@ -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(
@@ -0,0 +1,78 @@
+/**
+ * One-time backfill: seed `container_configs` rows from existing
+ * `groups/<folder>/container.json` files and `agent_groups.agent_provider`.
+ *
+ * Runs after migrations, before channel adapters start. Idempotent — skips
+ * groups that already have a config row.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { GROUPS_DIR } from './config.js';
+import type { McpServerConfig, AdditionalMountConfig } from './container-config.js';
+import { getAllAgentGroups } from './db/agent-groups.js';
+import { getContainerConfig, createContainerConfig } from './db/container-configs.js';
+import { log } from './log.js';
+import type { ContainerConfigRow } from './types.js';
+
+interface LegacyContainerJson {
+  mcpServers?: Record<string, McpServerConfig>;
+  packages?: { apt?: string[]; npm?: string[] };
+  imageTag?: string;
+  additionalMounts?: AdditionalMountConfig[];
+  skills?: string[] | 'all';
+  provider?: string;
+  assistantName?: string;
+  maxMessagesPerPrompt?: number;
+}
+
+export function backfillContainerConfigs(): void {
+  const groups = getAllAgentGroups();
+  let backfilled = 0;
+
+  for (const group of groups) {
+    // Skip if already has a config row
+    if (getContainerConfig(group.id)) continue;
+
+    // Read legacy container.json from disk
+    const filePath = path.join(GROUPS_DIR, group.folder, 'container.json');
+    let legacy: LegacyContainerJson = {};
+    if (fs.existsSync(filePath)) {
+      try {
+        legacy = JSON.parse(fs.readFileSync(filePath, 'utf8')) as LegacyContainerJson;
+      } catch (err) {
+        log.warn('Backfill: failed to parse container.json, using defaults', {
+          folder: group.folder,
+          err: String(err),
+        });
+      }
+    }
+
+    // DB agent_provider wins over file provider (matches old cascade)
+    const provider = group.agent_provider || legacy.provider || null;
+
+    const row: ContainerConfigRow = {
+      agent_group_id: group.id,
+      provider,
+      model: null,
+      effort: null,
+      image_tag: legacy.imageTag ?? null,
+      assistant_name: legacy.assistantName ?? null,
+      max_messages_per_prompt: legacy.maxMessagesPerPrompt ?? null,
+      skills: JSON.stringify(legacy.skills ?? 'all'),
+      mcp_servers: JSON.stringify(legacy.mcpServers ?? {}),
+      packages_apt: JSON.stringify(legacy.packages?.apt ?? []),
+      packages_npm: JSON.stringify(legacy.packages?.npm ?? []),
+      additional_mounts: JSON.stringify(legacy.additionalMounts ?? []),
+      cli_scope: 'group',
+      updated_at: new Date().toISOString(),
+    };
+
+    createContainerConfig(row);
+    backfilled++;
+  }
+
+  if (backfilled > 0) {
+    log.info('Backfilled container_configs from disk', { count: backfilled });
+  }
+}
@@ -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();
@@ -18,7 +18,8 @@ import fs from 'fs';
 import path from 'path';

 import { GROUPS_DIR } from './config.js';
-import { readContainerConfig } from './container-config.js';
+import type { McpServerConfig } from './container-config.js';
+import { getContainerConfig } from './db/container-configs.js';
 import { log } from './log.js';
 import type { AgentGroup } from './types.js';

@@ -54,7 +55,10 @@ export function composeGroupClaudeMd(group: AgentGroup): void {
  }

  // Desired fragment set.
-  const config = readContainerConfig(group.folder);
+  const configRow = getContainerConfig(group.id);
+  const mcpServers: Record<string, McpServerConfig> = configRow
+    ? (JSON.parse(configRow.mcp_servers) as Record<string, McpServerConfig>)
+    : {};
  const desired = new Map<string, { type: 'symlink' | 'inline'; content: string }>();

  // Skill fragments — every skill that ships an `instructions.md`.
@@ -75,13 +79,15 @@ export function composeGroupClaudeMd(group: AgentGroup): void {
  // Built-in module fragments — every MCP tool source file that ships a
  // sibling `<name>.instructions.md`. These describe how the agent should
  // use that module's MCP tools (schedule_task, install_packages, etc.).
-  // Always included — these are built-in, not toggleable.
+  // Skip cli.instructions.md when cli_scope is disabled.
+  const cliDisabled = configRow?.cli_scope === 'disabled';
  const mcpToolsHostDir = path.join(process.cwd(), MCP_TOOLS_HOST_SUBPATH);
  if (fs.existsSync(mcpToolsHostDir)) {
    for (const entry of fs.readdirSync(mcpToolsHostDir)) {
      const match = entry.match(/^(.+)\.instructions\.md$/);
      if (!match) continue;
      const moduleName = match[1];
+      if (moduleName === 'cli' && cliDisabled) continue;
      desired.set(`module-${moduleName}.md`, {
        type: 'symlink',
        content: `${SHARED_MCP_TOOLS_CONTAINER_BASE}/${entry}`,
@@ -91,7 +97,7 @@ export function composeGroupClaudeMd(group: AgentGroup): void {

  // MCP server fragments — inline instructions from container.json for
  // user-added external MCP servers.
-  for (const [name, mcp] of Object.entries(config.mcpServers)) {
+  for (const [name, mcp] of Object.entries(mcpServers)) {
    if (mcp.instructions) {
      desired.set(`mcp-${name}.md`, {
        type: 'inline',
@@ -0,0 +1,112 @@
+/**
+ * `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';
+import { formatTransportError } from './transport-errors.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);
+  }
+
+  // Join all positionals with dashes to form the command name.
+  // If the full name isn't a command, the dispatcher will try trimming
+  // the last segment and using it as the target ID (e.g. `groups get abc`
+  // → command "groups-get", id "abc").
+  const command = positional.join('-');
+
+  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'),
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`ncl: unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(2);
+});
@@ -0,0 +1,137 @@
+/**
+ * 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 { getContainerConfig } from '../../db/container-configs.js';
+import { getResource, getResources } from '../crud.js';
+import type { CallerContext } from '../frame.js';
+import { listCommands, register } from '../registry.js';
+
+const GROUP_SCOPE_RESOURCES = new Set(['groups', 'sessions', 'destinations', 'members']);
+
+function getCliScope(ctx: CallerContext): string | undefined {
+  if (ctx.caller !== 'agent') return undefined;
+  return getContainerConfig(ctx.agentGroupId)?.cli_scope ?? 'group';
+}
+
+register({
+  name: 'help',
+  description: 'List available resources and commands.',
+  access: 'open',
+  parseArgs: () => ({}),
+  handler: async (_args, ctx) => {
+    const cliScope = getCliScope(ctx);
+    let resources = getResources();
+    if (cliScope === 'group') {
+      resources = resources.filter((r) => GROUP_SCOPE_RESOURCES.has(r.plural));
+    }
+    const commands = listCommands().filter((c) => c.access !== 'hidden' && !c.resource);
+
+    const lines: string[] = [];
+
+    if (cliScope === 'group') {
+      lines.push('CLI scope: group (--id and group args are auto-filled to your agent group)');
+      lines.push('');
+    }
+
+    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 (_args, ctx) => {
+          const cliScope = getCliScope(ctx);
+          const lines: string[] = [];
+          lines.push(`${res.plural}: ${res.description}`);
+
+          if (cliScope === 'group' && GROUP_SCOPE_RESOURCES.has(res.plural)) {
+            lines.push('');
+            lines.push('Note: --id and group args are auto-filled to your agent group. You do not need to pass them.');
+          }
+
+          lines.push('');
+
+          // Verbs
+          const idAutoFilled = cliScope === 'group' && (res.plural === 'groups' || res.plural === 'destinations');
+          const idHint = idAutoFilled ? '' : ' <id>';
+          const verbs: string[] = [];
+          if (res.operations.list) verbs.push(`list [open]`);
+          if (res.operations.get) verbs.push(`get${idHint} [open]`);
+          if (res.operations.create) verbs.push(`create [approval]`);
+          if (res.operations.update) verbs.push(`update${idHint} [approval]`);
+          if (res.operations.delete) verbs.push(`delete${idHint} [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
+          const autoFilledFields =
+            cliScope === 'group' ? new Set(['id', 'agent_group_id', 'group']) : new Set<string>();
+          lines.push('Fields:');
+          for (const col of res.columns) {
+            const tags: string[] = [];
+            if (autoFilledFields.has(col.name)) tags.push('auto-filled');
+            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
+    }
+  }
+}
@@ -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();
--- a/Show More
+++ b/Show More