docs: update token count to 181k tokens · 91% of context window

chore: bump version to 2.0.72
Merge pull request #2648 from nanocoai/share-session-command
2026-06-04 10:14:47 +08:00 · 2026-05-31 20:17:59 +00:00 · 2026-05-31 20:17:55 +00:00 · 2026-05-31 23:17:43 +03:00 · 2026-05-30 10:42:36 +03:00 · 2026-05-28 19:41:34 +00:00
31 changed files with 1634 additions and 129 deletions
@@ -75,7 +75,7 @@ Stop and wait for the user to confirm before continuing.

 ### Remote Mode (Photon API)

-1. Set up a [Photon](https://photon.im) account
+1. Set up a [Photon](https://photon.codes) account
 2. Get your server URL and API key

 ### Configure environment
@@ -0,0 +1,140 @@
+---
+name: add-rtk
+description: Install rtk token-compression proxy into agent containers. Routes Bash tool calls through rtk for 60–90% token savings on dev commands (git, cargo, pytest, docker, kubectl, etc.).
+---
+
+# Add rtk
+
+Install [rtk](https://github.com/rtk-ai/rtk) — a CLI proxy delivering 60–90% token savings on common dev commands (git, cargo, pytest, docker, kubectl, etc.) — and wire it transparently into agent containers via the Claude Code `PreToolUse` hook.
+
+## What this sets up
+
+- `rtk` binary at `~/.local/bin/rtk` on the host
+- `~/.local/bin/rtk` mounted read-only at `/usr/local/bin/rtk` inside the target agent group's containers
+- `PreToolUse` hook in the agent group's `settings.json` so every Bash call is automatically filtered through rtk — no CLAUDE.md instructions needed
+
+## Step 1 — Install rtk on the host
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+```
+
+If the script put the binary elsewhere, move it:
+
+```bash
+find ~/.local ~/.cargo/bin ~/bin -name rtk 2>/dev/null
+mv "$(which rtk 2>/dev/null)" ~/.local/bin/rtk
+```
+
+Verify:
+
+```bash
+~/.local/bin/rtk --version
+chmod +x ~/.local/bin/rtk   # if needed
+```
+
+## Step 2 — Identify the target agent group
+
+```bash
+ncl groups list
+```
+
+Note the group ID (e.g. `ag-1776342942165-ptgddd`). Repeat Steps 3–5 for each group.
+
+## Step 3 — Mount rtk into the container config
+
+`additional_mounts` is a JSON column not exposed via `ncl config update`. Update it directly via the DB helper, merging with any existing mounts.
+
+Read current mounts first:
+
+```bash
+pnpm exec tsx scripts/q.ts data/v2.db \
+  "SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
+```
+
+Then write the merged array (include all existing entries plus the rtk entry):
+
+```bash
+pnpm exec tsx scripts/q.ts data/v2.db \
+  "UPDATE container_configs SET additional_mounts = '<merged-json>' WHERE agent_group_id = '<group-id>'"
+```
+
+The rtk entry to append: `{"hostPath":"/home/<user>/.local/bin/rtk","containerPath":"/usr/local/bin/rtk","readonly":true}`
+
+Verify:
+
+```bash
+pnpm exec tsx scripts/q.ts data/v2.db \
+  "SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
+```
+
+## Step 4 — Add the PreToolUse hook to settings.json
+
+Each agent group has a `settings.json` at:
+
+```
+data/v2-sessions/<group-id>/.claude-shared/settings.json
+```
+
+This file is mounted at `/home/node/.claude/settings.json` inside the container and is read by Claude Code for hooks, env, and model config.
+
+Add the `PreToolUse` entry using `jq` to merge safely:
+
+```bash
+SETTINGS="data/v2-sessions/<group-id>/.claude-shared/settings.json"
+
+jq '.hooks.PreToolUse = [{"matcher":"Bash","hooks":[{"type":"command","command":"rtk hook claude"}]}]' \
+  "$SETTINGS" > /tmp/rtk-settings.json && mv /tmp/rtk-settings.json "$SETTINGS"
+```
+
+If `PreToolUse` already exists, append instead of overwriting:
+
+```bash
+jq '.hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":"rtk hook claude"}]}]' \
+  "$SETTINGS" > /tmp/rtk-settings.json && mv /tmp/rtk-settings.json "$SETTINGS"
+```
+
+## Step 5 — Restart the container
+
+```bash
+ncl groups restart --id <group-id>
+```
+
+No `--message` needed — the hook is transparent and requires no agent awareness.
+
+## Verify
+
+Ask the agent to run `git status` or any other supported command. rtk intercepts it silently. Check savings with:
+
+```bash
+~/.local/bin/rtk gain
+```
+
+## Troubleshooting
+
+### `rtk: command not found` inside the container
+
+Mount wasn't applied or container wasn't restarted:
+
+```bash
+pnpm exec tsx scripts/q.ts data/v2.db \
+  "SELECT additional_mounts FROM container_configs WHERE agent_group_id = '<group-id>'"
+# Look for entry with /usr/local/bin/rtk
+ncl groups restart --id <group-id>
+```
+
+### Hook not firing
+
+Verify the hook is in `settings.json`:
+
+```bash
+jq '.hooks.PreToolUse' data/v2-sessions/<group-id>/.claude-shared/settings.json
+```
+
+If missing, re-run Step 4.
+
+### Binary won't execute — permission denied
+
+```bash
+chmod +x ~/.local/bin/rtk
+```
@@ -55,6 +55,47 @@ pnpm run build

 ## Credentials

+Two paths — manual (Azure Portal) or auto (Teams CLI).
+
+### Auto: Teams CLI
+
+Requires Node.js 18+, a Microsoft 365 account with sideloading permissions, and a public HTTPS endpoint (ngrok, Cloudflare Tunnel, or similar).
+
+1. Install the CLI:
+
+   ```bash
+   npm install -g @microsoft/teams.cli@preview
+   ```
+
+2. Sign in and verify:
+
+   ```bash
+   teams login
+   teams status
+   ```
+
+3. Create the Entra app, client secret, and bot registration:
+
+   ```bash
+   teams app create \
+     --name "NanoClaw" \
+     --endpoint "https://your-domain/api/webhooks/teams"
+   ```
+
+   The CLI prints the credentials as `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID`. Map them to NanoClaw's env keys:
+
+   - `CLIENT_ID` → `TEAMS_APP_ID`
+   - `CLIENT_SECRET` → `TEAMS_APP_PASSWORD`
+   - `TENANT_ID` → `TEAMS_APP_TENANT_ID`
+
+4. Pick **Install in Teams** from the post-create menu and confirm in the Teams dialog.
+
+Continue to [Configure environment](#configure-environment).
+
+---
+
+The steps below describe the **manual Azure Portal path**.
+
 ### Step 1: Create an Azure AD App Registration

 1. Go to [Azure Portal](https://portal.azure.com) > **App registrations** > **New registration**
@@ -20,6 +20,7 @@ Skip to **Credentials** if all of these are already in place:
 - `setup/whatsapp-auth.ts` and `setup/groups.ts` both exist
 - `setup/index.ts`'s `STEPS` map contains both `'whatsapp-auth':` and `groups:`
 - `@whiskeysockets/baileys`, `qrcode`, `pino` are listed in `package.json` dependencies
+- `.claude/skills/add-whatsapp/scripts/wa-qr-browser.ts` exists (ships with this skill)

 Otherwise continue. Every step below is safe to re-run.

@@ -95,7 +96,7 @@ If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenti
 - **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)

 Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?
- **QR code in browser** (Recommended) - Opens a browser window with a large, scannable QR code
+- **QR code in browser** (Recommended) - Runs a small local HTTP server that renders the rotating QR as a PNG and auto-opens your default browser
 - **Pairing code** - Enter a numeric code on your phone (no camera needed, requires phone number)
 - **QR code in terminal** - Displays QR code in the terminal (can be too small on some displays)

@@ -114,11 +115,13 @@ rm -rf store/auth/
 For QR code in browser (recommended):

 ```bash
-pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts
 ```

 (Bash timeout: 150000ms)

+The wrapper spawns `setup/index.ts --step whatsapp-auth -- --method qr`, parses each rotating QR from its `WHATSAPP_AUTH_QR` status blocks, and serves the current QR as a PNG on a local HTTP server (default port `8765`, falls back to a free port). Flags: `--clean` (wipes `store/auth/` before spawning) and `--port N`.
+
 Tell the user:

 > A browser window will open with a QR code.
@@ -130,11 +133,13 @@ Tell the user:
 For QR code in terminal:

 ```bash
-pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal
+pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr
 ```

 (Bash timeout: 150000ms)

+The setup driver emits each rotating QR as a `WHATSAPP_AUTH_QR` status block; when run directly (not through `setup:auto`) the raw QR string is printed and your terminal must render it as ASCII. If your terminal can't render it readably, use the browser method above.
+
 Tell the user:

 > 1. Open WhatsApp > **Settings** > **Linked Devices** > **Link a Device**
@@ -220,10 +225,10 @@ Not supported (WhatsApp linked device limitation): edit messages, delete message

 ### QR code expired

-QR codes expire after ~60 seconds. Re-run the auth command:
+QR codes expire after ~60 seconds. The browser wrapper rotates automatically as long as it's running; if it was stopped, re-run with `--clean`:

 ```bash
-rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean
 ```

 ### Pairing code not working
@@ -236,10 +241,10 @@ rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --met

 Ensure: digits only (no `+`), phone has internet, WhatsApp is updated.

-If pairing code keeps failing, switch to QR-browser auth instead:
+WhatsApp's pairing-code flow occasionally rejects valid codes with "Couldn't link device — An error happened. Please try again." This is a server-side rejection unrelated to the code itself; we've seen it happen twice in a row on fresh dedicated numbers. If you hit it more than once, switch to QR-browser auth — it has a noticeably higher success rate:

 ```bash
-rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr-browser
+pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean
 ```

 ### "waiting for this message" on reactions
@@ -0,0 +1,246 @@
+/**
+ * scripts/wa-qr-browser.ts — serve WhatsApp pairing QR in the browser.
+ *
+ * Wraps `setup/index.ts --step whatsapp-auth -- --method qr` and renders the
+ * rotating QR string as a PNG in a small local HTTP page. Avoids the unreadable
+ * ASCII terminal QR. macOS / desktop-Linux only — no headless support needed.
+ *
+ * Usage:
+ *   pnpm exec tsx scripts/wa-qr-browser.ts [--clean] [--port 8765]
+ *
+ * --clean   rm -rf store/auth/ before spawning the auth step.
+ * --port N  bind to port N (default 8765, falls back to a free port).
+ */
+import { spawn, exec } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import QRCode from 'qrcode';
+
+type Status = 'waiting' | 'ready' | 'success' | 'failed';
+type State = {
+  qr: string | null;
+  status: Status;
+  error?: string;
+  version: number;
+};
+
+const state: State = { qr: null, status: 'waiting', version: 0 };
+
+const args = process.argv.slice(2);
+const clean = args.includes('--clean');
+const portIdx = args.indexOf('--port');
+const requestedPort = portIdx >= 0 ? Number(args[portIdx + 1]) : 8765;
+
+if (clean) {
+  fs.rmSync(path.join(process.cwd(), 'store', 'auth'), {
+    recursive: true,
+    force: true,
+  });
+  console.log('[wa-qr-browser] cleaned store/auth/');
+}
+
+function htmlPage(): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>WhatsApp pairing</title>
+  <style>
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+           font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+           background: #0b141a; color: #e9edef; }
+    .card { background: #202c33; padding: 32px 40px; border-radius: 16px;
+            box-shadow: 0 12px 36px rgba(0,0,0,0.4); text-align: center;
+            min-width: 420px; }
+    h1 { font-size: 18px; font-weight: 500; margin: 0 0 20px; color: #aebac1; }
+    .qr-wrap { background: white; padding: 16px; border-radius: 12px;
+               display: inline-block; }
+    #qr { width: 360px; height: 360px; display: block; image-rendering: pixelated; }
+    #status { margin-top: 20px; font-size: 14px; color: #8696a0; min-height: 20px; }
+    #status.ok { color: #00d26a; font-size: 18px; font-weight: 500; }
+    #status.err { color: #ff6b6b; }
+    ol { text-align: left; color: #aebac1; font-size: 13px; line-height: 1.8;
+         margin: 20px 0 0; padding-left: 20px; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Scan with WhatsApp</h1>
+    <div class="qr-wrap"><img id="qr" alt="QR code" /></div>
+    <div id="status">Waiting for QR…</div>
+    <ol>
+      <li>Open WhatsApp on your phone</li>
+      <li>Settings &rarr; Linked Devices &rarr; Link a Device</li>
+      <li>Point the camera at this QR code</li>
+    </ol>
+  </div>
+  <script>
+    let lastVersion = -1;
+    const qr = document.getElementById('qr');
+    const status = document.getElementById('status');
+    async function tick() {
+      try {
+        const r = await fetch('/qr.json', { cache: 'no-store' });
+        const s = await r.json();
+        if (s.status === 'success') {
+          qr.style.display = 'none';
+          status.className = 'ok';
+          status.textContent = '✓ Authenticated!';
+          return;
+        }
+        if (s.status === 'failed') {
+          qr.style.display = 'none';
+          status.className = 'err';
+          status.textContent = '✗ ' + (s.error || 'failed');
+          return;
+        }
+        if (s.qr && s.version !== lastVersion) {
+          lastVersion = s.version;
+          qr.src = '/qr.png?v=' + s.version;
+          status.textContent = 'QR ready — scan within ~20s';
+        }
+      } catch (e) { /* server closing, ignore */ }
+      setTimeout(tick, 1500);
+    }
+    tick();
+  </script>
+</body>
+</html>`;
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = req.url ?? '/';
+  if (url === '/' || url.startsWith('/?')) {
+    res.setHeader('content-type', 'text/html; charset=utf-8');
+    res.end(htmlPage());
+    return;
+  }
+  if (url === '/qr.json') {
+    res.setHeader('content-type', 'application/json');
+    res.setHeader('cache-control', 'no-store');
+    res.end(JSON.stringify(state));
+    return;
+  }
+  if (url.startsWith('/qr.png')) {
+    if (!state.qr) {
+      res.statusCode = 404;
+      res.end();
+      return;
+    }
+    try {
+      const buf = await QRCode.toBuffer(state.qr, { width: 360, margin: 1 });
+      res.setHeader('content-type', 'image/png');
+      res.setHeader('cache-control', 'no-store');
+      res.end(buf);
+    } catch (e) {
+      res.statusCode = 500;
+      res.end(String(e));
+    }
+    return;
+  }
+  res.statusCode = 404;
+  res.end();
+});
+
+function listen(port: number): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE' && port === requestedPort) {
+        server.listen(0, () => {
+          const addr = server.address();
+          if (addr && typeof addr === 'object') resolve(addr.port);
+          else reject(new Error('unexpected address'));
+        });
+      } else {
+        reject(err);
+      }
+    });
+    server.listen(port, () => {
+      const addr = server.address();
+      if (addr && typeof addr === 'object') resolve(addr.port);
+      else reject(new Error('unexpected address'));
+    });
+  });
+}
+
+const port = await listen(requestedPort);
+const url = `http://localhost:${port}`;
+console.log(`[wa-qr-browser] QR server on ${url}`);
+
+const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+exec(`${opener} ${url}`, (err) => {
+  if (err) console.log(`[wa-qr-browser] could not auto-open browser: ${err.message}`);
+  else console.log('[wa-qr-browser] opening browser…');
+});
+
+const child = spawn(
+  'pnpm',
+  ['exec', 'tsx', 'setup/index.ts', '--step', 'whatsapp-auth', '--', '--method', 'qr'],
+  { stdio: ['inherit', 'pipe', 'inherit'] },
+);
+
+let stdoutBuf = '';
+child.stdout.on('data', (chunk: Buffer) => {
+  const text = chunk.toString();
+  process.stdout.write(text);
+  stdoutBuf += text;
+
+  const blockRe = /=== NANOCLAW SETUP: (\w+) ===\n([\s\S]*?)\n=== END ===/g;
+  let m: RegExpExecArray | null;
+  let lastEnd = 0;
+  while ((m = blockRe.exec(stdoutBuf)) !== null) {
+    const [, name, body] = m;
+    const fields: Record<string, string> = {};
+    for (const line of body.split('\n')) {
+      const kv = line.match(/^(\w+):\s*(.*)$/);
+      if (kv) fields[kv[1]] = kv[2];
+    }
+    handleBlock(name, fields);
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd > 0) stdoutBuf = stdoutBuf.slice(lastEnd);
+});
+
+function handleBlock(name: string, fields: Record<string, string>): void {
+  if (name === 'WHATSAPP_AUTH_QR' && fields.QR) {
+    state.qr = fields.QR;
+    state.status = 'ready';
+    state.version++;
+    return;
+  }
+  if (name === 'WHATSAPP_AUTH') {
+    if (fields.STATUS === 'success') {
+      state.status = 'success';
+      console.log('[wa-qr-browser] authenticated');
+      setTimeout(() => server.close(() => process.exit(0)), 3000);
+    } else if (fields.STATUS === 'skipped') {
+      state.status = 'success';
+      state.error = `already authenticated (${fields.REASON ?? 'unknown'})`;
+      console.log(`[wa-qr-browser] ${state.error}`);
+      setTimeout(() => server.close(() => process.exit(0)), 3000);
+    } else if (fields.STATUS === 'failed') {
+      state.status = 'failed';
+      state.error = fields.ERROR ?? 'unknown error';
+      console.error(`[wa-qr-browser] failed: ${state.error}`);
+    }
+  }
+}
+
+child.on('exit', (code) => {
+  if (state.status === 'success') return;
+  if (state.status !== 'failed') {
+    state.status = 'failed';
+    state.error = `auth process exited (code=${code ?? 'null'})`;
+  }
+  setTimeout(() => {
+    server.close(() => process.exit(1));
+  }, 3000);
+});
+
+process.on('SIGINT', () => {
+  console.log('\n[wa-qr-browser] aborting…');
+  child.kill('SIGTERM');
+  server.close(() => process.exit(130));
+});
@@ -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.128
+ARG CLAUDE_CODE_VERSION=2.1.154
 ARG AGENT_BROWSER_VERSION=latest
 ARG VERCEL_VERSION=52.2.1
 ARG BUN_VERSION=1.3.12
@@ -5,8 +5,9 @@
    "": {
      "name": "nanoclaw-agent-runner",
      "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.2.128",
-        "@modelcontextprotocol/sdk": "^1.12.1",
+        "@anthropic-ai/claude-agent-sdk": "^0.3.154",
+        "@anthropic-ai/sdk": "^0.100.0",
+        "@modelcontextprotocol/sdk": "^1.29.0",
        "cron-parser": "^5.0.0",
        "zod": "^4.0.0",
      },
@@ -18,25 +19,25 @@
    },
  },
  "packages": {
-    "@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": ["@anthropic-ai/claude-agent-sdk@0.3.154", "", { "optionalDependencies": { "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.154", "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.154", "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.154", "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.154", "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.154", "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.154", "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.154", "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.154" }, "peerDependencies": { "@anthropic-ai/sdk": ">=0.93.0", "@modelcontextprotocol/sdk": "^1.29.0", "zod": "^4.0.0" } }, "sha512-iEn25urI2QrMPFIhId3h7v/7EG5gsmF7ooe+6EvsAosePeLmpVVerp5nXtHnlmBkMinLecurcPA+OddKw76jYw=="],

-    "@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-arm64": ["@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.154", "", { "os": "darwin", "cpu": "arm64" }, "sha512-oFW3LD5lYrKAU+AKu27Z8hrzqkrh362qQrwi/i3DxGcud9BXUycsXYjShpDj3D3JZu169UzZuSPhx1Wajmbiwg=="],

-    "@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-darwin-x64": ["@anthropic-ai/claude-agent-sdk-darwin-x64@0.3.154", "", { "os": "darwin", "cpu": "x64" }, "sha512-5BgWEueP+cqoctWjZYhCbyltuaV/N2DmKDXD3/69cKaVmJp8XL9OCzlq/HEirA/+Ssjskx6hDUBaOcpuZ3iwQA=="],

-    "@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": ["@anthropic-ai/claude-agent-sdk-linux-arm64@0.3.154", "", { "os": "linux", "cpu": "arm64" }, "sha512-rRkW4SBL3W7zQvKscCIfIGlmoeuTbMV6dXFbPdmpRGvmYZIs79RpzO6xrGBnnhmm+B7znQ9oHAnffi/2FBgJbA=="],

-    "@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-arm64-musl": ["@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.3.154", "", { "os": "linux", "cpu": "arm64" }, "sha512-o2bCQN4Xn3UqCLErC5m4T7u0yYArJYmgFCUFnA6K96DdW2RERvx+gTKXxWuHEBkDO+eMoHLHLxk0u2jGES00Ng=="],

-    "@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": ["@anthropic-ai/claude-agent-sdk-linux-x64@0.3.154", "", { "os": "linux", "cpu": "x64" }, "sha512-GpiFF8Ez6PbM3m0gqtCo/FKM346qyRdP7VhbmJzdnbNKTiiUZ66vDQyEUPZPCG24ZkrG4m96KpRIUwY08rHiNg=="],

-    "@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-linux-x64-musl": ["@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.3.154", "", { "os": "linux", "cpu": "x64" }, "sha512-zA7S8Lm6O4QBsUpbhiOht8BgiXHOBBFUIo8ZLK6r5wAatK3Q44syWVxICeyCnR6wqfnkf3cugCw27ycS6vVgaA=="],

-    "@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-arm64": ["@anthropic-ai/claude-agent-sdk-win32-arm64@0.3.154", "", { "os": "win32", "cpu": "arm64" }, "sha512-cDW1YFbU/PJFlrGXhlAGcbkXt80sEO6WtnH8nN8YHXLn5NWduy2q7o/qC6i8XozgvRGf6t/eMoH7IasGIEDhDw=="],

-    "@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/claude-agent-sdk-win32-x64": ["@anthropic-ai/claude-agent-sdk-win32-x64@0.3.154", "", { "os": "win32", "cpu": "x64" }, "sha512-tSKaIIpL72OPg3WfzZTCIl8OJgcbq4qieu8/fDWjsdeQuari9gQMIuEflFphk9HqNsxpSmDqKi8Sm5mW2V566Q=="],

-    "@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=="],
+    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.100.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-cAm3aXm6qAiHIvHxyIIGd6tVmsD2gDqlc2h0R20ijNUzGgVnIN822bit4mKbF6CkuV7qIrLQIPoAepHEpanrQQ=="],

    "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],

@@ -44,6 +45,8 @@

    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.29.0", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ=="],

+    "@stablelib/base64": ["@stablelib/base64@1.0.1", "", {}, "sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ=="],
+
    "@types/bun": ["@types/bun@1.3.12", "", { "dependencies": { "bun-types": "1.3.12" } }, "sha512-DBv81elK+/VSwXHDlnH3Qduw+KxkTIWi7TXkAeh24zpi5l0B2kUg9Ga3tb4nJaPcOFswflgi/yAvMVBPrxMB+A=="],

    "@types/node": ["@types/node@22.19.17", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-wGdMcf+vPYM6jikpS/qhg6WiqSV/OhG+jeeHT/KlVqxYfD40iYJf9/AE1uQxVWFvU7MipKRkRv8NSHiCGgPr8Q=="],
@@ -108,6 +111,8 @@

    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],

+    "fast-sha256": ["fast-sha256@1.3.0", "", {}, "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ=="],
+
    "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],

    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
@@ -216,6 +221,8 @@

    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],

+    "standardwebhooks": ["standardwebhooks@1.0.0", "", { "dependencies": { "@stablelib/base64": "^1.0.0", "fast-sha256": "^1.3.0" } }, "sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg=="],
+
    "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],

    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
@@ -9,8 +9,9 @@
    "test": "bun test"
  },
  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.128",
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.154",
+    "@anthropic-ai/sdk": "^0.100.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
    "cron-parser": "^5.0.0",
    "zod": "^4.0.0"
  },
@@ -51,14 +51,43 @@ describe('context timezone header', () => {
    expect(result).toContain(`<context timezone="${TIMEZONE}"`);
  });

-  it('header comes before the <messages> block', () => {
+  it('header comes before the first <message> block when multiple are present', () => {
    insertMessage('m1', 'chat', { sender: 'Alice', text: 'one' });
    insertMessage('m2', 'chat', { sender: 'Bob', text: 'two' });
    const result = formatMessages(getPendingMessages());
    const ctxIdx = result.indexOf('<context');
-    const msgsIdx = result.indexOf('<messages>');
+    const firstMsgIdx = result.indexOf('<message ');
    expect(ctxIdx).toBeGreaterThanOrEqual(0);
-    expect(msgsIdx).toBeGreaterThan(ctxIdx);
+    expect(firstMsgIdx).toBeGreaterThan(ctxIdx);
+  });
+});
+
+describe('multi-message chat batches', () => {
+  // Regression guard for #2555: an outer `<messages>` envelope around
+  // multiple chat messages caused the Claude Agent SDK to emit a synthetic
+  // `No response requested.` stub instead of calling the API. Each
+  // `<message>` block is self-contained; concatenating them is enough.
+  it('does NOT wrap multiple chat messages in an outer <messages> envelope', () => {
+    insertMessage('m1', 'chat', { sender: 'Alice', text: 'one' });
+    insertMessage('m2', 'chat', { sender: 'Bob', text: 'two' });
+    const result = formatMessages(getPendingMessages());
+    expect(result).not.toContain('<messages>');
+    expect(result).not.toContain('</messages>');
+  });
+
+  it('emits one <message> block per inbound row, in order', () => {
+    insertMessage('m1', 'chat', { sender: 'Alice', text: 'first' });
+    insertMessage('m2', 'chat', { sender: 'Bob', text: 'second' });
+    insertMessage('m3', 'chat', { sender: 'Carol', text: 'third' });
+    const result = formatMessages(getPendingMessages());
+    const matches = result.match(/<message [^>]*>/g) ?? [];
+    expect(matches.length).toBe(3);
+    const firstIdx = result.indexOf('first');
+    const secondIdx = result.indexOf('second');
+    const thirdIdx = result.indexOf('third');
+    expect(firstIdx).toBeGreaterThan(0);
+    expect(secondIdx).toBeGreaterThan(firstIdx);
+    expect(thirdIdx).toBeGreaterThan(secondIdx);
  });
 });

@@ -11,7 +11,7 @@ import { TIMEZONE, formatLocalTime } from './timezone.js';
 */
 export type CommandCategory = 'admin' | 'filtered' | 'passthrough' | 'none';

-const ADMIN_COMMANDS = new Set(['/remote-control', '/clear', '/compact', '/context', '/cost', '/files']);
+const ADMIN_COMMANDS = new Set(['/remote-control', '/clear', '/compact', '/context', '/cost', '/files', '/upload-trace']);
 const FILTERED_COMMANDS = new Set(['/help', '/login', '/logout', '/doctor', '/config', '/start']);

 export interface CommandInfo {
@@ -155,16 +155,15 @@ export function formatMessages(messages: MessageInRow[]): string {
 }

 function formatChatMessages(messages: MessageInRow[]): string {
-  if (messages.length === 1) {
-    return formatSingleChat(messages[0]);
-  }
-
-  const lines = ['<messages>'];
-  for (const msg of messages) {
-    lines.push(formatSingleChat(msg));
-  }
-  lines.push('</messages>');
-  return lines.join('\n');
+  // Each `<message id="..." from="...">...</message>` block is self-contained;
+  // concatenating them reads to the agent as a sequence of distinct messages.
+  // Earlier revisions wrapped multi-message batches in an outer `<messages>`
+  // envelope, but the Claude Agent SDK responded to that shape with a
+  // synthetic stub (`model: "<synthetic>"`, `content: "No response
+  // requested."`) instead of calling the API — see #2555 for the full trace.
+  // The fix is simply to drop the wrapper; the single-message path (which
+  // already worked) is now just the N=1 case of the same code.
+  return messages.map(formatSingleChat).join('\n');
 }

 function formatSingleChat(msg: MessageInRow): string {
@@ -4,6 +4,7 @@ import { initTestSessionDb, closeSessionDb, getInboundDb, getOutboundDb } from '
 import { getPendingMessages, markCompleted } from './db/messages-in.js';
 import { getUndeliveredMessages } from './db/messages-out.js';
 import { formatMessages, extractRouting } from './formatter.js';
+import { isCorruptionError } from './poll-loop.js';
 import { MockProvider } from './providers/mock.js';

 beforeEach(() => {
@@ -37,13 +38,15 @@ describe('formatter', () => {
    expect(prompt).toContain('Hello world');
  });

-  it('should format multiple chat messages as XML block', () => {
+  it('should format multiple chat messages as distinct <message> blocks', () => {
    insertMessage('m1', 'chat', { sender: 'John', text: 'Hello' });
    insertMessage('m2', 'chat', { sender: 'Jane', text: 'Hi there' });
    const messages = getPendingMessages();
    const prompt = formatMessages(messages);
-    expect(prompt).toContain('<messages>');
-    expect(prompt).toContain('</messages>');
+    // The <messages> envelope was dropped in fe2e881b (#2556) so the SDK calls
+    // the API; each message is now its own self-contained <message> block.
+    expect(prompt).not.toContain('<messages>');
+    expect(prompt.match(/<message /g) ?? []).toHaveLength(2);
    expect(prompt).toContain('sender="John"');
    expect(prompt).toContain('sender="Jane"');
  });
@@ -375,3 +378,20 @@ describe('end-to-end with mock provider', () => {
    expect(outMessages[0].in_reply_to).toBe('m1');
  });
 });
+
+describe('isCorruptionError', () => {
+  it('matches the Docker Desktop macOS torn-read symptom', () => {
+    expect(isCorruptionError('database disk image is malformed')).toBe(true);
+  });
+
+  it('matches wrapped SQLite corruption codes', () => {
+    expect(isCorruptionError('SqliteError: SQLITE_CORRUPT_VTAB: ...')).toBe(true);
+    expect(isCorruptionError('file is not a database')).toBe(true);
+  });
+
+  it('returns false for unrelated errors', () => {
+    expect(isCorruptionError('database is locked')).toBe(false);
+    expect(isCorruptionError('no such table: messages_in')).toBe(false);
+    expect(isCorruptionError('')).toBe(false);
+  });
+});
@@ -13,11 +13,36 @@ import {
  stripInternalTags,
  type RoutingContext,
 } from './formatter.js';
+import { isUploadTraceCommand, uploadTrace } from './upload-trace.js';
 import type { AgentProvider, AgentQuery, ProviderEvent } from './providers/types.js';

 const POLL_INTERVAL_MS = 1000;
 const ACTIVE_POLL_INTERVAL_MS = 500;

+/**
+ * Number of consecutive `database disk image is malformed` errors after which
+ * the follow-up poll gives up and exits the process. At ACTIVE_POLL_INTERVAL_MS
+ * = 500ms this is roughly 5 seconds — long enough to dodge a transient torn
+ * read during a host write, short enough to recover quickly from a poisoned
+ * page cache (host-sweep then respawns with a fresh mount).
+ */
+const CORRUPTION_STREAK_EXIT = 10;
+
+/**
+ * True for SQLite errors that indicate a corrupt READ view — almost always a
+ * cross-mount page-cache coherency issue on Docker Desktop macOS rather than
+ * actual file damage (host-side integrity_check passes). Reopening the DB
+ * handle inside this process does NOT recover; only a fresh container mount
+ * does. Caller's job is to exit so host-sweep respawns the container.
+ */
+export function isCorruptionError(msg: string): boolean {
+  return (
+    msg.includes('database disk image is malformed') ||
+    msg.includes('SQLITE_CORRUPT') ||
+    msg.includes('file is not a database')
+  );
+}
+
 function log(msg: string): void {
  console.error(`[poll-loop] ${msg}`);
 }
@@ -58,6 +83,19 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
  // a Codex thread id never gets handed to Claude or vice versa.
  let continuation: string | undefined = migrateLegacyContinuation(config.providerName);

+  // Before resuming, drop a session whose on-disk transcript has grown too
+  // large/old to cold-resume within the host's idle ceiling. Without this a
+  // long-lived hub keeps trying to reload an ever-growing .jsonl, hangs the
+  // first turn, and gets killed before it can reply (then repeats forever).
+  if (continuation) {
+    const rotateReason = config.provider.maybeRotateContinuation?.(continuation, config.cwd);
+    if (rotateReason) {
+      log(`Rotating session — ${rotateReason}; starting fresh`);
+      clearContinuation(config.providerName);
+      continuation = undefined;
+    }
+  }
+
  if (continuation) {
    log(`Resuming agent session ${continuation}`);
  }
@@ -124,6 +162,19 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
        commandIds.push(msg.id);
        continue;
      }
+      if ((msg.kind === 'chat' || msg.kind === 'chat-sdk') && isUploadTraceCommand(msg)) {
+        log('Uploading session trace to Hugging Face');
+        writeMessageOut({
+          id: generateId(),
+          kind: 'chat',
+          platform_id: routing.platformId,
+          channel_type: routing.channelType,
+          thread_id: routing.threadId,
+          content: JSON.stringify({ text: uploadTrace() }),
+        });
+        commandIds.push(msg.id);
+        continue;
+      }
      normalMessages.push(msg);
    }

@@ -278,6 +329,7 @@ async function processQuery(
  // will kill the container and messages get reset to pending.
  let pollInFlight = false;
  let endedForCommand = false;
+  let corruptionStreak = 0;
  const pollHandle = setInterval(() => {
    if (done || pollInFlight || endedForCommand) return;
    pollInFlight = true;
@@ -349,6 +401,31 @@ async function processQuery(
        // path is not, so it needs its own.
        const errMsg = err instanceof Error ? err.message : String(err);
        log(`Follow-up poll error: ${errMsg}`);
+
+        // Detect SQLite cross-mount corruption (Docker Desktop macOS virtiofs /
+        // gRPC-FUSE coherency bug — the kernel page cache for the inbound.db
+        // bind mount can latch a torn snapshot mid-host-write, after which
+        // every fresh openInboundDb() in this process sees the same broken
+        // view. Reopening inside the container does NOT recover; only a fresh
+        // container mount does. Exit so the host sweep respawns us.
+        if (isCorruptionError(errMsg)) {
+          corruptionStreak += 1;
+          if (corruptionStreak >= CORRUPTION_STREAK_EXIT) {
+            log(
+              `Follow-up poll: ${corruptionStreak} consecutive '${errMsg}' errors — ` +
+                `inbound.db page cache is poisoned. Exiting so host respawns with a fresh mount.`,
+            );
+            // Stop touching the heartbeat so host-sweep stale detection fires
+            // promptly even if exit() races with in-flight async work.
+            done = true;
+            clearInterval(pollHandle);
+            // Defer exit one tick so this log line flushes through Docker's
+            // log driver before the process dies.
+            setTimeout(() => process.exit(75), 100);
+          }
+        } else {
+          corruptionStreak = 0;
+        }
      } finally {
        pollInFlight = false;
      }
@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { ClaudeProvider } from './claude.js';
+
+// maybeRotateContinuation guards the cold-resume failure mode: a long-lived
+// session whose on-disk transcript has grown so large (or old) that the SDK
+// can't reload it before the host's idle ceiling kills the container.
+
+let tmp: string;
+let prevHome: string | undefined;
+let prevConv: string | undefined;
+let prevBytes: string | undefined;
+let prevDays: string | undefined;
+
+const PROJECT_DIR = '-workspace-agent';
+const CWD = '/workspace/agent';
+
+function writeTranscript(sessionId: string, bytes: number, firstTs?: string): string {
+  const dir = path.join(tmp, '.claude', 'projects', PROJECT_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, `${sessionId}.jsonl`);
+  const first =
+    JSON.stringify({
+      type: 'user',
+      timestamp: firstTs ?? new Date().toISOString(),
+      message: { role: 'user', content: 'hello' },
+    }) + '\n';
+  const filler = 'x'.repeat(Math.max(0, bytes - first.length));
+  fs.writeFileSync(p, first + filler);
+  return p;
+}
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-rotate-'));
+  prevHome = process.env.HOME;
+  prevConv = process.env.NANOCLAW_CONVERSATIONS_DIR;
+  prevBytes = process.env.CLAUDE_TRANSCRIPT_ROTATE_BYTES;
+  prevDays = process.env.CLAUDE_TRANSCRIPT_ROTATE_AGE_DAYS;
+  process.env.HOME = tmp;
+  delete process.env.CLAUDE_CONFIG_DIR;
+  process.env.NANOCLAW_CONVERSATIONS_DIR = path.join(tmp, 'conversations');
+});
+
+afterEach(() => {
+  const restore = (k: string, v: string | undefined) => (v === undefined ? delete process.env[k] : (process.env[k] = v));
+  restore('HOME', prevHome);
+  restore('NANOCLAW_CONVERSATIONS_DIR', prevConv);
+  restore('CLAUDE_TRANSCRIPT_ROTATE_BYTES', prevBytes);
+  restore('CLAUDE_TRANSCRIPT_ROTATE_AGE_DAYS', prevDays);
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe('ClaudeProvider.maybeRotateContinuation', () => {
+  it('keeps a small, recent transcript (returns null, leaves file in place)', () => {
+    process.env.CLAUDE_TRANSCRIPT_ROTATE_BYTES = String(1024 * 1024);
+    const p = writeTranscript('sess-small', 4096);
+    const provider = new ClaudeProvider();
+    expect(provider.maybeRotateContinuation('sess-small', CWD)).toBeNull();
+    expect(fs.existsSync(p)).toBe(true);
+  });
+
+  it('rotates an oversized transcript (returns reason, moves the .jsonl aside)', () => {
+    process.env.CLAUDE_TRANSCRIPT_ROTATE_BYTES = String(64 * 1024);
+    const p = writeTranscript('sess-big', 200 * 1024);
+    const provider = new ClaudeProvider();
+    const reason = provider.maybeRotateContinuation('sess-big', CWD);
+    expect(reason).toContain('MB');
+    expect(fs.existsSync(p)).toBe(false); // original moved out of the resume path
+    const dir = path.dirname(p);
+    expect(fs.readdirSync(dir).some((f) => f.startsWith('sess-big.jsonl.rotated-'))).toBe(true);
+  });
+
+  it('rotates an aged transcript even when small', () => {
+    process.env.CLAUDE_TRANSCRIPT_ROTATE_BYTES = String(1024 * 1024);
+    process.env.CLAUDE_TRANSCRIPT_ROTATE_AGE_DAYS = '7';
+    const old = new Date(Date.now() - 10 * 86400_000).toISOString();
+    writeTranscript('sess-old', 2048, old);
+    const provider = new ClaudeProvider();
+    expect(provider.maybeRotateContinuation('sess-old', CWD)).toContain('d');
+  });
+
+  it('returns null for an unknown session id', () => {
+    const provider = new ClaudeProvider();
+    expect(provider.maybeRotateContinuation('does-not-exist', CWD)).toBeNull();
+  });
+});
@@ -1,4 +1,5 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';

 import { query as sdkQuery, type HookCallback, type PreCompactHookInput } from '@anthropic-ai/claude-agent-sdk';
@@ -188,49 +189,126 @@ const postToolUseHook: HookCallback = async () => {
  return { continue: true };
 };

+/**
+ * Read a Claude transcript .jsonl, render a markdown summary, and drop it into
+ * the agent's `conversations/` folder so context survives a compaction or a
+ * session rotation. Best-effort: returns false (and logs) on any failure.
+ */
+function archiveTranscriptFile(transcriptPath: string | undefined, sessionId: string | undefined, assistantName?: string): boolean {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    log('No transcript found for archiving');
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(transcriptPath, 'utf-8');
+    const messages = parseTranscript(content);
+    if (messages.length === 0) return false;
+
+    // Try to get summary from sessions index
+    let summary: string | undefined;
+    const indexPath = path.join(path.dirname(transcriptPath), 'sessions-index.json');
+    if (fs.existsSync(indexPath)) {
+      try {
+        const index = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+        summary = index.entries?.find((e: { sessionId: string; summary?: string }) => e.sessionId === sessionId)?.summary;
+      } catch {
+        /* ignore */
+      }
+    }
+
+    const name = summary
+      ? summary.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50)
+      : `conversation-${new Date().getHours().toString().padStart(2, '0')}${new Date().getMinutes().toString().padStart(2, '0')}`;
+
+    const conversationsDir = process.env.NANOCLAW_CONVERSATIONS_DIR || '/workspace/agent/conversations';
+    fs.mkdirSync(conversationsDir, { recursive: true });
+    const filename = `${new Date().toISOString().split('T')[0]}-${name}.md`;
+    fs.writeFileSync(path.join(conversationsDir, filename), formatTranscriptMarkdown(messages, summary, assistantName));
+    log(`Archived conversation to ${filename}`);
+    return true;
+  } catch (err) {
+    log(`Failed to archive transcript: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+
 function createPreCompactHook(assistantName?: string): HookCallback {
  return async (input) => {
    const preCompact = input as PreCompactHookInput;
-    const { transcript_path: transcriptPath, session_id: sessionId } = preCompact;
-
-    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
-      log('No transcript found for archiving');
-      return {};
-    }
-
-    try {
-      const content = fs.readFileSync(transcriptPath, 'utf-8');
-      const messages = parseTranscript(content);
-      if (messages.length === 0) return {};
-
-      // Try to get summary from sessions index
-      let summary: string | undefined;
-      const indexPath = path.join(path.dirname(transcriptPath), 'sessions-index.json');
-      if (fs.existsSync(indexPath)) {
-        try {
-          const index = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
-          summary = index.entries?.find((e: { sessionId: string; summary?: string }) => e.sessionId === sessionId)?.summary;
-        } catch {
-          /* ignore */
-        }
-      }
-
-      const name = summary
-        ? summary.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50)
-        : `conversation-${new Date().getHours().toString().padStart(2, '0')}${new Date().getMinutes().toString().padStart(2, '0')}`;
-
-      const conversationsDir = '/workspace/agent/conversations';
-      fs.mkdirSync(conversationsDir, { recursive: true });
-      const filename = `${new Date().toISOString().split('T')[0]}-${name}.md`;
-      fs.writeFileSync(path.join(conversationsDir, filename), formatTranscriptMarkdown(messages, summary, assistantName));
-      log(`Archived conversation to ${filename}`);
-    } catch (err) {
-      log(`Failed to archive transcript: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    archiveTranscriptFile(preCompact.transcript_path, preCompact.session_id, assistantName);
    return {};
  };
 }

+// ── Continuation rotation (cold-resume guard) ──
+
+/**
+ * Resume cost is dominated by transcript size. Past this many bytes a fresh
+ * cold container can't reload the .jsonl before the host's 30-min idle ceiling
+ * fires, so the session is dropped and started clean. Operator-overridable.
+ */
+function transcriptRotateBytes(): number {
+  return Number(process.env.CLAUDE_TRANSCRIPT_ROTATE_BYTES) || 12 * 1024 * 1024;
+}
+
+/**
+ * Secondary age trigger, measured from the transcript's first entry. 0 (or a
+ * non-positive value) disables the age check; size alone then governs.
+ */
+function transcriptRotateAgeMs(): number {
+  const raw = process.env.CLAUDE_TRANSCRIPT_ROTATE_AGE_DAYS;
+  if (raw === undefined || raw.trim() === '') return 14 * 86_400_000;
+  const days = Number(raw);
+  if (!Number.isFinite(days)) return 14 * 86_400_000;
+  // Explicit non-positive override disables the age check; size alone governs.
+  return days > 0 ? days * 86_400_000 : Infinity;
+}
+
+function claudeProjectsDir(): string {
+  const base = process.env.CLAUDE_CONFIG_DIR || path.join(process.env.HOME || os.homedir(), '.claude');
+  return path.join(base, 'projects');
+}
+
+/**
+ * Locate the .jsonl backing a session id. The SDK names project dirs by a
+ * mangled cwd; rather than reproduce that convention we scan project dirs for
+ * `<sessionId>.jsonl` (session ids are UUIDs, so this is unambiguous).
+ */
+function findTranscriptPath(sessionId: string): string | null {
+  const projects = claudeProjectsDir();
+  let dirs: string[];
+  try {
+    dirs = fs.readdirSync(projects);
+  } catch {
+    return null;
+  }
+  for (const dir of dirs) {
+    const candidate = path.join(projects, dir, `${sessionId}.jsonl`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Epoch-ms of the first transcript entry, or null if unreadable. */
+function transcriptStartMs(transcriptPath: string): number | null {
+  try {
+    const fd = fs.openSync(transcriptPath, 'r');
+    try {
+      const buf = Buffer.alloc(4096);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      const firstLine = buf.toString('utf-8', 0, n).split('\n', 1)[0];
+      const ts = JSON.parse(firstLine)?.timestamp;
+      const ms = ts ? Date.parse(ts) : NaN;
+      return Number.isNaN(ms) ? null : ms;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
 // ── Provider ──

 /**
@@ -277,6 +355,41 @@ export class ClaudeProvider implements AgentProvider {
    return STALE_SESSION_RE.test(msg);
  }

+  maybeRotateContinuation(continuation: string): string | null {
+    const transcriptPath = findTranscriptPath(continuation);
+    if (!transcriptPath) return null;
+
+    let size: number;
+    try {
+      size = fs.statSync(transcriptPath).size;
+    } catch {
+      return null;
+    }
+
+    const maxBytes = transcriptRotateBytes();
+    const startMs = transcriptStartMs(transcriptPath);
+    const ageMs = startMs === null ? 0 : Date.now() - startMs;
+    const maxAgeMs = transcriptRotateAgeMs();
+
+    let reason: string | null = null;
+    if (size > maxBytes) {
+      reason = `transcript ${(size / 1_048_576).toFixed(1)}MB > ${(maxBytes / 1_048_576).toFixed(0)}MB cap`;
+    } else if (startMs !== null && ageMs > maxAgeMs) {
+      reason = `transcript ${(ageMs / 86_400_000).toFixed(1)}d old > ${(maxAgeMs / 86_400_000).toFixed(0)}d cap`;
+    }
+    if (!reason) return null;
+
+    // Preserve a readable summary, then move the heavy .jsonl out of the
+    // resume path so the SDK starts a fresh session and the disk is reclaimed.
+    archiveTranscriptFile(transcriptPath, continuation, this.assistantName);
+    try {
+      fs.renameSync(transcriptPath, `${transcriptPath}.rotated-${Date.now()}`);
+    } catch (err) {
+      log(`Failed to move rotated transcript aside: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return reason;
+  }
+
  query(input: QueryInput): AgentQuery {
    const stream = new MessageStream();
    stream.push(input.prompt);
@@ -302,7 +415,7 @@ export class ClaudeProvider implements AgentProvider {
        effort: this.effort as any,
        permissionMode: 'bypassPermissions',
        allowDangerouslySkipPermissions: true,
-        settingSources: ['project', 'user'],
+        settingSources: ['project', 'user', 'local'],
        mcpServers: this.mcpServers,
        hooks: {
          PreToolUse: [{ hooks: [preToolUseHook] }],
@@ -14,6 +14,21 @@ export interface AgentProvider {
   * (missing transcript, unknown session, etc.) and should be cleared.
   */
  isSessionInvalid(err: unknown): boolean;
+
+  /**
+   * Optional pre-resume maintenance. Given the stored continuation token,
+   * decide whether its backing transcript has grown too large or too old to
+   * resume cheaply. Return a non-null reason string to tell the caller to drop
+   * the continuation and start a fresh session (the provider archives any
+   * recoverable summary first); return null to keep resuming.
+   *
+   * Guards the cold-resume failure mode: a long-lived hub session accumulates
+   * days of history — including base64 image blocks the agent Read — and the
+   * SDK reloads the whole .jsonl on every resume. Past a threshold the first
+   * turn alone can exceed the host's idle ceiling, so the container is killed
+   * before it ever replies. Providers without an on-disk transcript omit this.
+   */
+  maybeRotateContinuation?(continuation: string, cwd: string): string | null;
 }

 /**
@@ -0,0 +1,84 @@
+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 { getPendingMessages } from './db/messages-in.js';
+import type { MessageInRow } from './db/messages-in.js';
+import { MockProvider } from './providers/mock.js';
+import { runPollLoop } from './poll-loop.js';
+import { isUploadTraceCommand } from './upload-trace.js';
+
+beforeEach(() => {
+  initTestSessionDb();
+});
+
+afterEach(() => {
+  closeSessionDb();
+});
+
+describe('isUploadTraceCommand', () => {
+  const make = (text: unknown) => ({ content: JSON.stringify({ text }) }) as MessageInRow;
+
+  it('matches /upload-trace (case-insensitive, with args)', () => {
+    expect(isUploadTraceCommand(make('/upload-trace'))).toBe(true);
+    expect(isUploadTraceCommand(make('/UPLOAD-TRACE'))).toBe(true);
+    expect(isUploadTraceCommand(make('  /upload-trace now '))).toBe(true);
+  });
+
+  it('does not match other text or commands', () => {
+    expect(isUploadTraceCommand(make('hello'))).toBe(false);
+    expect(isUploadTraceCommand(make('/upload'))).toBe(false);
+    expect(isUploadTraceCommand(make('/clear'))).toBe(false);
+    expect(isUploadTraceCommand({ content: 'not json' } as MessageInRow)).toBe(false);
+  });
+});
+
+describe('poll loop — /upload-trace command', () => {
+  it('handles the command in the runner, writes a status, skips query', async () => {
+    getInboundDb()
+      .prepare(
+        `INSERT INTO messages_in (id, kind, timestamp, status, platform_id, channel_type, content)
+         VALUES ('m-upload-trace', 'chat', datetime('now'), 'pending', 'chan-1', 'discord', ?)`,
+      )
+      .run(JSON.stringify({ text: '/upload-trace' }));
+
+    // If the provider were ever queried it would emit this — asserting its
+    // absence proves the runner intercepted /upload-trace instead of the LLM.
+    const provider = new MockProvider({}, () => '<message to="discord-test">should not run</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 5000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 5000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out).toHaveLength(1);
+    // A status line from uploadTrace() — never the provider's reply.
+    const text = JSON.parse(out[0].content).text as string;
+    expect(text.length).toBeGreaterThan(0);
+    expect(text).not.toBe('should not run');
+
+    // Command message was completed (not left pending).
+    expect(getPendingMessages()).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
+});
+
+async function runPollLoopWithTimeout(provider: MockProvider, signal: AbortSignal, timeoutMs: number): Promise<void> {
+  return Promise.race([
+    runPollLoop({ provider, providerName: 'mock', cwd: '/tmp' }),
+    new Promise<void>((_, reject) => {
+      signal.addEventListener('abort', () => reject(new Error('aborted')));
+    }),
+    new Promise<void>((_, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
+  ]);
+}
+
+async function waitFor(condition: () => boolean, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (!condition()) {
+    if (Date.now() - start > timeoutMs) throw new Error('waitFor timeout');
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
@@ -0,0 +1,142 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { MessageInRow } from './db/messages-in.js';
+
+/**
+ * `/upload-trace` command: upload this session's Claude Code transcript to the user's
+ * own private `{hf_user}/nanoclaw-traces` dataset, browsable in the HF Agent
+ * Trace Viewer. The transcript the Claude provider keeps under
+ * `~/.claude/projects/<dir>/<sessionId>.jsonl` is already in the format the
+ * viewer auto-detects, so this just locates the newest one and pushes it.
+ *
+ * Auth is the OneCLI gateway's job: curl goes out through the injected
+ * HTTPS_PROXY, which adds the user's HF token. We never see the raw token, and
+ * a 401 from `whoami` is our "not signed in" signal.
+ */
+
+/**
+ * Narrow check for /upload-trace — the runner handles this command directly
+ * (no LLM turn). Admin-gated by the host router before it reaches the container.
+ */
+export function isUploadTraceCommand(msg: MessageInRow): boolean {
+  let text = '';
+  try {
+    text = (JSON.parse(msg.content)?.text ?? '').trim();
+  } catch {
+    return false; // non-JSON content is never a command
+  }
+  return text.toLowerCase().startsWith('/upload-trace');
+}
+
+/** Newest Claude Code transcript jsonl (the current session). */
+function newestTranscript(): string | null {
+  const projects = path.join(os.homedir(), '.claude', 'projects');
+  let best: { p: string; m: number } | null = null;
+  let dirs: string[];
+  try {
+    dirs = fs.readdirSync(projects);
+  } catch {
+    return null;
+  }
+  for (const dir of dirs) {
+    let files: string[];
+    try {
+      files = fs.readdirSync(path.join(projects, dir));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (!f.endsWith('.jsonl')) continue;
+      const p = path.join(projects, dir, f);
+      const m = fs.statSync(p).mtimeMs;
+      if (!best || m > best.m) best = { p, m };
+    }
+  }
+  return best?.p ?? null;
+}
+
+function curl(args: string[], input?: string): { ok: boolean; out: string } {
+  const r = spawnSync('curl', args, { input, encoding: 'utf-8' });
+  return { ok: r.status === 0, out: (r.stdout ?? '') + (r.stderr ?? '') };
+}
+
+/** Returns a user-facing status line. Never throws. */
+export function uploadTrace(): string {
+  const file = newestTranscript();
+  if (!file) return 'No transcript to upload for this session yet.';
+
+  const who = curl(['-sf', 'https://huggingface.co/api/whoami-v2']);
+  if (!who.ok) {
+    return [
+      "Can't upload — no Hugging Face token is available to this agent. To set it up:",
+      '',
+      '1. Create a token with WRITE access at https://huggingface.co/settings/tokens',
+      '   (New token → type "Write" → copy it).',
+      '',
+      '2. Add it to the OneCLI vault. Open the dashboard — remotely at https://app.onecli.sh/',
+      '   or on the host at http://127.0.0.1:10254 — then Secrets → New secret,',
+      '   paste the token, and set the host pattern to  huggingface.co',
+      '',
+      '3. Assign it to this agent — new agents start with no secrets attached.',
+      '   In the same dashboard, open this agent and set its secret mode to "all"; or from the host run:',
+      '     onecli agents list                                   # find this agent\'s id',
+      '     onecli agents set-secret-mode --id <agent-id> --mode all',
+      '',
+      'Then run /upload-trace again — no restart needed.',
+    ].join('\n');
+  }
+  let user: string | undefined;
+  try {
+    user = JSON.parse(who.out)?.name;
+  } catch {
+    /* fall through */
+  }
+  if (!user) return 'Could not resolve your Hugging Face username.';
+
+  const repo = `${user}/nanoclaw-traces`;
+  // Idempotent create — ignore failure (already exists / no-op). The
+  // Content-Type header is required: without it curl sends form-encoding and
+  // the Hub rejects the body with 400 (expected string at "name").
+  curl([
+    '-sf',
+    '-X',
+    'POST',
+    'https://huggingface.co/api/repos/create',
+    '-H',
+    'Content-Type: application/json',
+    '-d',
+    JSON.stringify({ type: 'dataset', name: 'nanoclaw-traces', private: true }),
+  ]);
+
+  const content = fs.readFileSync(file).toString('base64');
+  const repoPath = `sessions/${path.basename(file)}`;
+  const ndjson =
+    JSON.stringify({ key: 'header', value: { summary: 'add session trace' } }) +
+    '\n' +
+    JSON.stringify({
+      key: 'file',
+      value: { path: repoPath, encoding: 'base64', content },
+    }) +
+    '\n';
+
+  const commit = curl(
+    [
+      '-sf',
+      '-X',
+      'POST',
+      `https://huggingface.co/api/datasets/${repo}/commit/main`,
+      '-H',
+      'Content-Type: application/x-ndjson',
+      '--data-binary',
+      '@-',
+    ],
+    ndjson,
+  );
+  if (!commit.ok) {
+    return 'Upload to Hugging Face failed (the transcript may be too large for an inline commit).';
+  }
+  return `Uploaded → https://huggingface.co/datasets/${repo}/blob/main/${repoPath}`;
+}
@@ -0,0 +1,61 @@
+---
+name: whatsapp-formatting
+description: Format messages for WhatsApp, including mentions that render as real WhatsApp tags. Use when responding in a WhatsApp conversation (platform_id / chatJid ends with @s.whatsapp.net or @g.us).
+---
+
+# WhatsApp Message Formatting
+
+WhatsApp uses its own lightweight markup and a phone-number-based mention syntax. The host's WhatsApp adapter (Baileys) handles markdown conversion automatically, but **mentions are only protocol-level mentions if you use the right syntax** — otherwise they render as plain text and don't notify the recipient.
+
+## How to detect WhatsApp context
+
+You're in a WhatsApp conversation when any of these are true:
+- The chat JID / platform id ends with `@s.whatsapp.net` (1-on-1 DM)
+- The chat JID / platform id ends with `@g.us` (group)
+- Your inbound message metadata has `chatJid` matching the above
+
+## Mentions — the important part
+
+To tag a user so their name appears **bold and clickable** in WhatsApp and they get a push notification, write the `@` followed by their phone number digits (no `+`, no spaces, no display name):
+
+```
+@15551234567 can you confirm?
+```
+
+The adapter scans your outgoing text for `@<digits>` (5–15 digits, optional leading `+` is stripped) and tells WhatsApp to render them as real mention tags.
+
+**The sender's phone JID is always in your inbound message metadata.** When a user writes to you, inbound `content.sender` looks like `15551234567@s.whatsapp.net`. The part before the `@` is exactly what you put after `@` when tagging them back.
+
+### Wrong vs right
+
+| You write | What recipients see |
+|-----------|---------------------|
+| `@Adam can you...` | Plain text `@Adam`. No tag, no notification. |
+| `@15551234567 can you...` | Bold/blue **@Adam** (or whatever name they're saved as), notification fires. |
+| `@+15551234567 ...` | Same as above — adapter strips the `+`. |
+
+### Picking who to tag
+
+- In a DM, there's no real need to tag the recipient (they already see every message), but tagging still works if you want emphasis.
+- In a group, look at the `participants` / inbound `content.sender` to find the JID of the person you mean. Don't guess from display names — pushNames can collide and are not reliable.
+- If you don't know the JID, just refer to the person by name in plain prose. Don't write `@<name>` — it won't tag and it will look like a tag that failed.
+
+## Text styles
+
+WhatsApp uses single-character delimiters, *not* doubled like standard Markdown.
+
+| Style | Syntax | Renders as |
+|-------|--------|------------|
+| Bold | `*bold*` | **bold** |
+| Italic | `_italic_` | *italic* |
+| Strikethrough | `~strike~` | ~strike~ |
+| Monospace | `` `code` `` | `code` |
+| Block monospace | ```` ```block``` ```` | preformatted block |
+
+The adapter converts standard Markdown (`**bold**`, `[link](url)`, `# heading`) to the WhatsApp-native form automatically, so you don't have to think about it — but be aware that single asterisks become italics, not bold.
+
+## What not to do
+
+- Don't write `<@U123>` (that's Slack), `<@!123>` (Discord), or any other channel's mention syntax.
+- Don't paste a full JID like `@15551234567@s.whatsapp.net` in the text — only the digits before the JID's `@` go after your `@`.
+- Don't try to tag display names. WhatsApp has no display-name-based mention API.
@@ -0,0 +1,19 @@
+## WhatsApp mentions — always use phone digits
+
+When you are replying in a WhatsApp conversation (the inbound message's `chatJid` ends with `@s.whatsapp.net` for a DM or `@g.us` for a group), and you want to tag a person so their name appears **bold and clickable** with a push notification, write `@` followed by their phone-number digits — never the display name.
+
+**The sender's phone JID is in your inbound message metadata** at `content.sender` (e.g. `15551234567@s.whatsapp.net`). The part before the `@` is exactly what you put after `@` when tagging them.
+
+| You write | What recipients see |
+|-----------|---------------------|
+| `@Adam, can you...` | Plain text. No tag, no notification. |
+| `@15551234567, can you...` | Bold/blue **@Adam** (whatever name they're saved as), notification fires. |
+| `@+15551234567 ...` | Same as above — the adapter strips the `+` automatically. |
+
+The host adapter scans your outbound text for `@<5–15 digits>` (with optional leading `+`) and tells WhatsApp to render those as real mention tags. If the digits aren't in the text, the tag doesn't render — no exceptions.
+
+### In groups
+
+Tag the person you're addressing using their JID from inbound metadata (look at the most recent message from them). Don't guess — pushNames collide and aren't reliable.
+
+If you don't know someone's JID, refer to them by name in plain prose. Do not write `@<displayname>` hoping it works.
@@ -1,6 +1,6 @@
 {
  "name": "nanoclaw",
-  "version": "2.0.64",
+  "version": "2.0.72",
  "description": "Personal Claude assistant. Lightweight, secure, customizable.",
  "type": "module",
  "packageManager": "pnpm@10.33.0",
@@ -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="174k tokens, 87% of context window">
-  <title>174k tokens, 87% 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="181k tokens, 91% of context window">
+  <title>181k tokens, 91% of context window</title>
  <linearGradient id="s" x2="0" y2="100%">
    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
    <stop offset="1" stop-opacity=".1"/>
@@ -15,8 +15,8 @@
      <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
        <text aria-hidden="true" x="26" y="15" fill="#010101" fill-opacity=".3">tokens</text>
        <text x="26" y="14">tokens</text>
-        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">174k</text>
-        <text x="71" y="14">174k</text>
+        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">181k</text>
+        <text x="71" y="14">181k</text>
      </g>
    </g>
  </a>
@@ -247,7 +247,7 @@ async function collectRemoteCreds(): Promise<RemoteCreds> {
      "Photon is a separate service that owns an iMessage account and",
      "exposes it over HTTP. NanoClaw will talk to it via its API.",
      '',
-      '  1. Set up a Photon server: https://photon.im',
+      '  1. Set up a Photon server: https://photon.codes',
      '  2. Copy the server URL and API key from your Photon dashboard',
    ].join('\n'),
    'Remote iMessage via Photon',
@@ -70,8 +70,8 @@ export const CONFIG: Entry[] = [
    surface: 'flag+ui',
    group: 'OneCLI',
    type: 'url',
-    default: 'https://app.onecli.sh',
-    placeholder: 'https://app.onecli.sh',
+    default: 'https://api.onecli.sh',
+    placeholder: 'https://api.onecli.sh',
    validate: httpUrl,
  },
  {
@@ -194,7 +194,12 @@ export async function run(args: string[]): Promise<void> {

  // 4. Send onboarding message — only on first wiring, not re-registration
  if (newlyWired) {
-    const { session } = resolveSession(agentGroup.id, messagingGroup.id, null, parsed.sessionMode as 'shared' | 'per-thread' | 'agent-shared');
+    const { session } = resolveSession(
+      agentGroup.id,
+      messagingGroup.id,
+      null,
+      parsed.sessionMode as 'shared' | 'per-thread' | 'agent-shared',
+    );
    writeSessionMessage(agentGroup.id, session.id, {
      id: generateId('onboard'),
      kind: 'task',
@@ -208,40 +213,38 @@ export async function run(args: string[]): Promise<void> {
    log.info('Onboarding message written', { sessionId: session.id, channel: parsed.channel });
  }

-  // 5. Update assistant name in CLAUDE.md files if different from default
+  // 5. Apply assistant name to JUST the group being registered.
+  //
+  // Earlier behavior did a project-wide find-replace of "Andy" across every
+  // `groups/*/CLAUDE.md` and overwrote `.env`'s `ASSISTANT_NAME`, which
+  // caused two real-world problems:
+  //   - registering a second agent (e.g. "Homie") clobbered the unrelated
+  //     primary agent's CLAUDE.md (replacing "Andy" with "Homie" in
+  //     groups/diddyclaw/CLAUDE.md when Diddyclaw was already in place);
+  //   - the global `.env` ASSISTANT_NAME flipped to the most recently-
+  //     registered agent, which then became the install-wide default
+  //     trigger for any *new* group registered without an explicit
+  //     `--assistant-name`.
+  // Both were unintentional global side-effects of a per-agent operation.
+  // Scope is now strictly: only the freshly-registered agent's own
+  // `groups/<folder>/CLAUDE.md`.
  let nameUpdated = false;
  if (parsed.assistantName !== 'Andy') {
-    log.info('Updating assistant name', { from: 'Andy', to: parsed.assistantName });
-
-    const groupsDir = path.join(projectRoot, 'groups');
-    const mdFiles = fs
-      .readdirSync(groupsDir)
-      .map((d) => path.join(groupsDir, d, 'CLAUDE.md'))
-      .filter((f) => fs.existsSync(f));
-
-    for (const mdFile of mdFiles) {
-      let content = fs.readFileSync(mdFile, 'utf-8');
-      content = content.replace(/^# Andy$/m, `# ${parsed.assistantName}`);
-      content = content.replace(/You are Andy/g, `You are ${parsed.assistantName}`);
-      fs.writeFileSync(mdFile, content);
-      log.info('Updated CLAUDE.md', { file: mdFile });
-    }
-
-    // Update .env
-    const envFile = path.join(projectRoot, '.env');
-    if (fs.existsSync(envFile)) {
-      let envContent = fs.readFileSync(envFile, 'utf-8');
-      if (envContent.includes('ASSISTANT_NAME=')) {
-        envContent = envContent.replace(/^ASSISTANT_NAME=.*$/m, `ASSISTANT_NAME="${parsed.assistantName}"`);
-      } else {
-        envContent += `\nASSISTANT_NAME="${parsed.assistantName}"`;
+    const mdFile = path.join(projectRoot, 'groups', parsed.folder, 'CLAUDE.md');
+    if (fs.existsSync(mdFile)) {
+      const before = fs.readFileSync(mdFile, 'utf-8');
+      const after = before
+        .replace(/^# Andy$/m, `# ${parsed.assistantName}`)
+        .replace(/You are Andy/g, `You are ${parsed.assistantName}`);
+      if (after !== before) {
+        fs.writeFileSync(mdFile, after);
+        log.info('Updated assistant name in registered group only', {
+          file: mdFile,
+          to: parsed.assistantName,
+        });
+        nameUpdated = true;
      }
-      fs.writeFileSync(envFile, envContent);
-    } else {
-      fs.writeFileSync(envFile, `ASSISTANT_NAME="${parsed.assistantName}"\n`);
    }
-    log.info('Set ASSISTANT_NAME in .env');
-    nameUpdated = true;
  }

  emitStatus('REGISTER_CHANNEL', {
@@ -36,6 +36,7 @@ const LINK_TIMEOUT_MS = 180_000;
 const DEFAULT_DEVICE_NAME = 'NanoClaw';

 interface SignalAccount {
+  number?: string;
  account?: string;
  registered?: boolean;
 }
@@ -59,7 +60,7 @@ function listAccounts(): string[] {
    const parsed = JSON.parse(res.stdout || '[]') as SignalAccount[];
    return parsed
      .filter((a) => a.registered !== false)
-      .map((a) => a.account ?? '')
+      .map((a) => a.number ?? a.account ?? '')
      .filter(Boolean);
  } catch {
    return [];
@@ -0,0 +1,220 @@
+/**
+ * Regression test for #2525 — `ncl groups delete` must cascade dependent
+ * rows in FK order so the final `DELETE FROM agent_groups` succeeds even
+ * when the group has sessions, destinations, approvals, role grants, etc.
+ *
+ * The bug pre-fix: the generic single-table DELETE handler ran a bare
+ * `DELETE FROM agent_groups WHERE id = ?` which always failed with a
+ * `SQLITE_CONSTRAINT_FOREIGNKEY` when anything pointed at the group.
+ *
+ * The approval handler in `dispatch.ts` re-enters `dispatch()` with
+ * `caller: 'host'` after admin approval, so the test invokes dispatch
+ * with the host caller — same code path a real approval would take.
+ */
+import fs from 'fs';
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+
+vi.mock('../../container-runner.js', () => ({
+  wakeContainer: vi.fn().mockResolvedValue(undefined),
+  isContainerRunning: vi.fn().mockReturnValue(false),
+  getActiveContainerCount: vi.fn().mockReturnValue(0),
+  killContainer: vi.fn(),
+  buildAgentGroupImage: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/nanoclaw-test-cli-groups' };
+});
+
+const TEST_DIR = '/tmp/nanoclaw-test-cli-groups';
+
+import { initTestDb, closeDb, runMigrations, createAgentGroup, getDb } from '../../db/index.js';
+import { createSession } from '../../db/sessions.js';
+import { dispatch } from '../dispatch.js';
+// Side-effect import: registers the `groups-*` commands (including delete).
+import './groups.js';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function count(sql: string, ...params: unknown[]): number {
+  return (
+    getDb()
+      .prepare(sql)
+      .get(...params) as { c: number }
+  ).c;
+}
+
+describe('groups CLI delete cascades dependent rows (#2525)', () => {
+  beforeEach(() => {
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+
+    const db = initTestDb();
+    runMigrations(db);
+  });
+
+  afterEach(() => {
+    closeDb();
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  });
+
+  it('deletes a group with sessions, destinations, approvals, members, roles, and wirings', async () => {
+    const GID = 'ag-victim';
+    const SID = 'sess-victim-1';
+    const MGID = 'mg-1';
+    const UID = 'tg:42';
+
+    createAgentGroup({ id: GID, name: 'victim', folder: 'victim', agent_provider: null, created_at: now() });
+    createSession({
+      id: SID,
+      agent_group_id: GID,
+      messaging_group_id: null,
+      thread_id: null,
+      agent_provider: null,
+      status: 'active',
+      container_status: 'stopped',
+      last_active: null,
+      created_at: now(),
+    });
+
+    const db = getDb();
+
+    // Direct inserts for the dependent tables. Keeps the fixture minimal —
+    // we only need rows that establish FK relationships, not full domain
+    // entities.
+    db.prepare(`INSERT INTO users (id, kind, display_name, created_at) VALUES (?, 'telegram', 'someone', ?)`).run(
+      UID,
+      now(),
+    );
+    db.prepare(
+      `INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
+       VALUES (?, 'telegram', 'tg-1', 'chat', 1, 'strict', ?)`,
+    ).run(MGID, now());
+
+    db.prepare(
+      `INSERT INTO agent_destinations (agent_group_id, local_name, target_type, target_id, created_at)
+       VALUES (?, 'chan', 'channel', ?, ?)`,
+    ).run(GID, MGID, now());
+
+    db.prepare(
+      `INSERT INTO pending_questions (question_id, session_id, message_out_id, title, options_json, created_at)
+       VALUES (?, ?, 'mout-1', 'q', '[]', ?)`,
+    ).run('q-1', SID, now());
+
+    db.prepare(
+      `INSERT INTO pending_approvals (approval_id, session_id, request_id, action, payload, created_at, agent_group_id, status, title, options_json)
+       VALUES (?, ?, 'req-1', 'cli_command', '{}', ?, ?, 'pending', '', '[]')`,
+    ).run('pa-1', SID, now(), GID);
+
+    db.prepare(
+      `INSERT INTO pending_sender_approvals (id, messaging_group_id, agent_group_id, sender_identity, sender_name, original_message, approver_user_id, created_at)
+       VALUES ('psa-1', ?, ?, 'tg:99', 'them', '{}', ?, ?)`,
+    ).run(MGID, GID, UID, now());
+
+    db.prepare(
+      `INSERT INTO pending_channel_approvals (messaging_group_id, agent_group_id, original_message, approver_user_id, created_at)
+       VALUES (?, ?, '{}', ?, ?)`,
+    ).run(MGID, GID, UID, now());
+
+    db.prepare(
+      `INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, engage_mode, sender_scope, ignored_message_policy, session_mode, priority, created_at)
+       VALUES ('mga-1', ?, ?, 'mention', 'all', 'drop', 'shared', 0, ?)`,
+    ).run(MGID, GID, now());
+
+    db.prepare(
+      `INSERT INTO agent_group_members (user_id, agent_group_id, added_by, added_at) VALUES (?, ?, NULL, ?)`,
+    ).run(UID, GID, now());
+
+    db.prepare(
+      `INSERT INTO user_roles (user_id, role, agent_group_id, granted_by, granted_at) VALUES (?, 'admin', ?, NULL, ?)`,
+    ).run(UID, GID, now());
+
+    // Container config row exercises the ON DELETE CASCADE on container_configs.
+    db.prepare(
+      `INSERT INTO container_configs
+         (agent_group_id, provider, model, effort, image_tag, assistant_name, max_messages_per_prompt,
+          skills, mcp_servers, packages_apt, packages_npm, additional_mounts, cli_scope, updated_at)
+       VALUES (?, NULL, NULL, NULL, NULL, NULL, NULL, '"all"', '{}', '[]', '[]', '[]', 'group', ?)`,
+    ).run(GID, now());
+
+    const resp = await dispatch({ id: 'req-del', command: 'groups-delete', args: { id: GID } }, { caller: 'host' });
+
+    expect(resp.ok).toBe(true);
+    const data = (resp as { ok: true; data: { deleted: string; removed: Record<string, number> } }).data;
+    expect(data.deleted).toBe(GID);
+    expect(data.removed).toMatchObject({
+      sessions: 1,
+      pending_questions: 1,
+      pending_approvals: 1,
+      agent_destinations_owned: 1,
+      agent_destinations_pointing: 0,
+      pending_sender_approvals: 1,
+      pending_channel_approvals: 1,
+      messaging_group_agents: 1,
+      agent_group_members: 1,
+      user_roles: 1,
+      container_configs: 1,
+    });
+
+    // The group and every dependent row must be gone.
+    expect(count('SELECT COUNT(*) AS c FROM agent_groups WHERE id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM sessions WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM pending_questions WHERE session_id = ?', SID)).toBe(0);
+    expect(
+      count('SELECT COUNT(*) AS c FROM pending_approvals WHERE agent_group_id = ? OR session_id = ?', GID, SID),
+    ).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM agent_destinations WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM pending_sender_approvals WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM pending_channel_approvals WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM messaging_group_agents WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM agent_group_members WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM user_roles WHERE agent_group_id = ?', GID)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM container_configs WHERE agent_group_id = ?', GID)).toBe(0);
+
+    // Unrelated tables untouched.
+    expect(count('SELECT COUNT(*) AS c FROM users WHERE id = ?', UID)).toBe(1);
+    expect(count('SELECT COUNT(*) AS c FROM messaging_groups WHERE id = ?', MGID)).toBe(1);
+  });
+
+  it('removes polymorphic agent_destinations that point at the deleted group', async () => {
+    const A = 'ag-a';
+    const B = 'ag-b';
+    createAgentGroup({ id: A, name: 'a', folder: 'a', agent_provider: null, created_at: now() });
+    createAgentGroup({ id: B, name: 'b', folder: 'b', agent_provider: null, created_at: now() });
+
+    const db = getDb();
+
+    // B has a destination pointing at A. target_id is polymorphic — no FK
+    // constraint enforces it, so without explicit cleanup the row would
+    // dangle after A is deleted.
+    db.prepare(
+      `INSERT INTO agent_destinations (agent_group_id, local_name, target_type, target_id, created_at)
+       VALUES (?, 'sibling', 'agent', ?, ?)`,
+    ).run(B, A, now());
+
+    const resp = await dispatch({ id: 'req-del-a', command: 'groups-delete', args: { id: A } }, { caller: 'host' });
+
+    expect(resp.ok).toBe(true);
+    const data = (resp as { ok: true; data: { removed: Record<string, number> } }).data;
+    expect(data.removed.agent_destinations_pointing).toBe(1);
+
+    // A is gone, B remains, and B's stale destination is cleaned up.
+    expect(count('SELECT COUNT(*) AS c FROM agent_groups WHERE id = ?', A)).toBe(0);
+    expect(count('SELECT COUNT(*) AS c FROM agent_groups WHERE id = ?', B)).toBe(1);
+    expect(count('SELECT COUNT(*) AS c FROM agent_destinations WHERE agent_group_id = ?', B)).toBe(0);
+  });
+
+  it('returns a handler error for an unknown group id', async () => {
+    const resp = await dispatch(
+      { id: 'req-missing', command: 'groups-delete', args: { id: 'ag-does-not-exist' } },
+      { caller: 'host' },
+    );
+
+    expect(resp.ok).toBe(false);
+    expect((resp as { ok: false; error: { code: string; message: string } }).error.code).toBe('handler-error');
+    expect((resp as { ok: false; error: { code: string; message: string } }).error.message).toMatch(/not found/i);
+  });
+});
@@ -1,6 +1,7 @@
 import type { McpServerConfig } from '../../container-config.js';
 import { buildAgentGroupImage, killContainer, wakeContainer } from '../../container-runner.js';
 import { restartAgentGroupContainers } from '../../container-restart.js';
+import { getDb, hasTable } from '../../db/connection.js';
 import { getSession } from '../../db/sessions.js';
 import { writeSessionMessage } from '../../session-manager.js';
 import {
@@ -57,8 +58,97 @@ registerResource({
    },
    { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
  ],
-  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval', delete: 'approval' },
+  // `delete` is intentionally not in `operations` — the generic single-table
+  // DELETE violates FK constraints (see #2525). The cascading handler is
+  // provided as `customOperations.delete` below.
+  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval' },
  customOperations: {
+    delete: {
+      access: 'approval',
+      description:
+        'Delete an agent group and its dependent rows (sessions, destinations, approvals, role grants, ' +
+        'memberships, channel wirings). FK-ordered cascade in a single transaction. ' +
+        'Use --id <group-id>. Out of scope: killing running containers, on-disk cleanup of groups/<folder>/ and data/v2-sessions/<group-id>/.',
+      handler: async (args) => {
+        const id = args.id as string;
+        if (!id) throw new Error('--id is required');
+        const db = getDb();
+
+        // Verify the group exists before doing anything — preserves the
+        // genericDelete behaviour of throwing "not found" for unknown IDs.
+        const exists = db.prepare('SELECT 1 FROM agent_groups WHERE id = ? LIMIT 1').get(id);
+        if (!exists) throw new Error(`group not found: ${id}`);
+
+        const hasAgentDestinations = hasTable(db, 'agent_destinations');
+        const hasPendingApprovals = hasTable(db, 'pending_approvals');
+
+        // FK-ordered cascade. Single sync transaction — better-sqlite3 rolls
+        // back the whole thing if any statement throws (e.g. an FK constraint
+        // we missed), so the central DB stays consistent. The `removed` counts
+        // are sourced from each DELETE's `changes` so they describe exactly
+        // what the transaction did, not a separate pre-flight snapshot.
+        const cascade = db.transaction((groupId: string) => {
+          const counts = {
+            sessions: 0,
+            pending_questions: 0,
+            pending_approvals: 0,
+            agent_destinations_owned: 0,
+            agent_destinations_pointing: 0,
+            pending_sender_approvals: 0,
+            pending_channel_approvals: 0,
+            messaging_group_agents: 0,
+            agent_group_members: 0,
+            user_roles: 0,
+            container_configs: 0,
+          };
+
+          if (hasAgentDestinations) {
+            counts.agent_destinations_owned = db
+              .prepare('DELETE FROM agent_destinations WHERE agent_group_id = ?')
+              .run(groupId).changes;
+            counts.agent_destinations_pointing = db
+              .prepare('DELETE FROM agent_destinations WHERE target_type = ? AND target_id = ?')
+              .run('agent', groupId).changes;
+          }
+          counts.pending_questions = db
+            .prepare(
+              'DELETE FROM pending_questions WHERE session_id IN (SELECT id FROM sessions WHERE agent_group_id = ?)',
+            )
+            .run(groupId).changes;
+          if (hasPendingApprovals) {
+            counts.pending_approvals = db
+              .prepare(
+                'DELETE FROM pending_approvals WHERE agent_group_id = ? OR session_id IN (SELECT id FROM sessions WHERE agent_group_id = ?)',
+              )
+              .run(groupId, groupId).changes;
+          }
+          counts.sessions = db.prepare('DELETE FROM sessions WHERE agent_group_id = ?').run(groupId).changes;
+          counts.pending_sender_approvals = db
+            .prepare('DELETE FROM pending_sender_approvals WHERE agent_group_id = ?')
+            .run(groupId).changes;
+          counts.pending_channel_approvals = db
+            .prepare('DELETE FROM pending_channel_approvals WHERE agent_group_id = ?')
+            .run(groupId).changes;
+          counts.messaging_group_agents = db
+            .prepare('DELETE FROM messaging_group_agents WHERE agent_group_id = ?')
+            .run(groupId).changes;
+          counts.agent_group_members = db
+            .prepare('DELETE FROM agent_group_members WHERE agent_group_id = ?')
+            .run(groupId).changes;
+          counts.user_roles = db.prepare('DELETE FROM user_roles WHERE agent_group_id = ?').run(groupId).changes;
+          // migration-014 has ON DELETE CASCADE on container_configs.agent_group_id;
+          // the explicit delete here mirrors the other tables and surfaces the count.
+          counts.container_configs = db
+            .prepare('DELETE FROM container_configs WHERE agent_group_id = ?')
+            .run(groupId).changes;
+          db.prepare('DELETE FROM agent_groups WHERE id = ?').run(groupId);
+          return counts;
+        });
+        const removed = cascade(id);
+
+        return { deleted: id, removed };
+      },
+    },
    restart: {
      access: 'approval',
      description:
@@ -12,7 +12,7 @@ import { getDb, hasTable } from './db/connection.js';
 export type GateResult = { action: 'pass' } | { action: 'filter' } | { action: 'deny'; command: string };

 const FILTERED_COMMANDS = new Set(['/help', '/login', '/logout', '/doctor', '/config', '/remote-control']);
-const ADMIN_COMMANDS = new Set(['/clear', '/compact', '/context', '/cost', '/files']);
+const ADMIN_COMMANDS = new Set(['/clear', '/compact', '/context', '/cost', '/files', '/upload-trace']);

 /**
 * Classify a message and decide whether it should reach the container.
@@ -357,6 +357,87 @@ describe('unknown-channel registration flow', () => {
      .c;
    expect(stillPending).toBe(1);
  });
+
+  it('does not let a scoped admin connect an unknown channel to another agent group', async () => {
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+    const { getDb } = await import('../../db/connection.js');
+
+    createAgentGroup({ id: 'ag-2', name: 'Betty', folder: 'betty', agent_provider: null, created_at: now() });
+    upsertUser({ id: 'telegram:scoped-admin', kind: 'telegram', display_name: 'Scoped Admin', created_at: now() });
+    grantRole({
+      user_id: 'telegram:scoped-admin',
+      role: 'admin',
+      agent_group_id: 'ag-1',
+      granted_by: 'telegram:owner',
+      granted_at: now(),
+    });
+    createMessagingGroup({
+      id: 'mg-dm-scoped-admin',
+      channel_type: 'telegram',
+      platform_id: 'dm-scoped-admin',
+      name: 'Scoped Admin DM',
+      is_group: 0,
+      unknown_sender_policy: 'public',
+      created_at: now(),
+    });
+    getDb()
+      .prepare(
+        `INSERT INTO user_dms (user_id, channel_type, messaging_group_id, resolved_at)
+       VALUES (?, ?, ?, ?)`,
+      )
+      .run('telegram:scoped-admin', 'telegram', 'mg-dm-scoped-admin', now());
+
+    await routeInbound(groupMention('chat-scoped-cross-group'));
+    await new Promise((r) => setTimeout(r, 10));
+
+    const pending = getDb().prepare('SELECT messaging_group_id FROM pending_channel_approvals').get() as {
+      messaging_group_id: string;
+    };
+    expect(pending).toBeDefined();
+    expect(deliverMock).toHaveBeenCalledTimes(1);
+    expect(deliverMock.mock.calls[0][1]).toBe('dm-scoped-admin');
+
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.messaging_group_id,
+        value: 'choose_existing',
+        userId: 'scoped-admin',
+        channelType: 'telegram',
+        platformId: 'dm-scoped-admin',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    const followupPayload = JSON.parse(deliverMock.mock.calls[1][4] as string) as {
+      options: Array<{ label: string; value: string }>;
+    };
+    expect(followupPayload.options.map((option) => option.value)).toContain('connect:ag-1');
+    expect(followupPayload.options.map((option) => option.value)).not.toContain('connect:ag-2');
+
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.messaging_group_id,
+        value: 'connect:ag-2',
+        userId: 'scoped-admin',
+        channelType: 'telegram',
+        platformId: 'dm-scoped-admin',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    const mgaCount = (
+      getDb()
+        .prepare('SELECT COUNT(*) AS c FROM messaging_group_agents WHERE messaging_group_id = ?')
+        .get(pending.messaging_group_id) as { c: number }
+    ).c;
+    expect(mgaCount).toBe(0);
+    const stillPending = (getDb().prepare('SELECT COUNT(*) AS c FROM pending_channel_approvals').get() as { c: number })
+      .c;
+    expect(stillPending).toBe(1);
+  });
 });

 describe('no-owner / no-agent failure modes', () => {
@@ -55,6 +55,7 @@ import type { InboundEvent } from '../../channels/adapter.js';
 import type { AgentGroup } from '../../types.js';
 import { pickApprovalDelivery, pickApprover } from '../approvals/primitive.js';
 import { createPendingChannelApproval, hasInFlightChannelApproval } from './db/pending-channel-approvals.js';
+import { hasAdminPrivilege } from './db/user-roles.js';

 // ── Value constants (response handler in index.ts parses these) ──

@@ -76,15 +77,24 @@ function toFolder(name: string): string {

 // ── Card builders ──

-function buildApprovalOptions(agentGroups: AgentGroup[]): RawOption[] {
+function visibleAgentGroupsForApprover(
+  agentGroups: AgentGroup[],
+  approverUserId: string | null | undefined,
+): AgentGroup[] {
+  if (!approverUserId) return agentGroups;
+  return agentGroups.filter((agentGroup) => hasAdminPrivilege(approverUserId, agentGroup.id));
+}
+
+function buildApprovalOptions(agentGroups: AgentGroup[], approverUserId?: string | null): RawOption[] {
+  const visibleAgentGroups = visibleAgentGroupsForApprover(agentGroups, approverUserId);
  const options: RawOption[] = [];
-  if (agentGroups.length === 1) {
+  if (visibleAgentGroups.length === 1) {
    options.push({
-      label: `Connect to ${agentGroups[0].name}`,
-      selectedLabel: `✅ Connected to ${agentGroups[0].name}`,
-      value: `${CONNECT_PREFIX}${agentGroups[0].id}`,
+      label: `Connect to ${visibleAgentGroups[0].name}`,
+      selectedLabel: `✅ Connected to ${visibleAgentGroups[0].name}`,
+      value: `${CONNECT_PREFIX}${visibleAgentGroups[0].id}`,
    });
-  } else {
+  } else if (visibleAgentGroups.length > 1) {
    options.push({
      label: 'Choose existing agent',
      selectedLabel: '📋 Choosing…',
@@ -194,7 +204,7 @@ export async function requestChannelApproval(input: RequestChannelApprovalInput)
  const channelName = originMg?.name ?? null;
  const title = isGroup ? '📣 Bot mentioned in new channel' : '💬 New direct message';
  const question = buildQuestionText(isGroup, senderName, channelName, originChannelType);
-  const options = normalizeOptions(buildApprovalOptions(agentGroups));
+  const options = normalizeOptions(buildApprovalOptions(agentGroups, delivery.userId));

  createPendingChannelApproval({
    messaging_group_id: messagingGroupId,
@@ -241,8 +251,12 @@ export async function requestChannelApproval(input: RequestChannelApprovalInput)
 /**
 * Build normalized options for the agent-selection follow-up card.
 */
-export function buildAgentSelectionOptions(agentGroups: AgentGroup[]): NormalizedOption[] {
-  const options: RawOption[] = agentGroups.map((ag) => ({
+export function buildAgentSelectionOptions(
+  agentGroups: AgentGroup[],
+  approverUserId?: string | null,
+): NormalizedOption[] {
+  const visibleAgentGroups = visibleAgentGroupsForApprover(agentGroups, approverUserId);
+  const options: RawOption[] = visibleAgentGroups.map((ag) => ({
    label: ag.name,
    selectedLabel: `✅ Connected to ${ag.name}`,
    value: `${CONNECT_PREFIX}${ag.id}`,
@@ -354,7 +354,7 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
    if (!adapter) return true;

    const agentGroups = getAllAgentGroups();
-    const options = buildAgentSelectionOptions(agentGroups);
+    const options = buildAgentSelectionOptions(agentGroups, approverId);
    const title = '📋 Choose an agent';
    updatePendingChannelApprovalCard(row.messaging_group_id, title, JSON.stringify(options));

@@ -438,6 +438,14 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
      deletePendingChannelApproval(row.messaging_group_id);
      return true;
    }
+    if (!hasAdminPrivilege(approverId, targetAgentGroupId)) {
+      log.warn('Channel registration: target agent group rejected for unauthorized approver', {
+        messagingGroupId: row.messaging_group_id,
+        targetAgentGroupId,
+        approverId,
+      });
+      return true;
+    }
  } else {
    log.warn('Channel registration: unknown response value', {
      messagingGroupId: row.messaging_group_id,