test(channels): add behavior registration tests for the remaining channel fleet

discord, gchat, github, imessage, linear, matrix, resend, teams, telegram,
webex, whatsapp-cloud, signal, wechat, whatsapp, emacs.

Same behavior shape as the slack/deltachat exemplars: import the real
src/channels/index.ts barrel and assert getRegisteredChannelNames() contains
the channel. Red if the barrel import line is deleted/drifts, if the barrel
fails to evaluate, or (for channels with an npm adapter) if the adapter package
is not installed — so each test also implicitly guards the skill's dependency.
signal and emacs have no npm adapter (signal-cli binary / http builtin), so
their tests guard the single barrel reach-in only.

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

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

@@ -0,0 +1,161 @@
+---
+name: add-codex
+description: Use Codex (CLI + AppServer) as the full agent provider — planning, tool orchestration, native compaction, MCP tools, session resume — in place of the Claude Agent SDK. ChatGPT subscription or OPENAI_API_KEY. Per-group via agent_provider. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).
+---
+
+# Codex agent provider
+
+NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `codex` | `mock`).
+
+Trunk ships with only the `claude` provider baked in. This skill copies the Codex provider files in from the `providers` branch, wires them into the host and container barrels, updates the Dockerfile to install the Codex CLI, and rebuilds the image.
+
+The Codex provider runs `codex app-server` as a child process and speaks JSON-RPC over stdio. That gives it native session resume, streaming events, MCP tool access, and `thread/compact/start` compaction — same feature bar as the Claude Agent SDK, without the Anthropic-only lock-in.
+
+## Install
+
+### Pre-flight
+
+If all of the following are already present, skip to **Configuration**:
+
+- `src/providers/codex.ts`
+- `container/agent-runner/src/providers/codex.ts`
+- `container/agent-runner/src/providers/codex-app-server.ts`
+- `container/agent-runner/src/providers/codex.factory.test.ts`
+- `import './codex.js';` line in `src/providers/index.ts`
+- `import './codex.js';` line in `container/agent-runner/src/providers/index.ts`
+- `ARG CODEX_VERSION` and `"@openai/codex@${CODEX_VERSION}"` in the pnpm global-install block in `container/Dockerfile`
+
+Missing pieces — continue below. All steps are idempotent; re-running is safe.
+
+### 1. Fetch the providers branch
+
+```bash
+git fetch origin providers
+```
+
+### 2. Copy the Codex source files
+
+Wholesale copies (owned entirely by this skill — user edits to these files won't survive a re-run, as designed):
+
+```bash
+git show origin/providers:src/providers/codex.ts                                      > src/providers/codex.ts
+git show origin/providers:container/agent-runner/src/providers/codex.ts               > container/agent-runner/src/providers/codex.ts
+git show origin/providers:container/agent-runner/src/providers/codex-app-server.ts    > container/agent-runner/src/providers/codex-app-server.ts
+git show origin/providers:container/agent-runner/src/providers/codex.factory.test.ts  > container/agent-runner/src/providers/codex.factory.test.ts
+```
+
+### 3. Append the self-registration imports
+
+Each barrel gets one line — alphabetical placement keeps diffs small.
+
+`src/providers/index.ts`:
+
+```typescript
+import './codex.js';
+```
+
+`container/agent-runner/src/providers/index.ts`:
+
+```typescript
+import './codex.js';
+```
+
+### 4. Add the Codex CLI to the container Dockerfile
+
+Two edits to `container/Dockerfile`, both idempotent (skip if already present):
+
+**(a)** In the "Pin CLI versions" ARG block (around line 18), add after `ARG CLAUDE_CODE_VERSION=...`:
+
+```dockerfile
+ARG CODEX_VERSION=0.124.0
+```
+
+**(b)** Add a new standalone `RUN` block for the Codex CLI, after the existing per-CLI install blocks (around line 106, right after the `@anthropic-ai/claude-code` block). The Dockerfile splits each global CLI into its own layer for cache granularity — keep that pattern; do not collapse them into a single combined `pnpm install -g` call:
+
+```dockerfile
+RUN --mount=type=cache,target=/root/.cache/pnpm \
+    pnpm install -g "@openai/codex@${CODEX_VERSION}"
+```
+
+Note: **no agent-runner package dependency** — Codex is a CLI binary, not a library. Unlike OpenCode, there's nothing to add to `container/agent-runner/package.json`.
+
+### 5. Build
+
+```bash
+pnpm run build                                         # host
+pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit   # container typecheck
+./container/build.sh                                   # agent image
+```
+
+## Configuration
+
+Codex supports two primary auth paths and one experimental BYO-endpoint path. Pick the one that matches your setup.
+
+### Option A — ChatGPT subscription (recommended for individuals)
+
+On the host (not inside the container), run Codex's OAuth login:
+
+```bash
+codex login
+```
+
+This writes `~/.codex/auth.json` with a subscription token. The host-side Codex provider ([src/providers/codex.ts](../../../src/providers/codex.ts)) copies `auth.json` into a per-session `~/.codex` directory mounted into the container — your host's own Codex CLI is never touched.
+
+No `.env` variables required for this mode.
+
+### Option B — API key (recommended for CI or API billing)
+
+```env
+OPENAI_API_KEY=sk-...
+CODEX_MODEL=gpt-5.4-mini
+```
+
+The host forwards both variables into the container. If both subscription (`auth.json`) and `OPENAI_API_KEY` are present, Codex prefers the subscription.
+
+### Option C — BYO OpenAI-compatible endpoint (experimental)
+
+Codex's built-in `openai` provider honors the `OPENAI_BASE_URL` env var directly. Point it at any OpenAI-compatible endpoint — Groq, Together, self-hosted vLLM, an OpenAI proxy, etc.
+
+```env
+OPENAI_API_KEY=...
+OPENAI_BASE_URL=https://api.groq.com/openai/v1
+CODEX_MODEL=llama-3.3-70b-versatile
+```
+
+Codex also ships first-class local-runner flags — `codex --oss --local-provider ollama` or `--local-provider lmstudio` — that auto-detect a local server. To use those inside NanoClaw, set `CODEX_MODEL` to a model your local runner serves and add the corresponding base URL; see the Codex CLI docs for the full `model_provider = oss` configuration.
+
+**Experimental caveat:** tool-calling quality depends on the model and endpoint. Not every OpenAI-compat provider implements the full function-calling spec, and smaller models (< 30B) often struggle with multi-step tool orchestration. Test before committing.
+
+### Per group / per session
+
+Set `"provider": "codex"` in the group's **`container.json`** (`groups/<folder>/container.json`) — the in-container runner reads `provider` from there, not from the DB. The DB columns **`agent_groups.agent_provider`** and **`sessions.agent_provider`** (session overrides group) only drive host-side provider contribution — per-session `~/.codex` mount, `OPENAI_*` / `CODEX_MODEL` env passthrough — and do not propagate into `container.json` at spawn time. Set both, or just edit `container.json`; if they disagree, the runner uses `container.json` and the host-side resolver falls back through session → group → `container.json` → `'claude'`.
+
+`CODEX_MODEL` applies process-wide via `.env`; if you need different models for different groups, set them via `container_config.env` on the group.
+
+Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config.mcpServers` on the host. The runner merges them into the same `mcpServers` object passed to all providers.
+
+## Operational notes
+
+- **Spawn-per-query:** Codex's app-server is spawned fresh per query invocation, matching the OpenCode pattern. No long-lived daemon to keep healthy across sessions.
+- **Per-session `~/.codex` isolation:** each group gets its own copy of the host's `auth.json`. The container can rewrite `config.toml` freely on every wake without touching the host's Codex config.
+- **Native compaction:** kicks in automatically at 40K cumulative input tokens between turns, via `thread/compact/start`. If compaction fails, the provider logs and continues uncompacted — no fatal error.
+- **Approvals:** auto-accepted inside the container (the container is the sandbox; same posture as Claude/OpenCode).
+- **Mid-turn input:** Codex turns don't accept mid-turn messages. Follow-up `push()` calls queue and drain between turns, matching the OpenCode pattern. The poll-loop only pushes between turns anyway, so no messages are dropped.
+- **Stale thread recovery:** `isSessionInvalid` matches on stale-thread-ID errors (`thread not found`, `unknown thread`, etc.) so a cold-started app-server can recover cleanly when it sees a stored continuation it no longer has.
+
+## Verify
+
+```bash
+grep -q "./codex.js" container/agent-runner/src/providers/index.ts && echo "container barrel: OK"
+grep -q "./codex.js" src/providers/index.ts && echo "host barrel: OK"
+grep -q "@openai/codex@" container/Dockerfile && echo "Dockerfile install: OK"
+cd container/agent-runner && bun test src/providers/codex.factory.test.ts && cd -
+```
+
+After the image rebuild, set `agent_provider = 'codex'` on a test group and send a message. Successful round-trip looks like:
+
+- `init` event with a stable thread ID as continuation
+- One or more `activity` / `progress` events during the turn
+- `result` event with the model's reply
+
+If the agent hangs or errors, check `~/.codex/auth.json` exists on the host (Option A) or that `OPENAI_API_KEY` is forwarding correctly (Option B) — `docker exec` into a running container and `env | grep -i openai` to confirm.

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

@@ -0,0 +1,62 @@
+# Remove DeltaChat
+
+## 1. Disable the adapter
+
+Comment out the import in `src/channels/index.ts`:
+
+```typescript
+// import './deltachat.js';
+```
+
+## 2. Remove credentials
+
+Remove the `DC_*` lines from `.env`:
+
+```bash
+DC_EMAIL
+DC_PASSWORD
+DC_IMAP_HOST
+DC_IMAP_PORT
+DC_SMTP_HOST
+DC_SMTP_PORT
+```
+
+## 3. Rebuild and restart
+
+```bash
+pnpm run build
+
+# Linux
+systemctl --user restart nanoclaw
+
+# macOS
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```
+
+## 4. Remove account data (optional)
+
+To fully remove all account data including DeltaChat encryption keys:
+
+```bash
+rm -rf dc-account/
+```
+
+> **Warning:** This deletes the Autocrypt keys. Contacts who have verified your bot's key will need to re-verify if the same email address is re-used with a new account.
+
+To keep the account for later reinstall, leave `dc-account/` intact.
+
+## 5. Remove the package (optional)
+
+```bash
+pnpm remove @deltachat/stdio-rpc-server
+```
+
+## Verification
+
+After removal, confirm the adapter is no longer starting:
+
+```bash
+grep "deltachat" logs/nanoclaw.log | tail -5
+```
+
+Expected: no `Channel adapter started` entry after the last restart.

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

@@ -0,0 +1,254 @@
+---
+name: add-deltachat
+description: Add DeltaChat channel integration via @deltachat/stdio-rpc-server. Native adapter — no Chat SDK bridge. Email-based messaging with end-to-end encryption.
+---
+
+# Add DeltaChat Channel
+
+The adapter drives the `@deltachat/stdio-rpc-server` JSON-RPC subprocess directly — pure Node.js against the DeltaChat core library. Messages are delivered over email with Autocrypt/OpenPGP encryption.
+
+## Install
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/deltachat.ts` exists
+- `src/channels/index.ts` contains `import './deltachat.js';`
+- `@deltachat/stdio-rpc-server` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/deltachat.ts > src/channels/deltachat.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if already present):
+
+```typescript
+import './deltachat.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @deltachat/stdio-rpc-server@2.49.0
+```
+
+### 5. Build
+
+```bash
+pnpm run build
+```
+
+## Account Setup
+
+A dedicated email account is strongly recommended — it will accumulate DeltaChat-formatted messages and store encryption keys. Not all providers work well with DeltaChat; check https://providers.delta.chat/ before picking one.
+
+**Default security modes:** IMAP uses SSL/TLS (port 993), SMTP uses STARTTLS (port 587). Both are configurable via `.env` — see Credentials below.
+
+To find the correct hostnames for a domain:
+
+```bash
+node -e "require('dns').resolveMx('example.com', (e,r) => console.log(r))"
+```
+
+Most providers publish their IMAP/SMTP hostnames in their help docs under "manual setup" or "IMAP access."
+
+## Credentials
+
+Add to `.env`:
+
+```bash
+DC_EMAIL=bot@example.com
+DC_PASSWORD=your-app-password
+DC_IMAP_HOST=imap.example.com
+DC_IMAP_PORT=993
+DC_IMAP_SECURITY=1        # 1=SSL/TLS (default), 2=STARTTLS, 3=plain
+DC_SMTP_HOST=smtp.example.com
+DC_SMTP_PORT=587
+DC_SMTP_SECURITY=2        # 2=STARTTLS (default), 1=SSL/TLS, 3=plain
+```
+
+Security settings are applied on every startup, so changing them in `.env` and restarting takes effect without wiping the account.
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+### Optional settings
+
+The following are read from the process environment (not `.env`). To override them, add `Environment=` lines to the systemd service unit or your launchd plist:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DC_ACCOUNT_DIR` | `dc-account` | Directory for DeltaChat account data (IMAP state, keys, blobs) |
+| `DC_DISPLAY_NAME` | `NanoClaw` | Bot display name shown in DeltaChat |
+| `DC_AVATAR_PATH` | _(none)_ | Absolute path to avatar image; set at startup only |
+
+The `/set-avatar` command (send an image with that caption) is the easiest way to set the avatar at runtime without modifying the service file. Only users with `owner` or global `admin` role can use it.
+
+### Restart
+
+```bash
+# Linux
+systemctl --user restart nanoclaw
+
+# macOS
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```
+
+On first start the adapter configures the email account (IMAP/SMTP credentials, calls `configure()`). Subsequent starts skip straight to `startIo()`. Account data is stored in `dc-account/` in the project root (or your `DC_ACCOUNT_DIR`).
+
+## Wiring
+
+### DMs
+
+**DeltaChat contacts cannot be added by email alone** — to start a chat, the user must open the bot's invite link in their DeltaChat app or scan its QR code. This triggers the SecureJoin handshake.
+
+#### Step 1 — Get the invite link
+
+After the service starts, the adapter logs the invite URL and writes a QR SVG:
+
+```bash
+grep "invite link" logs/nanoclaw.log | tail -1
+# url field contains the https://i.delta.chat/... invite link
+# also written to dc-account/invite-qr.svg (or $DC_ACCOUNT_DIR/invite-qr.svg)
+```
+
+The invite URL is stable (tied to the bot's email and encryption keys) so it stays valid across restarts.
+
+#### Step 2 — Add the bot in DeltaChat
+
+Two options for the user to connect:
+
+- **Link**: Copy the `https://i.delta.chat/...` URL and open it on the device running DeltaChat. The app recognises it and shows a "Start chat" prompt.
+- **QR code**: Open `dc-account/invite-qr.svg` in a browser or image viewer, display it on screen, and scan it from the DeltaChat app using the QR-scan button on the new-chat screen.
+
+After accepting, DeltaChat exchanges keys and creates the chat automatically.
+
+#### Step 3 — Wire the chat to an agent
+
+Once the first message arrives the router auto-creates a `messaging_groups` row. Look up the chat ID:
+
+```bash
+sqlite3 data/v2.db \
+  "SELECT platform_id, name FROM messaging_groups WHERE channel_type='deltachat' AND is_group=0 ORDER BY created_at DESC LIMIT 5"
+```
+
+Then run `/init-first-agent` — it creates the agent group, grants the user owner access, and wires the messaging group in one step:
+
+```bash
+pnpm exec tsx scripts/init-first-agent.ts \
+  --channel deltachat \
+  --user-id deltachat:user@example.com \
+  --platform-id <platform_id from above> \
+  --display-name "Your Name"
+```
+
+### Groups
+
+Add the bot email to a DeltaChat group. When any member sends a message, the router creates a `messaging_groups` row with `is_group = 1`. Run `/manage-channels` to wire it to an agent group.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/init-first-agent` to create an agent and wire it to your DeltaChat DM (see Wiring above), or `/manage-channels` to wire this channel to an existing agent group.
+
+## Channel Info
+
+- **type**: `deltachat`
+- **terminology**: DeltaChat calls them "chats" (1:1 DMs) and "groups"
+- **supports-threads**: no — DeltaChat has no thread model
+- **platform-id-format**: numeric chat ID as a string (e.g. `"12"`) — the DeltaChat core's internal chat identifier
+- **user-id-format**: `deltachat:{email}` — the contact's email address
+- **how-to-find-id**: Send a message from DeltaChat to the bot email, then query `messaging_groups` as shown above
+- **typical-use**: Personal assistant over DeltaChat DMs; small groups where participants use DeltaChat
+- **default-isolation**: One agent per bot identity. Multiple chats with the same operator can share an agent group; groups with other people should typically use `isolated` session mode
+
+### Features
+
+- File attachments — inbound and outbound; inbound waits up to 30 seconds for large-message download to complete
+- Invite link logged on every startup — URL + QR SVG written to `dc-account/invite-qr.svg`; see Wiring for the bootstrap flow
+- `/set-avatar` — send an image with this caption to change the bot's DeltaChat avatar (admin/owner only)
+- Connectivity watchdog — restarts IO if IMAP goes quiet for 20 minutes or connectivity drops below threshold for two consecutive 5-minute checks
+- Network nudge — `maybeNetwork()` called every 10 minutes to recover from prolonged idle
+
+Not supported: DeltaChat reactions, message editing/deletion, read receipts.
+
+### Connectivity model
+
+`isConnected()` returns `true` when the internal connectivity value is ≥ 3000:
+
+| Range | Meaning |
+|-------|---------|
+| 1000–1999 | Not connected |
+| 2000–2999 | Connecting |
+| 3000–3999 | Working (IMAP fetching) |
+| ≥ 4000 | Fully connected (IMAP IDLE) |
+
+## Troubleshooting
+
+### Adapter not starting — credentials missing
+
+```bash
+grep "Channel credentials missing" logs/nanoclaw.log | grep deltachat
+```
+
+All six required vars (`DC_EMAIL`, `DC_PASSWORD`, `DC_IMAP_HOST`, `DC_IMAP_PORT`, `DC_SMTP_HOST`, `DC_SMTP_PORT`) must be present in `.env`.
+
+### Account configure fails
+
+```bash
+grep "DeltaChat" logs/nanoclaw.log | tail -20
+```
+
+Common causes:
+- Wrong IMAP/SMTP hostnames — double-check provider docs
+- App password not generated — Gmail and some others require this when 2FA is enabled
+- Port/security mismatch — defaults are port 993 + SSL/TLS for IMAP and port 587 + STARTTLS for SMTP; override with `DC_IMAP_PORT`/`DC_IMAP_SECURITY` or `DC_SMTP_PORT`/`DC_SMTP_SECURITY` in `.env`
+
+### Provider uses SMTP port 465 (SSL/TLS) instead of 587
+
+Set `DC_SMTP_SECURITY=1` and `DC_SMTP_PORT=465` in `.env`, then restart.
+
+### Messages not arriving
+
+1. Check the service is running and the adapter started: `grep "Channel adapter started.*deltachat" logs/nanoclaw.log`
+2. Check connectivity: `grep "DeltaChat: IO started" logs/nanoclaw.log`
+3. Check the sender has been granted access — run `/init-first-agent` to create their user record and wire the chat
+4. Verify the messaging group is wired: `sqlite3 data/v2.db "SELECT mg.platform_id, mga.agent_group_id FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id WHERE mg.channel_type='deltachat'"`
+
+### Stale lock file after crash
+
+```bash
+rm -f dc-account/accounts.lock
+systemctl --user restart nanoclaw
+```
+
+### Bot not responding after restart
+
+The account is already configured — IO restarts automatically on service start. If the RPC subprocess is stuck, restart the service. Check for errors:
+
+```bash
+grep "DeltaChat" logs/nanoclaw.error.log | tail -20
+```
+
+### Messages received but agent not responding
+
+The messaging group exists but may not be wired to an agent group. Run:
+
+```bash
+sqlite3 data/v2.db "SELECT id, platform_id, name FROM messaging_groups WHERE channel_type='deltachat'"
+```
+
+If the group has no entry in `messaging_group_agents`, wire it with `/manage-channels`.

.claude/skills/add-deltachat/VERIFY.md

@@ -0,0 +1,54 @@
+# Verify DeltaChat
+
+## 1. Check the adapter started
+
+```bash
+grep "Channel adapter started.*deltachat" logs/nanoclaw.log | tail -1
+```
+
+Expected: `Channel adapter started { channel: 'deltachat', type: 'deltachat' }`
+
+## 2. Check IMAP/SMTP connectivity
+
+Replace with your provider's hostnames from `.env`:
+
+```bash
+DC_IMAP=$(grep '^DC_IMAP_HOST=' .env | cut -d= -f2)
+DC_SMTP=$(grep '^DC_SMTP_HOST=' .env | cut -d= -f2)
+
+bash -c "echo >/dev/tcp/$DC_IMAP/993" && echo "IMAP open" || echo "IMAP blocked"
+bash -c "echo >/dev/tcp/$DC_SMTP/587" && echo "SMTP open" || echo "SMTP blocked"
+```
+
+## 3. End-to-end message test
+
+1. Open DeltaChat on your device
+2. Add the bot email address as a contact
+3. Send a message
+4. The bot should respond within a few seconds
+
+If nothing arrives, check:
+
+```bash
+grep "DeltaChat" logs/nanoclaw.log | tail -20
+grep "DeltaChat" logs/nanoclaw.error.log | tail -10
+```
+
+## 4. Check messaging group was created
+
+```bash
+sqlite3 data/v2.db \
+  "SELECT id, platform_id, name FROM messaging_groups WHERE channel_type='deltachat' ORDER BY created_at DESC LIMIT 5"
+```
+
+If a row appears, the inbound routing is working. If not, the adapter isn't receiving the message — check logs for `DeltaChat: error handling incoming message`.
+
+## 5. Verify user access
+
+If the message arrived but the agent didn't respond, the sender may not have access:
+
+```bash
+sqlite3 data/v2.db "SELECT id, display_name FROM users WHERE id LIKE 'deltachat:%'"
+```
+
+Grant access as shown in the SKILL.md "Grant user access" section.

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

@@ -57,7 +57,7 @@ groups: () => import('./groups.js'),
 ### 5. Install the adapter packages (pinned)
 
 ```bash
-pnpm install @whiskeysockets/baileys@6.17.16 qrcode@1.5.4 @types/qrcode@1.5.6 pino@9.6.0
+pnpm install @whiskeysockets/baileys@7.0.0-rc.9 qrcode@1.5.4 @types/qrcode@1.5.6 pino@9.6.0
 ```
 
 ### 6. Build

container/AGENTS.md

@@ -1,15 +0,0 @@
-You are a NanoClaw agent. Your name, destinations, and message-sending rules are provided in the runtime system prompt at the top of each turn.
-
-## Communication
-
-Be concise. Prefer outcomes over play-by-play; when the work is done, the final message should be about the result.
-
-When you produce a file for the user in the workspace — a document, export, or asset — deliver it with `send_file` in the same turn; announcing without sending is an unfinished reply.
-
-## Workspace
-
-Files you create are saved in `/workspace/agent/`. Use this for notes, research, artifacts, and anything that should persist across turns in this group.
-
-## Conversation History
-
-The `conversations/` folder holds searchable past conversation transcripts or exchange archives for this group. Use it to recall prior context when a request references something that happened before.

container/Dockerfile

@@ -20,7 +20,6 @@ ARG INSTALL_CJK_FONTS=false
 # mean every rebuild silently picks up the latest and can break in lockstep
 # across all users.
 ARG CLAUDE_CODE_VERSION=2.1.116
-ARG CODEX_VERSION=0.138.0
 ARG AGENT_BROWSER_VERSION=latest
 ARG VERCEL_VERSION=latest
 ARG BUN_VERSION=1.3.12
@@ -102,9 +101,6 @@ RUN --mount=type=cache,target=/root/.cache/pnpm \
 RUN --mount=type=cache,target=/root/.cache/pnpm \
     pnpm install -g "agent-browser@${AGENT_BROWSER_VERSION}"
 
-RUN --mount=type=cache,target=/root/.cache/pnpm \
-    pnpm install -g "@openai/codex@${CODEX_VERSION}"
-
 RUN --mount=type=cache,target=/root/.cache/pnpm \
     pnpm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
 

container/agent-runner/bun.lock

@@ -7,7 +7,6 @@
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.2.116",
         "@modelcontextprotocol/sdk": "^1.12.1",
-        "@opencode-ai/sdk": "^1.4.3",
         "cron-parser": "^5.0.0",
         "zod": "^4.0.0",
       },
@@ -45,8 +44,6 @@
 
     "@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=="],
 
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.4.11", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-EJxSfc7D/dda/vrw8zQe4g7yVTxERktvb5SvIBlGBnKYQJGOgo9RyA/1EL3l208rHeo6jm1sdrAF0E6o/k94ug=="],
-
     "@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=="],

container/agent-runner/package.json

@@ -11,7 +11,6 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.116",
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@opencode-ai/sdk": "^1.4.3",
     "cron-parser": "^5.0.0",
     "zod": "^4.0.0"
   },

container/agent-runner/src/providers/codex-app-server.test.ts

@@ -1,162 +0,0 @@
-import { describe, expect, it, afterEach } from 'bun:test';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import {
-  type AppServer,
-  attachCodexAutoApproval,
-  buildCodexProcessEnv,
-  tomlBasicString,
-  writeCodexConfigToml,
-} from './codex-app-server.js';
-
-let tmpHome: string | null = null;
-const originalHome = process.env.HOME;
-
-afterEach(() => {
-  process.env.HOME = originalHome;
-  if (tmpHome) {
-    fs.rmSync(tmpHome, { recursive: true, force: true });
-    tmpHome = null;
-  }
-});
-
-describe('Codex config TOML', () => {
-  it('escapes basic strings', () => {
-    expect(tomlBasicString('a "quoted" \\\\ value')).toBe('"a \\"quoted\\" \\\\\\\\ value"');
-  });
-
-  it('rejects newlines', () => {
-    expect(() => tomlBasicString('bad\nvalue')).toThrow(/newline/);
-  });
-
-  it('hardcodes danger-full-access + never and writes model, effort, and MCP servers', () => {
-    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-home-'));
-    process.env.HOME = tmpHome;
-
-    writeCodexConfigToml(
-      {
-        nanoclaw: {
-          command: 'bun',
-          args: ['run', '/app/src/mcp-tools/index.ts'],
-          env: { FOO: 'bar' },
-        },
-      },
-      { model: 'gpt-5', effort: 'medium' },
-    );
-
-    const content = fs.readFileSync(path.join(tmpHome, '.codex', 'config.toml'), 'utf-8');
-    expect(content).toContain('sandbox_mode = "danger-full-access"');
-    expect(content).toContain('approval_policy = "never"');
-    expect(content).toContain('project_doc_max_bytes = 32768');
-    expect(content).toContain('model = "gpt-5"');
-    expect(content).toContain('model_reasoning_effort = "medium"');
-    expect(content).not.toContain('[sandbox_workspace_write]');
-    expect(content).not.toContain('writable_roots =');
-    expect(content).toContain('[mcp_servers.nanoclaw]');
-    expect(content).toContain('command = "bun"');
-    expect(content).toContain('args = ["run", "/app/src/mcp-tools/index.ts"]');
-    expect(content).toContain('[mcp_servers.nanoclaw.env]');
-    expect(content).toContain('FOO = "bar"');
-  });
-});
-
-describe('Codex auto-approval', () => {
-  // NanoClaw (container isolation + OneCLI) is the boundary, so the handler accepts
-  // every request unconditionally — even paths/commands a sandbox policy would refuse.
-  it('grants full filesystem + network for permission requests', () => {
-    const { server, writes } = fakeServer();
-    attachCodexAutoApproval(server);
-
-    server.serverRequestHandlers[0]({
-      id: 1,
-      method: 'item/permissions/requestApproval',
-      params: { permissions: { fileSystem: { read: ['/workspace/agent'], write: ['/workspace/agent'] } } },
-    });
-
-    const result = JSON.parse(writes[0]).result as {
-      permissions: { fileSystem: { read: string[]; write: string[] }; network: { enabled: boolean } };
-      scope: string;
-    };
-    expect(result.scope).toBe('turn');
-    expect(result.permissions.fileSystem.read).toEqual(['/']);
-    expect(result.permissions.fileSystem.write).toEqual(['/']);
-    expect(result.permissions.network.enabled).toBe(true);
-  });
-
-  it('accepts file-change and command-exec approvals regardless of path', () => {
-    const { server, writes } = fakeServer();
-    attachCodexAutoApproval(server);
-
-    server.serverRequestHandlers[0]({ id: 2, method: 'item/fileChange/requestApproval', params: { grantRoot: '/etc' } });
-    server.serverRequestHandlers[0]({
-      id: 3,
-      method: 'item/commandExecution/requestApproval',
-      params: { command: 'rm -rf /', cwd: '/' },
-    });
-
-    expect(JSON.parse(writes[0]).result).toEqual({ decision: 'accept' });
-    expect(JSON.parse(writes[1]).result).toEqual({ decision: 'accept' });
-  });
-
-  it('approves legacy patch and command-exec approvals regardless of path', () => {
-    const { server, writes } = fakeServer();
-    attachCodexAutoApproval(server);
-
-    server.serverRequestHandlers[0]({
-      id: 4,
-      method: 'applyPatchApproval',
-      params: { fileChanges: { '/etc/passwd': {} } },
-    });
-    server.serverRequestHandlers[0]({ id: 5, method: 'execCommandApproval', params: { command: 'rm -rf /', cwd: '/' } });
-
-    expect(JSON.parse(writes[0]).result).toEqual({ decision: 'approved' });
-    expect(JSON.parse(writes[1]).result).toEqual({ decision: 'approved' });
-  });
-
-  it('fails closed for unknown server requests', () => {
-    const { server, writes } = fakeServer();
-    attachCodexAutoApproval(server);
-
-    server.serverRequestHandlers[0]({ id: 6, method: 'new/unknown/request' });
-
-    const response = JSON.parse(writes[0]);
-    expect(response.error.message).toContain('Unhandled Codex app-server request');
-  });
-});
-
-describe('Codex process env', () => {
-  it('forwards proxy/runtime env without leaking secret-like host env', () => {
-    const env = buildCodexProcessEnv({
-      PATH: '/bin',
-      HOME: '/home/node',
-      CODEX_HOME: '/home/node/.codex',
-      HTTPS_PROXY: 'http://proxy',
-      OPENAI_API_KEY: 'sk-test',
-      ONECLI_API_KEY: 'onecli-secret',
-      SOME_TOKEN: 'token',
-    });
-
-    expect(env.PATH).toBe('/bin');
-    expect(env.HOME).toBe('/home/node');
-    expect(env.CODEX_HOME).toBe('/home/node/.codex');
-    expect(env.HTTPS_PROXY).toBe('http://proxy');
-    expect(env.OPENAI_API_KEY).toBeUndefined();
-    expect(env.ONECLI_API_KEY).toBeUndefined();
-    expect(env.SOME_TOKEN).toBeUndefined();
-  });
-});
-
-function fakeServer(): { server: AppServer; writes: string[] } {
-  const writes: string[] = [];
-  const server = {
-    process: { stdin: { write: (line: string) => writes.push(line) } },
-    readline: { close: () => {} },
-    pending: new Map(),
-    notificationHandlers: [],
-    exitHandlers: [],
-    serverRequestHandlers: [],
-  } as unknown as AppServer;
-  return { server, writes };
-}

container/agent-runner/src/providers/codex-app-server.ts

@@ -1,441 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { spawn, type ChildProcess } from 'child_process';
-import { createInterface, type Interface as ReadlineInterface } from 'readline';
-
-// Cap Codex's project-doc loading (AGENTS.md). The host-side composer
-// (src/providers/codex-agents-md.ts) enforces the same cap at compose time —
-// host and container share no modules, so the constant lives in both.
-const CODEX_PROJECT_DOC_MAX_BYTES = 32 * 1024;
-
-function log(msg: string): void {
-  console.error(`[codex-app-server] ${msg}`);
-}
-
-const INIT_TIMEOUT_MS = 30_000;
-
-export const STALE_THREAD_RE = /thread\s+not\s+found|unknown\s+thread|thread[_\s]id|no such thread/i;
-
-let nextRequestId = 1;
-
-export interface JsonRpcResponse {
-  id: number | string;
-  result?: unknown;
-  error?: { code: number; message: string; data?: unknown };
-}
-
-export interface JsonRpcNotification {
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-export interface JsonRpcServerRequest {
-  id: number | string;
-  method: string;
-  params?: Record<string, unknown>;
-}
-
-type JsonRpcMessage = JsonRpcResponse | JsonRpcNotification | JsonRpcServerRequest;
-
-export interface AppServer {
-  process: ChildProcess;
-  readline: ReadlineInterface;
-  pending: Map<number | string, { resolve: (r: JsonRpcResponse) => void; reject: (e: Error) => void }>;
-  notificationHandlers: Array<(n: JsonRpcNotification) => void>;
-  serverRequestHandlers: Array<(r: JsonRpcServerRequest) => void>;
-  /**
-   * Fired when the app-server process dies (exit or spawn error). Pending
-   * request/response pairs are rejected separately via failPending — but a
-   * turn in flight has NO pending request (turn/start already resolved); it
-   * is parked on a notification waker that a dead process will never kick.
-   * Without these handlers a mid-turn crash surfaces as a 10-minute turn
-   * timeout instead of the real exit code, after the --rm container has
-   * already taken the server's stderr with it.
-   */
-  exitHandlers: Array<(err: Error) => void>;
-}
-
-export interface CodexMcpServer {
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-}
-
-export type CodexReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
-
-// Codex runs unrestricted inside the container. NanoClaw's container isolation and
-// the OneCLI allow-list are the security boundary — not Codex's own sandbox/approval
-// primitives (which can't run here anyway: workspace-write/read-only need user
-// namespaces, which the agent containers deny). Both are hardcoded as instance-level
-// defaults in config.toml; threads and turns inherit them, never override them.
-const CODEX_SANDBOX_MODE = 'danger-full-access';
-const CODEX_APPROVAL_POLICY = 'never';
-
-const CODEX_ENV_ALLOWLIST = new Set([
-  'ALL_PROXY',
-  'CURL_CA_BUNDLE',
-  'GIT_SSL_CAINFO',
-  'HOME',
-  'HTTP_PROXY',
-  'HTTPS_PROXY',
-  'LANG',
-  'LC_ALL',
-  'NODE_EXTRA_CA_CERTS',
-  'NO_PROXY',
-  'PATH',
-  'PNPM_HOME',
-  'REQUESTS_CA_BUNDLE',
-  'SSL_CERT_DIR',
-  'SSL_CERT_FILE',
-  'TEMP',
-  'TERM',
-  'TMP',
-  'TMPDIR',
-  'TZ',
-  'USER',
-  'all_proxy',
-  'http_proxy',
-  'https_proxy',
-  'no_proxy',
-  'CODEX_HOME',
-]);
-
-export interface ThreadParams {
-  model?: string;
-  cwd: string;
-  baseInstructions?: string;
-  developerInstructions?: string;
-}
-
-export interface TurnParams {
-  threadId: string;
-  inputText: string;
-  model?: string;
-  effort?: string;
-  cwd?: string;
-}
-
-export function spawnCodexAppServer(): AppServer {
-  const args = ['app-server', '--listen', 'stdio://'];
-  log(`Spawning: codex ${args.join(' ')}`);
-
-  const proc = spawn('codex', args, {
-    stdio: ['pipe', 'pipe', 'pipe'],
-    env: buildCodexProcessEnv(process.env),
-  });
-  const rl = createInterface({ input: proc.stdout! });
-
-  const server: AppServer = {
-    process: proc,
-    readline: rl,
-    pending: new Map(),
-    notificationHandlers: [],
-    exitHandlers: [],
-    serverRequestHandlers: [],
-  };
-
-  proc.stderr?.on('data', (chunk: Buffer) => {
-    const text = chunk.toString().trim();
-    if (text) log(`[stderr] ${text}`);
-  });
-
-  rl.on('line', (line: string) => {
-    if (!line.trim()) return;
-    let msg: JsonRpcMessage;
-    try {
-      msg = JSON.parse(line) as JsonRpcMessage;
-    } catch {
-      log(`[parse-error] ${line.slice(0, 200)}`);
-      return;
-    }
-
-    if (isResponse(msg)) {
-      const handler = server.pending.get(msg.id);
-      if (handler) {
-        server.pending.delete(msg.id);
-        handler.resolve(msg);
-      }
-    } else if (isServerRequest(msg)) {
-      for (const h of server.serverRequestHandlers) h(msg);
-    } else if ('method' in msg) {
-      for (const h of server.notificationHandlers) h(msg as JsonRpcNotification);
-    }
-  });
-
-  const failPending = (err: Error): void => {
-    for (const [, handler] of server.pending) handler.reject(err);
-    server.pending.clear();
-  };
-
-  proc.on('error', (err) => {
-    log(`[process-error] ${err.message}`);
-    failPending(err);
-    for (const h of [...server.exitHandlers]) h(err);
-  });
-
-  proc.on('exit', (code, signal) => {
-    log(`[exit] code=${code} signal=${signal}`);
-    const err = new Error(`Codex app-server exited: code=${code} signal=${signal}`);
-    failPending(err);
-    for (const h of [...server.exitHandlers]) h(err);
-  });
-
-  return server;
-}
-
-export function sendCodexRequest(
-  server: AppServer,
-  method: string,
-  params?: Record<string, unknown>,
-  timeoutMs = 60_000,
-): Promise<JsonRpcResponse> {
-  const id = nextRequestId++;
-  const req = params === undefined ? { id, method } : { id, method, params };
-  const line = JSON.stringify(req) + '\n';
-
-  return new Promise<JsonRpcResponse>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      server.pending.delete(id);
-      reject(new Error(`Timeout waiting for ${method} response (${timeoutMs}ms)`));
-    }, timeoutMs);
-
-    server.pending.set(id, {
-      resolve: (r) => {
-        clearTimeout(timer);
-        resolve(r);
-      },
-      reject: (e) => {
-        clearTimeout(timer);
-        reject(e);
-      },
-    });
-
-    try {
-      server.process.stdin!.write(line);
-    } catch (err) {
-      clearTimeout(timer);
-      server.pending.delete(id);
-      reject(err instanceof Error ? err : new Error(String(err)));
-    }
-  });
-}
-
-export function sendCodexNotification(server: AppServer, method: string, params?: Record<string, unknown>): void {
-  const line = JSON.stringify(params === undefined ? { method } : { method, params }) + '\n';
-  server.process.stdin!.write(line);
-}
-
-export function sendCodexResponse(server: AppServer, id: number | string, result: unknown): void {
-  try {
-    server.process.stdin!.write(JSON.stringify({ id, result }) + '\n');
-  } catch (err) {
-    log(`[send-error] response id=${id}: ${err instanceof Error ? err.message : String(err)}`);
-  }
-}
-
-export function killCodexAppServer(server: AppServer): void {
-  try {
-    server.readline.close();
-    server.process.kill('SIGTERM');
-  } catch {
-    /* ignore */
-  }
-}
-
-export async function initializeCodexAppServer(server: AppServer): Promise<void> {
-  const resp = await sendCodexRequest(
-    server,
-    'initialize',
-    {
-      clientInfo: { name: 'nanoclaw', title: 'NanoClaw', version: '2.0' },
-      capabilities: { experimentalApi: true },
-    },
-    INIT_TIMEOUT_MS,
-  );
-  if (resp.error) throw new Error(`initialize failed: ${resp.error.message}`);
-  sendCodexNotification(server, 'initialized');
-}
-
-export async function startOrResumeCodexThread(
-  server: AppServer,
-  threadId: string | undefined,
-  params: ThreadParams,
-): Promise<string> {
-  const baseParams = {
-    model: params.model,
-    cwd: params.cwd,
-    approvalPolicy: CODEX_APPROVAL_POLICY,
-    sandbox: CODEX_SANDBOX_MODE,
-    baseInstructions: params.baseInstructions,
-    developerInstructions: params.developerInstructions,
-    personality: 'friendly',
-    sessionStartSource: 'startup',
-    persistExtendedHistory: false,
-  };
-
-  if (threadId) {
-    const resp = await sendCodexRequest(server, 'thread/resume', {
-      threadId,
-      ...baseParams,
-      excludeTurns: true,
-    });
-    if (!resp.error) return threadId;
-    if (!STALE_THREAD_RE.test(resp.error.message)) {
-      throw new Error(`thread/resume failed: ${resp.error.message}`);
-    }
-    log(`Stale thread ${threadId}; starting fresh thread.`);
-  }
-
-  const resp = await sendCodexRequest(server, 'thread/start', {
-    ...baseParams,
-    experimentalRawEvents: false,
-  });
-  if (resp.error) throw new Error(`thread/start failed: ${resp.error.message}`);
-
-  const result = resp.result as { thread?: { id?: string } } | undefined;
-  const newThreadId = result?.thread?.id;
-  if (!newThreadId) throw new Error('thread/start response missing thread ID');
-  return newThreadId;
-}
-
-export async function startCodexTurn(server: AppServer, params: TurnParams): Promise<string> {
-  const resp = await sendCodexRequest(server, 'turn/start', {
-    threadId: params.threadId,
-    input: [{ type: 'text', text: params.inputText, text_elements: [] }],
-    model: params.model,
-    effort: params.effort,
-    cwd: params.cwd,
-  });
-  if (resp.error) throw new Error(`turn/start failed: ${resp.error.message}`);
-  const result = resp.result as { turn?: { id?: string } } | undefined;
-  const turnId = result?.turn?.id;
-  if (!turnId) throw new Error('turn/start response missing turn ID');
-  return turnId;
-}
-
-export async function steerCodexTurn(
-  server: AppServer,
-  threadId: string,
-  turnId: string,
-  inputText: string,
-): Promise<void> {
-  const resp = await sendCodexRequest(server, 'turn/steer', {
-    threadId,
-    expectedTurnId: turnId,
-    input: [{ type: 'text', text: inputText, text_elements: [] }],
-  });
-  if (resp.error) throw new Error(`turn/steer failed: ${resp.error.message}`);
-}
-
-export async function interruptCodexTurn(server: AppServer, threadId: string, turnId: string): Promise<void> {
-  const resp = await sendCodexRequest(server, 'turn/interrupt', { threadId, turnId }, 10_000);
-  if (resp.error) throw new Error(`turn/interrupt failed: ${resp.error.message}`);
-}
-
-// With approval_policy=never the command/patch approval requests don't fire, but the
-// app-server still sends a few non-approval server→client requests (permission
-// negotiation, MCP elicitations, tool calls) that must be answered or the turn hangs.
-// NanoClaw is the boundary, so accept/grant everything.
-export function attachCodexAutoApproval(server: AppServer): void {
-  server.serverRequestHandlers.push((req) => {
-    switch (req.method) {
-      case 'item/commandExecution/requestApproval':
-      case 'item/fileChange/requestApproval':
-        sendCodexResponse(server, req.id, { decision: 'accept' });
-        break;
-      case 'applyPatchApproval':
-      case 'execCommandApproval':
-        sendCodexResponse(server, req.id, { decision: 'approved' });
-        break;
-      case 'item/permissions/requestApproval':
-        sendCodexResponse(server, req.id, {
-          permissions: { fileSystem: { read: ['/'], write: ['/'] }, network: { enabled: true } },
-          scope: 'turn',
-          strictAutoReview: true,
-        });
-        break;
-      case 'item/tool/requestUserInput':
-        sendCodexResponse(server, req.id, { answers: {} });
-        break;
-      case 'mcpServer/elicitation/request':
-        sendCodexResponse(server, req.id, { action: 'cancel', content: null, _meta: null });
-        break;
-      case 'item/tool/call':
-        sendCodexResponse(server, req.id, { success: false, contentItems: [] });
-        break;
-      default:
-        sendCodexError(server, req.id, `Unhandled Codex app-server request: ${req.method}`);
-        break;
-    }
-  });
-}
-
-export function writeCodexConfigToml(
-  servers: Record<string, CodexMcpServer>,
-  opts: { model?: string; effort?: string } = {},
-): void {
-  const codexConfigDir = path.join(process.env.HOME || '/home/node', '.codex');
-  fs.mkdirSync(codexConfigDir, { recursive: true });
-  const configTomlPath = path.join(codexConfigDir, 'config.toml');
-
-  // Instance-level defaults the app-server reads on startup; threads/turns inherit them.
-  const lines: string[] = [
-    `sandbox_mode = ${tomlBasicString(CODEX_SANDBOX_MODE)}`,
-    `approval_policy = ${tomlBasicString(CODEX_APPROVAL_POLICY)}`,
-    `project_doc_max_bytes = ${CODEX_PROJECT_DOC_MAX_BYTES}`,
-  ];
-  if (opts.model) lines.push(`model = ${tomlBasicString(opts.model)}`);
-  if (opts.effort) lines.push(`model_reasoning_effort = ${tomlBasicString(opts.effort)}`);
-  lines.push('');
-
-  for (const [name, config] of Object.entries(servers)) {
-    lines.push(`[mcp_servers.${name}]`);
-    lines.push(`command = ${tomlBasicString(config.command)}`);
-    if (config.args && config.args.length > 0) {
-      lines.push(`args = [${config.args.map(tomlBasicString).join(', ')}]`);
-    }
-    if (config.env && Object.keys(config.env).length > 0) {
-      lines.push(`[mcp_servers.${name}.env]`);
-      for (const [key, value] of Object.entries(config.env)) {
-        lines.push(`${key} = ${tomlBasicString(value)}`);
-      }
-    }
-    lines.push('');
-  }
-
-  fs.writeFileSync(configTomlPath, lines.join('\n'));
-}
-
-export function buildCodexProcessEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
-  const next: NodeJS.ProcessEnv = {};
-  for (const key of CODEX_ENV_ALLOWLIST) {
-    const value = env[key];
-    if (value !== undefined) next[key] = value;
-  }
-  if (!next.CODEX_HOME) next.CODEX_HOME = next.HOME ? path.join(next.HOME, '.codex') : '/home/node/.codex';
-  if (!next.HOME) next.HOME = '/home/node';
-  return next;
-}
-
-export function tomlBasicString(value: string): string {
-  if (value.includes('\n') || value.includes('\r')) {
-    throw new Error(`MCP config value contains newline: ${JSON.stringify(value.slice(0, 40))}`);
-  }
-  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-}
-
-function sendCodexError(server: AppServer, id: number | string, message: string, data?: unknown): void {
-  try {
-    server.process.stdin!.write(JSON.stringify({ id, error: { code: -32000, message, data } }) + '\n');
-  } catch (err) {
-    log(`[send-error] error id=${id}: ${err instanceof Error ? err.message : String(err)}`);
-  }
-}
-
-function isResponse(msg: JsonRpcMessage): msg is JsonRpcResponse {
-  return 'id' in msg && ('result' in msg || 'error' in msg) && !('method' in msg);
-}
-
-function isServerRequest(msg: JsonRpcMessage): msg is JsonRpcServerRequest {
-  return 'id' in msg && 'method' in msg;
-}

container/agent-runner/src/providers/codex-dockerfile.test.ts

@@ -1,30 +0,0 @@
-// Structural guard for the Codex CLI install in container/Dockerfile.
-//
-// @openai/codex is a CLI *binary* installed via the Dockerfile, not an
-// importable package, so the barrel-driven registration tests cannot see it.
-// This test reads the real Dockerfile and asserts the version ARG and the
-// `pnpm install -g` line for @openai/codex are both present. It goes red if
-// either Dockerfile edit is dropped or drifts.
-//
-// Runs under bun (same suite as the container registration test):
-//   cd container/agent-runner && bun test src/providers/codex-dockerfile.test.ts
-
-import { readFileSync } from 'fs';
-import path from 'path';
-
-import { describe, it, expect } from 'bun:test';
-
-// container/agent-runner/src/providers/ -> container/Dockerfile
-const DOCKERFILE = path.join(import.meta.dir, '..', '..', '..', 'Dockerfile');
-
-describe('container/Dockerfile codex CLI install', () => {
-  const dockerfile = readFileSync(DOCKERFILE, 'utf8');
-
-  it('declares the CODEX_VERSION ARG', () => {
-    expect(dockerfile).toMatch(/ARG\s+CODEX_VERSION=/);
-  });
-
-  it('installs the @openai/codex CLI pinned to that ARG', () => {
-    expect(dockerfile).toMatch(/pnpm install -g\s+"@openai\/codex@\$\{CODEX_VERSION\}"/);
-  });
-});

container/agent-runner/src/providers/codex-registration.test.ts

@@ -1,22 +0,0 @@
-/**
- * Integration test for the codex provider's CONTAINER-side reach-in: the self-registration
- * import in container/agent-runner/src/providers/index.ts. Importing the barrel runs
- * codex.ts's top-level registerProvider('codex', …); without that import line
- * createProvider('codex') throws 'Unknown provider' at runtime.
- *
- * Behavior, not structural, and BARREL-ONLY: it imports the real barrel (./index.js),
- * never ./codex.js directly, then asserts listProviderNames() contains the provider. The
- * existing codex.factory.test.ts imports ./codex.js directly, so it self-registers and
- * stays GREEN when the barrel line is deleted — a unit test, not a registration guard.
- * This goes red if the barrel import is deleted/drifts or the barrel fails to evaluate. codex uses the @openai/codex CLI *binary* (not an importable package), so this test does not guard that dependency — the Dockerfile install line is guarded structurally + by the container build (see the skill validate step).
- */
-import { describe, it, expect } from 'bun:test';
-
-import { listProviderNames } from './provider-registry.js';
-import './index.js'; // the real container provider barrel — triggers each provider's registerProvider()
-
-describe('codex provider registration', () => {
-  it('registers codex via the provider barrel', () => {
-    expect(listProviderNames()).toContain('codex');
-  });
-});

container/agent-runner/src/providers/codex.factory.test.ts

@@ -1,17 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-
-import { CodexProvider } from './codex.js';
-
-describe('CodexProvider', () => {
-  it('rejects unsupported reasoning effort values', () => {
-    expect(() => new CodexProvider({ effort: 'max' })).toThrow(/Unsupported Codex reasoning effort/);
-  });
-
-  it('normalizes supported reasoning effort values', () => {
-    expect(new CodexProvider({ effort: 'HIGH' })).toBeInstanceOf(CodexProvider);
-  });
-
-  it('accepts supported reasoning effort values', () => {
-    expect(new CodexProvider({ effort: 'xhigh' })).toBeInstanceOf(CodexProvider);
-  });
-});

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

@@ -1,419 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-import { registerProvider } from './provider-registry.js';
-import type {
-  AgentProvider,
-  AgentQuery,
-  McpServerConfig,
-  ProviderEvent,
-  ProviderExchange,
-  ProviderOptions,
-  QueryInput,
-} from './types.js';
-import { archiveProviderExchange } from './exchange-archive.js';
-import {
-  type AppServer,
-  type CodexReasoningEffort,
-  type JsonRpcNotification,
-  STALE_THREAD_RE,
-  attachCodexAutoApproval,
-  initializeCodexAppServer,
-  interruptCodexTurn,
-  killCodexAppServer,
-  spawnCodexAppServer,
-  startCodexTurn,
-  startOrResumeCodexThread,
-  steerCodexTurn,
-  writeCodexConfigToml,
-} from './codex-app-server.js';
-
-const TURN_TIMEOUT_MS = 10 * 60 * 1000;
-const SUPPORTED_EFFORTS = new Set<CodexReasoningEffort>(['none', 'minimal', 'low', 'medium', 'high', 'xhigh']);
-
-export interface CodexRuntimeDeps {
-  writeCodexConfigToml: typeof writeCodexConfigToml;
-  spawnCodexAppServer: typeof spawnCodexAppServer;
-  attachCodexAutoApproval: typeof attachCodexAutoApproval;
-  initializeCodexAppServer: typeof initializeCodexAppServer;
-  startOrResumeCodexThread: typeof startOrResumeCodexThread;
-  startCodexTurn: typeof startCodexTurn;
-  steerCodexTurn: typeof steerCodexTurn;
-  interruptCodexTurn: typeof interruptCodexTurn;
-  killCodexAppServer: typeof killCodexAppServer;
-}
-
-const defaultCodexRuntimeDeps: CodexRuntimeDeps = {
-  writeCodexConfigToml,
-  spawnCodexAppServer,
-  attachCodexAutoApproval,
-  initializeCodexAppServer,
-  startOrResumeCodexThread,
-  startCodexTurn,
-  steerCodexTurn,
-  interruptCodexTurn,
-  killCodexAppServer,
-};
-
-function classifyError(message: string): string | undefined {
-  if (/auth|api key|unauthorized|login|credential/i.test(message)) return 'auth';
-  if (/quota|rate limit|insufficient|billing|credit/i.test(message)) return 'quota';
-  if (/sandbox|permission|denied/i.test(message)) return 'sandbox';
-  if (/thread|conversation|session/i.test(message)) return 'stale-session';
-  return undefined;
-}
-
-function normalizeEffort(effort: string | undefined): CodexReasoningEffort | undefined {
-  const normalized = effort?.trim().toLowerCase();
-  if (!normalized) return undefined;
-  if (!SUPPORTED_EFFORTS.has(normalized as CodexReasoningEffort)) {
-    throw new Error(`Unsupported Codex reasoning effort: ${effort}`);
-  }
-  return normalized as CodexReasoningEffort;
-}
-
-export class CodexProvider implements AgentProvider {
-  readonly supportsNativeSlashCommands = false;
-  // Codex has no native NanoClaw memory — opt in to the runner's persistent
-  // memory/ scaffold (see memory-scaffold.ts).
-  readonly usesMemoryScaffold = true;
-  // The app-server keeps history server-side; there is no on-disk transcript,
-  // so the provider persists each exchange itself into `conversations/`
-  // (see exchange-archive.ts). The poll-loop reports exchanges through this
-  // hook and does nothing else — archiving is payload code, not runner code.
-  onExchangeComplete(exchange: ProviderExchange): void {
-    archiveProviderExchange({
-      provider: 'codex',
-      prompt: exchange.prompt,
-      result: exchange.result,
-      continuation: exchange.continuation,
-      status: exchange.status,
-    });
-  }
-
-  private readonly mcpServers: Record<string, McpServerConfig>;
-  private readonly model?: string;
-  private readonly effort?: CodexReasoningEffort;
-  private readonly runtime: CodexRuntimeDeps;
-
-  constructor(options: ProviderOptions = {}, runtime: CodexRuntimeDeps = defaultCodexRuntimeDeps) {
-    this.mcpServers = options.mcpServers ?? {};
-    this.model = options.model;
-    this.runtime = runtime;
-    this.effort = normalizeEffort(options.effort);
-  }
-
-  isSessionInvalid(err: unknown): boolean {
-    const msg = err instanceof Error ? err.message : String(err);
-    return STALE_THREAD_RE.test(msg);
-  }
-
-  query(input: QueryInput): AgentQuery {
-    const pending: string[] = [input.prompt];
-    let waiting: (() => void) | null = null;
-    let ended = false;
-    let aborted = false;
-    let activeServer: AppServer | null = null;
-    let activeThreadId: string | null = null;
-    let activeTurnId: string | null = null;
-    let wakeActiveTurn: (() => void) | null = null;
-
-    const wake = (): void => {
-      waiting?.();
-      waiting = null;
-    };
-
-    const pushOrSteer = (message: string): void => {
-      if (activeServer && activeThreadId && activeTurnId) {
-        void this.runtime.steerCodexTurn(activeServer, activeThreadId, activeTurnId, message).catch(() => {
-          pending.push(message);
-          wake();
-        });
-        return;
-      }
-      pending.push(message);
-      wake();
-    };
-
-    const self = this;
-
-    async function* gen(): AsyncGenerator<ProviderEvent> {
-      self.runtime.writeCodexConfigToml(self.mcpServers, { model: self.model, effort: self.effort });
-      const server = self.runtime.spawnCodexAppServer();
-      activeServer = server;
-      self.runtime.attachCodexAutoApproval(server);
-
-      let threadId: string | undefined = input.continuation;
-      let initYielded = false;
-
-      try {
-        await self.runtime.initializeCodexAppServer(server);
-        threadId = await self.runtime.startOrResumeCodexThread(server, threadId, {
-          model: self.model,
-          cwd: input.cwd,
-          baseInstructions: input.systemContext?.instructions,
-        });
-        activeThreadId = threadId;
-
-        while (!aborted) {
-          while (pending.length === 0 && !ended && !aborted) {
-            await new Promise<void>((resolve) => {
-              waiting = resolve;
-            });
-          }
-          if (aborted) return;
-          if (pending.length === 0 && ended) return;
-
-          const text = pending.shift()!;
-          yield* runOneTurn(
-            server,
-            threadId,
-            text,
-            self.model,
-            self.effort,
-            input.cwd,
-            (turnId) => {
-              activeTurnId = turnId;
-            },
-            () => {
-              activeTurnId = null;
-            },
-            () => initYielded,
-            () => {
-              initYielded = true;
-            },
-            () => aborted,
-            (waker) => {
-              wakeActiveTurn = waker;
-            },
-            self.runtime.startCodexTurn,
-          );
-        }
-      } finally {
-        activeTurnId = null;
-        activeThreadId = null;
-        activeServer = null;
-        wakeActiveTurn = null;
-        self.runtime.killCodexAppServer(server);
-      }
-    }
-
-    return {
-      push: pushOrSteer,
-      end: () => {
-        ended = true;
-        wake();
-      },
-      abort: () => {
-        aborted = true;
-        if (activeServer && activeThreadId && activeTurnId) {
-          void this.runtime.interruptCodexTurn(activeServer, activeThreadId, activeTurnId).catch(() => {});
-        }
-        wakeActiveTurn?.();
-        wake();
-      },
-      events: gen(),
-    };
-  }
-}
-
-async function* runOneTurn(
-  server: AppServer,
-  threadId: string,
-  inputText: string,
-  model: string | undefined,
-  effort: string | undefined,
-  cwd: string,
-  setActiveTurn: (turnId: string) => void,
-  clearActiveTurn: () => void,
-  hasInit: () => boolean,
-  markInit: () => void,
-  isAborted: () => boolean,
-  setAbortWaker: (waker: (() => void) | null) => void,
-  startTurn: typeof startCodexTurn,
-): AsyncGenerator<ProviderEvent> {
-  const state: { error: Error | null } = { error: null };
-  let resultText = '';
-  let turnDone = false;
-  let turnId: string | null = null;
-
-  // A finished turn can no longer absorb steered input: codex's turn/steer
-  // against a completed turn resolves as a no-op, so a follow-up routed there
-  // is lost silently. Clear the active-turn marker the moment the turn ends —
-  // before the generator drains and tears down in its `finally` — so
-  // pushOrSteer queues any racing follow-up into a fresh turn instead.
-  const finishTurn = (): void => {
-    turnDone = true;
-    clearActiveTurn();
-  };
-
-  const buffer: ProviderEvent[] = [];
-  let waker: (() => void) | null = null;
-  const kick = (): void => {
-    waker?.();
-    waker = null;
-  };
-  setAbortWaker(kick);
-
-  const handler = (n: JsonRpcNotification): void => {
-    const method = n.method;
-    const params = n.params ?? {};
-    buffer.push({ type: 'activity' });
-
-    switch (method) {
-      case 'thread/started': {
-        const thread = params.thread as { id?: string } | undefined;
-        if (thread?.id && !hasInit()) {
-          markInit();
-          buffer.push({ type: 'init', continuation: thread.id });
-        }
-        break;
-      }
-      case 'turn/started': {
-        const turn = params.turn as { id?: string } | undefined;
-        if (turn?.id) {
-          turnId = turn.id;
-          setActiveTurn(turn.id);
-        }
-        break;
-      }
-      case 'item/agentMessage/delta': {
-        const delta = params.delta as string | undefined;
-        if (delta) resultText += delta;
-        break;
-      }
-      case 'item/completed': {
-        const item = params.item as { type?: string; text?: string } | undefined;
-        if (item?.type === 'agentMessage' && item.text) resultText = item.text;
-        break;
-      }
-      case 'thread/status/changed': {
-        const status = params.status as string | undefined;
-        if (status) buffer.push({ type: 'progress', message: `status: ${status}` });
-        break;
-      }
-      case 'error': {
-        const err = params.error as { message?: string; additionalDetails?: string | null } | undefined;
-        const msg = [err?.message, err?.additionalDetails].filter(Boolean).join(': ') || 'Codex turn failed';
-        state.error = new Error(msg);
-        finishTurn();
-        break;
-      }
-      case 'turn/completed': {
-        const turn = params.turn as
-          | { error?: { message?: string; additionalDetails?: string | null } | null; items?: unknown[] }
-          | undefined;
-        const agentMessage = turn?.items
-          ?.filter((item): item is { type: string; text?: string } => typeof item === 'object' && item !== null)
-          .find((item) => item.type === 'agentMessage' && item.text);
-        if (agentMessage?.text) resultText = agentMessage.text;
-        if (turn?.error) {
-          const msg =
-            [turn.error.message, turn.error.additionalDetails].filter(Boolean).join(': ') || 'Codex turn failed';
-          state.error = new Error(msg);
-        }
-        finishTurn();
-        break;
-      }
-      default:
-        break;
-    }
-
-    kick();
-  };
-
-  server.notificationHandlers.push(handler);
-
-  // A dead app-server can't send the notification this turn is parked on —
-  // end the turn immediately with the real cause instead of the 10-min timeout.
-  const onServerExit = (err: Error): void => {
-    if (turnDone) return;
-    state.error = err;
-    finishTurn();
-    kick();
-  };
-  server.exitHandlers.push(onServerExit);
-
-  const timer = setTimeout(() => {
-    state.error = new Error(`Turn timed out after ${TURN_TIMEOUT_MS}ms`);
-    finishTurn();
-    kick();
-  }, TURN_TIMEOUT_MS);
-
-  try {
-    if (!hasInit()) {
-      markInit();
-      buffer.push({ type: 'init', continuation: threadId });
-    }
-
-    turnId = await startTurn(server, {
-      threadId,
-      inputText,
-      model,
-      effort,
-      cwd,
-    });
-    setActiveTurn(turnId);
-    const imagesBefore = listGeneratedImages(threadId);
-    if (isAborted()) return;
-
-    while (true) {
-      while (buffer.length > 0) {
-        yield buffer.shift()!;
-      }
-      if (turnDone || isAborted()) break;
-      await new Promise<void>((resolve) => {
-        waker = resolve;
-      });
-      waker = null;
-    }
-
-    while (buffer.length > 0) yield buffer.shift()!;
-
-    if (isAborted()) return;
-
-    if (state.error) {
-      yield {
-        type: 'error',
-        message: state.error.message,
-        retryable: false,
-        classification: classifyError(state.error.message),
-      };
-      throw state.error;
-    }
-
-    for (const imagePath of listGeneratedImages(threadId)) {
-      if (!imagesBefore.has(imagePath)) {
-        yield { type: 'file', path: imagePath };
-      }
-    }
-
-    yield { type: 'result', text: resultText || null };
-  } finally {
-    clearTimeout(timer);
-    clearActiveTurn();
-    setAbortWaker(null);
-    const idx = server.notificationHandlers.indexOf(handler);
-    if (idx >= 0) server.notificationHandlers.splice(idx, 1);
-    const exitIdx = server.exitHandlers.indexOf(onServerExit);
-    if (exitIdx >= 0) server.exitHandlers.splice(exitIdx, 1);
-  }
-}
-
-/**
- * Codex's built-in image generation saves into CODEX_HOME/generated_images/
- * <threadId>/ — its native client renders those to the user, so the model
- * believes delivery already happened and won't send_file them. The runner
- * must deliver them itself: snapshot the dir at turn start, emit a `file`
- * event for anything new at turn end.
- */
-function listGeneratedImages(threadId: string): Set<string> {
-  const dir = path.join(process.env.CODEX_HOME || '/home/node/.codex', 'generated_images', threadId);
-  try {
-    return new Set(fs.readdirSync(dir).map((f) => path.join(dir, f)));
-  } catch {
-    return new Set();
-  }
-}
-
-registerProvider('codex', (opts) => new CodexProvider(opts));

container/agent-runner/src/providers/codex.turns.test.ts

@@ -1,267 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import { CodexProvider, type CodexRuntimeDeps } from './codex.js';
-import type { AppServer, JsonRpcNotification, TurnParams } from './codex-app-server.js';
-import type { ProviderEvent } from './types.js';
-
-describe('CodexProvider active turns', () => {
-  it('steers follow-ups into the active turn and yields liveness activity', async () => {
-    const fake = createFakeCodexRuntime();
-    const provider = new CodexProvider({}, fake.runtime);
-    const query = provider.query({ prompt: 'first prompt', cwd: '/workspace/agent' });
-    const events: ProviderEvent[] = [];
-
-    const collect = collectEvents(query.events, events);
-
-    await waitFor(() => fake.startCalls.length === 1);
-    query.push('follow-up prompt');
-    await waitFor(() => fake.steerCalls.length === 1);
-    query.end();
-    fake.completeTurn('final answer');
-
-    await collect;
-
-    expect(fake.startCalls).toHaveLength(1);
-    expect(fake.startCalls[0].inputText).toBe('first prompt');
-    expect(fake.steerCalls).toEqual([{ threadId: 'thread-1', turnId: 'turn-1', inputText: 'follow-up prompt' }]);
-    expect(events.filter((event) => event.type === 'activity').length).toBeGreaterThanOrEqual(2);
-    expect(events.filter((event) => event.type === 'result')).toEqual([{ type: 'result', text: 'final answer' }]);
-    expect(fake.killed).toBe(true);
-  });
-
-  it('queues follow-ups for the next turn when steering is rejected', async () => {
-    const fake = createFakeCodexRuntime({ rejectSteer: true });
-    const provider = new CodexProvider({}, fake.runtime);
-    const query = provider.query({ prompt: 'first prompt', cwd: '/workspace/agent' });
-    const events: ProviderEvent[] = [];
-
-    const collect = collectEvents(query.events, events);
-
-    await waitFor(() => fake.startCalls.length === 1);
-    query.push('queued follow-up');
-    await waitFor(() => fake.steerCalls.length === 1);
-    await sleep(0);
-
-    fake.completeTurn('first answer');
-    await waitFor(() => fake.startCalls.length === 2);
-    query.end();
-    fake.completeTurn('second answer');
-
-    await collect;
-
-    expect(fake.startCalls.map((call) => call.inputText)).toEqual(['first prompt', 'queued follow-up']);
-    expect(fake.steerCalls).toHaveLength(1);
-    expect(events.filter((event) => event.type === 'result')).toEqual([
-      { type: 'result', text: 'first answer' },
-      { type: 'result', text: 'second answer' },
-    ]);
-  });
-
-  it('queues a follow-up that races turn completion into a new turn, never steering the finished turn', async () => {
-    const fake = createFakeCodexRuntime();
-    const provider = new CodexProvider({}, fake.runtime);
-    const query = provider.query({ prompt: 'first prompt', cwd: '/workspace/agent' });
-    const events: ProviderEvent[] = [];
-
-    const collect = collectEvents(query.events, events);
-
-    await waitFor(() => fake.startCalls.length === 1);
-
-    // The turn completes, then a follow-up lands in the same tick — before the
-    // generator has drained and torn the turn down. codex's turn/steer no-ops
-    // on a finished turn (resolves without error), so steering here would drop
-    // the message silently. It must start a fresh turn instead.
-    fake.completeTurn('first answer');
-    query.push('racing follow-up');
-
-    await waitFor(() => fake.startCalls.length === 2);
-    query.end();
-    fake.completeTurn('second answer');
-
-    await collect;
-
-    expect(fake.steerCalls).toHaveLength(0);
-    expect(fake.startCalls.map((call) => call.inputText)).toEqual(['first prompt', 'racing follow-up']);
-    expect(events.filter((event) => event.type === 'result')).toEqual([
-      { type: 'result', text: 'first answer' },
-      { type: 'result', text: 'second answer' },
-    ]);
-  });
-
-  it('interrupts the active turn and closes the stream on abort', async () => {
-    const fake = createFakeCodexRuntime();
-    const provider = new CodexProvider({}, fake.runtime);
-    const query = provider.query({ prompt: 'first prompt', cwd: '/workspace/agent' });
-    const events: ProviderEvent[] = [];
-
-    const collect = collectEvents(query.events, events);
-
-    await waitFor(() => fake.startCalls.length === 1);
-    query.abort();
-
-    await collect;
-
-    expect(fake.interruptCalls).toEqual([{ threadId: 'thread-1', turnId: 'turn-1' }]);
-    expect(events.some((event) => event.type === 'result')).toBe(false);
-    expect(fake.killed).toBe(true);
-  });
-
-  it('threads the configured model and effort into the turn', async () => {
-    const fake = createFakeCodexRuntime();
-    const provider = new CodexProvider({ model: 'gpt-5.5', effort: 'high' }, fake.runtime);
-    const query = provider.query({ prompt: 'first prompt', cwd: '/workspace/agent' });
-    const events: ProviderEvent[] = [];
-
-    const collect = collectEvents(query.events, events);
-
-    await waitFor(() => fake.startCalls.length === 1);
-    query.end();
-    fake.completeTurn('final answer');
-
-    await collect;
-
-    expect(fake.startCalls[0].model).toBe('gpt-5.5');
-    expect(fake.startCalls[0].effort).toBe('high');
-    expect(events.filter((event) => event.type === 'result')).toEqual([{ type: 'result', text: 'final answer' }]);
-  });
-
-  it('delivers harness-generated images as file events — the model never sends them itself', async () => {
-    const codexHome = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-home-'));
-    const prevHome = process.env.CODEX_HOME;
-    process.env.CODEX_HOME = codexHome;
-    try {
-      const fake = createFakeCodexRuntime();
-      const provider = new CodexProvider({}, fake.runtime);
-      const query = provider.query({ prompt: 'make an image', cwd: '/workspace/agent' });
-      const events: ProviderEvent[] = [];
-      const collect = collectEvents(query.events, events);
-
-      await waitFor(() => fake.startCalls.length === 1);
-      // Codex's built-in image_gen writes into CODEX_HOME mid-turn.
-      const imagesDir = path.join(codexHome, 'generated_images', 'thread-1');
-      fs.mkdirSync(imagesDir, { recursive: true });
-      fs.writeFileSync(path.join(imagesDir, 'ig_abc.png'), 'png-bytes');
-
-      query.end();
-      fake.completeTurn('Here you go — created the image.');
-      await collect;
-
-      const files = events.filter((event) => event.type === 'file') as Array<{ type: 'file'; path: string }>;
-      expect(files).toHaveLength(1);
-      expect(files[0].path).toBe(path.join(imagesDir, 'ig_abc.png'));
-      // file events arrive before the result so delivery shares the turn.
-      expect(events.findIndex((e) => e.type === 'file')).toBeLessThan(events.findIndex((e) => e.type === 'result'));
-    } finally {
-      if (prevHome === undefined) delete process.env.CODEX_HOME;
-      else process.env.CODEX_HOME = prevHome;
-      fs.rmSync(codexHome, { recursive: true, force: true });
-    }
-  });
-
-  it('ends the turn immediately with the real cause when the app-server dies mid-turn', async () => {
-    const fake = createFakeCodexRuntime();
-    const provider = new CodexProvider({}, fake.runtime);
-    const query = provider.query({ prompt: 'prompt', cwd: '/workspace/agent' });
-    const events: ProviderEvent[] = [];
-
-    const collect = collectEvents(query.events, events);
-    await waitFor(() => fake.startCalls.length === 1);
-
-    // No pending request exists mid-turn (turn/start already resolved), so
-    // only the exitHandlers seam can end the turn — without it this parks
-    // on the waker until the 10-minute turn timeout.
-    fake.crashServer(new Error('Codex app-server exited: code=1 signal=null'));
-
-    // The generator yields the error event, then rethrows to its consumer.
-    await collect.catch(() => {});
-
-    const errors = events.filter((event) => event.type === 'error');
-    expect(errors).toHaveLength(1);
-    expect((errors[0] as { message: string }).message).toContain('app-server exited');
-  });
-});
-
-function createFakeCodexRuntime(opts: { rejectSteer?: boolean } = {}) {
-  const server = fakeServer();
-  const startCalls: TurnParams[] = [];
-  const steerCalls: Array<{ threadId: string; turnId: string; inputText: string }> = [];
-  const interruptCalls: Array<{ threadId: string; turnId: string }> = [];
-  let killed = false;
-
-  const notify = (method: string, params?: Record<string, unknown>): void => {
-    const notification: JsonRpcNotification = { method, params };
-    for (const handler of [...server.notificationHandlers]) handler(notification);
-  };
-
-  const runtime: CodexRuntimeDeps = {
-    writeCodexConfigToml: () => {},
-    spawnCodexAppServer: () => server,
-    attachCodexAutoApproval: () => {},
-    initializeCodexAppServer: async () => {},
-    startOrResumeCodexThread: async (_server, threadId) => threadId ?? 'thread-1',
-    startCodexTurn: async (_server, params) => {
-      startCalls.push(params);
-      const turnId = `turn-${startCalls.length}`;
-      notify('turn/started', { turn: { id: turnId } });
-      return turnId;
-    },
-    steerCodexTurn: async (_server, threadId, turnId, inputText) => {
-      steerCalls.push({ threadId, turnId, inputText });
-      if (opts.rejectSteer) throw new Error('steer rejected');
-    },
-    interruptCodexTurn: async (_server, threadId, turnId) => {
-      interruptCalls.push({ threadId, turnId });
-    },
-    killCodexAppServer: () => {
-      killed = true;
-    },
-  };
-
-  return {
-    runtime,
-    startCalls,
-    steerCalls,
-    interruptCalls,
-    get killed() {
-      return killed;
-    },
-    completeTurn(text: string) {
-      notify('turn/completed', { turn: { items: [{ type: 'agentMessage', text }] } });
-    },
-    crashServer(err: Error) {
-      for (const h of [...server.exitHandlers]) h(err);
-    },
-  };
-}
-
-function fakeServer(): AppServer {
-  return {
-    process: { stdin: { write: () => true }, kill: () => true },
-    readline: { close: () => {} },
-    pending: new Map(),
-    notificationHandlers: [],
-    exitHandlers: [],
-    serverRequestHandlers: [],
-  } as unknown as AppServer;
-}
-
-async function collectEvents(events: AsyncIterable<ProviderEvent>, sink: ProviderEvent[]): Promise<void> {
-  for await (const event of events) {
-    sink.push(event);
-  }
-}
-
-async function waitFor(condition: () => boolean, timeoutMs = 1000): Promise<void> {
-  const start = Date.now();
-  while (!condition()) {
-    if (Date.now() - start > timeoutMs) throw new Error('waitFor timeout');
-    await sleep(10);
-  }
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

container/agent-runner/src/providers/exchange-archive.test.ts

@@ -1,73 +0,0 @@
-import { afterEach, describe, expect, it } from 'bun:test';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import { archiveProviderExchange } from './exchange-archive.js';
-
-let tmpDir: string | null = null;
-
-afterEach(() => {
-  if (tmpDir) {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-    tmpDir = null;
-  }
-});
-
-function makeTmpDir(): string {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nanoclaw-archive-'));
-  return tmpDir;
-}
-
-describe('provider exchange archive', () => {
-  it('writes unique exchange-level archives with provider metadata', () => {
-    const conversationsDir = makeTmpDir();
-    const timestamp = new Date('2026-06-03T12:34:56.789Z');
-
-    const first = archiveProviderExchange({
-      conversationsDir,
-      provider: 'codex',
-      prompt: 'hello',
-      result: 'world',
-      continuation: 'thread-123',
-      status: 'completed',
-      timestamp,
-    });
-    const second = archiveProviderExchange({
-      conversationsDir,
-      provider: 'codex',
-      prompt: 'hello again',
-      result: 'world again',
-      continuation: 'thread-123',
-      status: 'completed',
-      timestamp,
-    });
-
-    expect(first).not.toBeNull();
-    expect(second).not.toBeNull();
-    expect(first).not.toBe(second);
-
-    const content = fs.readFileSync(path.join(conversationsDir, first!), 'utf-8');
-    expect(content).toContain('# Codex Exchange');
-    expect(content).toContain('Provider: codex');
-    expect(content).toContain('Continuation/thread id: thread-123');
-    expect(content).toContain('Status: completed');
-    expect(content).toContain('**User**: hello');
-    expect(content).toContain('**Assistant**: world');
-  });
-
-  it('skips empty result text', () => {
-    const conversationsDir = makeTmpDir();
-    const filename = archiveProviderExchange({
-      conversationsDir,
-      provider: 'codex',
-      prompt: 'hello',
-      result: '   ',
-      continuation: 'thread-123',
-      status: 'completed',
-    });
-
-    expect(filename).toBeNull();
-    expect(fs.readdirSync(conversationsDir)).toHaveLength(0);
-  });
-});

container/agent-runner/src/providers/exchange-archive.ts

@@ -1,88 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-/**
- * Per-exchange markdown archive for providers with no on-disk transcript —
- * payload code, shipped with the provider that needs it. The provider's
- * `onExchangeComplete` hook (see types.ts) calls this with each completed
- * exchange; the runner never archives on a provider's behalf.
- */
-
-const DEFAULT_CONVERSATIONS_DIR = '/workspace/agent/conversations';
-
-export interface ProviderExchangeArchiveOptions {
-  provider: string;
-  prompt: string;
-  result: string | null | undefined;
-  continuation?: string;
-  status: string;
-  timestamp?: Date;
-  conversationsDir?: string;
-}
-
-/**
- * Archive a single prompt/result exchange. Returns the written filename, or
- * null when there is nothing to archive (empty result).
- */
-export function archiveProviderExchange(options: ProviderExchangeArchiveOptions): string | null {
-  const result = options.result?.trim();
-  if (!result) return null;
-
-  const timestamp = options.timestamp ?? new Date();
-  const conversationsDir =
-    options.conversationsDir || process.env.NANOCLAW_CONVERSATIONS_DIR || DEFAULT_CONVERSATIONS_DIR;
-  fs.mkdirSync(conversationsDir, { recursive: true });
-
-  const filename = uniqueArchiveFilename(conversationsDir, options.provider, options.continuation, timestamp);
-  const lines = [
-    `# ${titleCase(options.provider)} Exchange`,
-    '',
-    `Archived: ${timestamp.toISOString()}`,
-    `Provider: ${options.provider}`,
-    `Continuation/thread id: ${options.continuation || '(none)'}`,
-    `Status: ${options.status}`,
-    '',
-    '---',
-    '',
-    `**User**: ${truncate(options.prompt)}`,
-    '',
-    `**Assistant**: ${truncate(result)}`,
-    '',
-  ];
-  fs.writeFileSync(path.join(conversationsDir, filename), lines.join('\n'));
-  return filename;
-}
-
-function uniqueArchiveFilename(
-  dir: string,
-  provider: string,
-  continuation: string | undefined,
-  timestamp: Date,
-): string {
-  const date = timestamp.toISOString().split('T')[0];
-  const time = timestamp.toISOString().replace(/[-:.TZ]/g, '').slice(8, 17);
-  const thread = sanitizeSlug(continuation || 'no-thread').slice(0, 24) || 'no-thread';
-  const base = `${date}-${sanitizeSlug(provider)}-${time}-${thread}`;
-  let filename = `${base}.md`;
-  let counter = 2;
-  while (fs.existsSync(path.join(dir, filename))) {
-    filename = `${base}-${counter}.md`;
-    counter += 1;
-  }
-  return filename;
-}
-
-function sanitizeSlug(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
-function titleCase(value: string): string {
-  return value ? value[0].toUpperCase() + value.slice(1) : 'Provider';
-}
-
-function truncate(value: string): string {
-  return value.length > 2000 ? value.slice(0, 2000) + '...' : value;
-}

container/agent-runner/src/providers/factory.test.ts

@@ -2,7 +2,6 @@ import { describe, it, expect } from 'bun:test';
 
 import { createProvider, type ProviderName } from './factory.js';
 import { ClaudeProvider } from './claude.js';
-import { CodexProvider } from './codex.js';
 import { MockProvider } from './mock.js';
 
 describe('createProvider', () => {
@@ -10,10 +9,6 @@ describe('createProvider', () => {
     expect(createProvider('claude')).toBeInstanceOf(ClaudeProvider);
   });
 
-  it('returns CodexProvider for codex', () => {
-    expect(createProvider('codex')).toBeInstanceOf(CodexProvider);
-  });
-
   it('returns MockProvider for mock', () => {
     expect(createProvider('mock')).toBeInstanceOf(MockProvider);
   });

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

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

container/agent-runner/src/providers/mcp-to-opencode.test.ts

@@ -1,59 +0,0 @@
-import { describe, it, expect } from 'bun:test';
-
-import { mcpServersToOpenCodeConfig } from './mcp-to-opencode.js';
-
-describe('mcpServersToOpenCodeConfig', () => {
-  it('maps nanoclaw + extra server like v2 index.ts merge', () => {
-    const servers = {
-      nanoclaw: {
-        command: 'node',
-        args: ['/app/src/mcp-tools/index.js'],
-        env: {
-          SESSION_INBOUND_DB_PATH: '/workspace/inbound.db',
-          SESSION_OUTBOUND_DB_PATH: '/workspace/outbound.db',
-          SESSION_HEARTBEAT_PATH: '/workspace/.heartbeat',
-        },
-      },
-      extra: {
-        command: 'npx',
-        args: ['-y', 'some-mcp'],
-        env: { FOO: 'bar' },
-      },
-    };
-
-    const mcp = mcpServersToOpenCodeConfig(servers);
-
-    expect(mcp.nanoclaw).toEqual({
-      type: 'local',
-      command: ['node', '/app/src/mcp-tools/index.js'],
-      environment: {
-        SESSION_INBOUND_DB_PATH: '/workspace/inbound.db',
-        SESSION_OUTBOUND_DB_PATH: '/workspace/outbound.db',
-        SESSION_HEARTBEAT_PATH: '/workspace/.heartbeat',
-      },
-      enabled: true,
-    });
-
-    expect(mcp.extra).toEqual({
-      type: 'local',
-      command: ['npx', '-y', 'some-mcp'],
-      environment: { FOO: 'bar' },
-      enabled: true,
-    });
-  });
-
-  it('omits environment when env is empty', () => {
-    const mcp = mcpServersToOpenCodeConfig({
-      x: { command: 'true', args: [], env: {} },
-    });
-    expect(mcp.x).toEqual({
-      type: 'local',
-      command: ['true'],
-      enabled: true,
-    });
-  });
-
-  it('returns empty record for undefined', () => {
-    expect(mcpServersToOpenCodeConfig(undefined)).toEqual({});
-  });
-});

container/agent-runner/src/providers/mcp-to-opencode.ts

@@ -1,39 +0,0 @@
-import type { McpServerConfig } from './types.js';
-
-/** OpenCode `mcp` entry shape (local stdio server). */
-export type OpenCodeMcpLocal = {
-  type: 'local';
-  command: string[];
-  environment?: Record<string, string>;
-  enabled: true;
-};
-
-/** OpenCode `mcp` entry shape (remote HTTP server). */
-export type OpenCodeMcpRemote = {
-  type: 'remote';
-  url: string;
-  headers?: Record<string, string>;
-  enabled: true;
-};
-
-export type OpenCodeMcpEntry = OpenCodeMcpLocal | OpenCodeMcpRemote;
-
-/**
- * Map NanoClaw v2 MCP definitions (same shape as Claude Agent SDK) into
- * OpenCode config `mcp` field. Stdio-only until `McpServerConfig` gains remote.
- */
-export function mcpServersToOpenCodeConfig(
-  servers: Record<string, McpServerConfig> | undefined,
-): Record<string, OpenCodeMcpEntry> {
-  const out: Record<string, OpenCodeMcpEntry> = {};
-  if (!servers) return out;
-  for (const [name, cfg] of Object.entries(servers)) {
-    out[name] = {
-      type: 'local',
-      command: [cfg.command, ...cfg.args],
-      ...(Object.keys(cfg.env).length > 0 ? { environment: cfg.env } : {}),
-      enabled: true,
-    };
-  }
-  return out;
-}

container/agent-runner/src/providers/opencode-registration.test.ts

@@ -1,22 +0,0 @@
-/**
- * Integration test for the opencode provider's CONTAINER-side reach-in: the self-registration
- * import in container/agent-runner/src/providers/index.ts. Importing the barrel runs
- * opencode.ts's top-level registerProvider('opencode', …); without that import line
- * createProvider('opencode') throws 'Unknown provider' at runtime.
- *
- * Behavior, not structural, and BARREL-ONLY: it imports the real barrel (./index.js),
- * never ./opencode.js directly, then asserts listProviderNames() contains the provider. The
- * existing opencode.factory.test.ts imports ./opencode.js directly, so it self-registers and
- * stays GREEN when the barrel line is deleted — a unit test, not a registration guard.
- * This goes red if the barrel import is deleted/drifts or the barrel fails to evaluate, or if @opencode-ai/sdk is not installed (the unmocked barrel import throws) — so it also implicitly guards that dependency.
- */
-import { describe, it, expect } from 'bun:test';
-
-import { listProviderNames } from './provider-registry.js';
-import './index.js'; // the real container provider barrel — triggers each provider's registerProvider()
-
-describe('opencode provider registration', () => {
-  it('registers opencode via the provider barrel', () => {
-    expect(listProviderNames()).toContain('opencode');
-  });
-});

container/agent-runner/src/providers/opencode.factory.test.ts

@@ -1,10 +0,0 @@
-import { describe, it, expect } from 'bun:test';
-
-import { createProvider } from './factory.js';
-import { OpenCodeProvider } from './opencode.js';
-
-describe('createProvider (opencode)', () => {
-  it('returns OpenCodeProvider for opencode', () => {
-    expect(createProvider('opencode')).toBeInstanceOf(OpenCodeProvider);
-  });
-});

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

@@ -1,423 +0,0 @@
-import { spawn, type ChildProcess } from 'child_process';
-
-import { createOpencodeClient, type OpencodeClient } from '@opencode-ai/sdk';
-
-import { registerProvider } from './provider-registry.js';
-import type { AgentProvider, AgentQuery, ProviderEvent, ProviderOptions, QueryInput } from './types.js';
-import { mcpServersToOpenCodeConfig } from './mcp-to-opencode.js';
-
-function log(msg: string): void {
-  console.error(`[opencode-provider] ${msg}`);
-}
-
-const SESSION_STATUS_RETRY_ERROR_AFTER = 3;
-
-/** Stale / dead OpenCode session heuristics (complement Claude-centric host patterns). */
-const STALE_SESSION_RE =
-  /no conversation found|ENOENT.*\.jsonl|session.*not found|NotFoundError|connection reset|ECONNRESET|404|event timeout/i;
-
-function killProcessTree(proc: ChildProcess): void {
-  if (!proc.pid) return;
-  try {
-    process.kill(-proc.pid, 'SIGKILL');
-  } catch {
-    try {
-      proc.kill('SIGKILL');
-    } catch {
-      /* ignore */
-    }
-  }
-}
-
-function spawnOpencodeServer(config: Record<string, unknown>, timeoutMs = 10_000): Promise<{ url: string; proc: ChildProcess }> {
-  return new Promise((resolve, reject) => {
-    const hostname = '127.0.0.1';
-    const port = 4096;
-    const proc = spawn('opencode', ['serve', `--hostname=${hostname}`, `--port=${port}`], {
-      env: {
-        ...process.env,
-        OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
-      },
-      detached: true,
-    });
-
-    const id = setTimeout(() => {
-      killProcessTree(proc);
-      reject(new Error(`Timeout waiting for OpenCode server to start after ${timeoutMs}ms`));
-    }, timeoutMs);
-
-    let output = '';
-    proc.stdout?.on('data', (chunk: Buffer) => {
-      output += chunk.toString();
-      for (const line of output.split('\n')) {
-        if (line.startsWith('opencode server listening')) {
-          const match = line.match(/on\s+(https?:\/\/[^\s]+)/);
-          if (match) {
-            clearTimeout(id);
-            resolve({ url: match[1], proc });
-          }
-        }
-      }
-    });
-    proc.stderr?.on('data', (chunk: Buffer) => {
-      output += chunk.toString();
-    });
-    proc.on('exit', (code) => {
-      clearTimeout(id);
-      let msg = `OpenCode server exited with code ${code}`;
-      if (output.trim()) msg += `\nServer output: ${output}`;
-      reject(new Error(msg));
-    });
-    proc.on('error', (err) => {
-      clearTimeout(id);
-      reject(err);
-    });
-  });
-}
-
-function wrapPromptWithContext(text: string, systemInstructions?: string): string {
-  let out = text;
-  if (systemInstructions) {
-    out = `<system>\n${systemInstructions}\n</system>\n\n${out}`;
-  }
-  return out;
-}
-
-function buildOpenCodeConfig(options: ProviderOptions): Record<string, unknown> {
-  const provider = process.env.OPENCODE_PROVIDER || 'anthropic';
-  const model = process.env.OPENCODE_MODEL;
-  const smallModel = process.env.OPENCODE_SMALL_MODEL;
-  const proxyUrl = process.env.ANTHROPIC_BASE_URL;
-
-  const providerModelId = model ? model.replace(new RegExp(`^${provider}/`), '') : undefined;
-  const providerSmallModelId = smallModel ? smallModel.replace(new RegExp(`^${provider}/`), '') : undefined;
-  const modelsToRegister = [providerModelId, providerSmallModelId]
-    .filter(Boolean)
-    .filter((mid, i, a) => a.indexOf(mid as string) === i);
-
-  const providerOptions: Record<string, unknown> =
-    provider === 'anthropic'
-      ? {}
-      : {
-          [provider]: {
-            options: { apiKey: 'placeholder', baseURL: proxyUrl },
-            ...(modelsToRegister.length > 0
-              ? {
-                  models: Object.fromEntries(
-                    modelsToRegister.map((mid) => [mid, { id: mid, name: mid, tool_call: true }]),
-                  ),
-                }
-              : {}),
-          },
-        };
-
-  const mcp = mcpServersToOpenCodeConfig(options.mcpServers);
-
-  // Load shared base + per-group fragments + per-group memory through OpenCode's
-  // native instructions pipeline (session/instruction.ts). Absolute paths with
-  // globs are supported. Files are read raw — `@./...` includes are NOT expanded
-  // by OpenCode, so point at the concrete files, not at composed CLAUDE.md.
-  const instructions = [
-    '/app/CLAUDE.md',
-    '/workspace/agent/.claude-fragments/*.md',
-    '/workspace/agent/CLAUDE.local.md',
-  ];
-
-  return {
-    ...(model ? { model } : {}),
-    ...(smallModel ? { small_model: smallModel } : {}),
-    enabled_providers: [provider],
-    permission: 'allow',
-    autoupdate: false,
-    snapshot: false,
-    provider: providerOptions,
-    instructions,
-    mcp,
-  };
-}
-
-type SharedRuntime = {
-  proc: ChildProcess;
-  client: OpencodeClient;
-  stream: AsyncGenerator<{ type: string; properties: Record<string, unknown> }, void, void>;
-  streamRelease: () => void;
-};
-
-let sharedRuntime: SharedRuntime | null = null;
-let sharedConfigKey: string | null = null;
-let sharedInit: Promise<SharedRuntime> | null = null;
-
-function runtimeConfigKey(options: ProviderOptions): string {
-  return JSON.stringify({
-    mcp: mcpServersToOpenCodeConfig(options.mcpServers),
-    model: process.env.OPENCODE_MODEL,
-    small: process.env.OPENCODE_SMALL_MODEL,
-    op: process.env.OPENCODE_PROVIDER,
-  });
-}
-
-async function ensureSharedRuntime(options: ProviderOptions): Promise<SharedRuntime> {
-  const key = runtimeConfigKey(options);
-  if (sharedRuntime && sharedConfigKey === key) return sharedRuntime;
-
-  if (sharedInit) return sharedInit;
-
-  sharedInit = (async () => {
-    if (sharedRuntime) {
-      destroySharedRuntime();
-    }
-    const config = buildOpenCodeConfig(options);
-    const { url, proc } = await spawnOpencodeServer(config);
-    const client = createOpencodeClient({ baseUrl: url });
-    const sub = await client.event.subscribe();
-    const stream = sub.stream as AsyncGenerator<{ type: string; properties: Record<string, unknown> }, void, void>;
-    sharedRuntime = {
-      proc,
-      client,
-      stream,
-      streamRelease: () => {
-        void stream.return?.(undefined);
-      },
-    };
-    sharedConfigKey = key;
-    sharedInit = null;
-    return sharedRuntime;
-  })();
-
-  return sharedInit;
-}
-
-export function destroySharedRuntime(): void {
-  if (sharedRuntime) {
-    try {
-      sharedRuntime.streamRelease();
-    } catch {
-      /* ignore */
-    }
-    killProcessTree(sharedRuntime.proc);
-    sharedRuntime = null;
-    sharedConfigKey = null;
-  }
-  sharedInit = null;
-}
-
-function sessionErrorMessage(props: { error?: unknown }): string {
-  const err = props.error as { data?: { message?: string } } | undefined;
-  if (err && typeof err === 'object' && err.data && typeof err.data.message === 'string') {
-    return err.data.message;
-  }
-  return JSON.stringify(props.error) || 'OpenCode session error';
-}
-
-export class OpenCodeProvider implements AgentProvider {
-  readonly supportsNativeSlashCommands = false;
-
-  private readonly options: ProviderOptions;
-  private activeSessionId: string | undefined;
-
-  constructor(options: ProviderOptions = {}) {
-    this.options = options;
-  }
-
-  isSessionInvalid(err: unknown): boolean {
-    const msg = err instanceof Error ? err.message : String(err);
-    return STALE_SESSION_RE.test(msg);
-  }
-
-  query(input: QueryInput): AgentQuery {
-    if (input.continuation) {
-      this.activeSessionId = input.continuation;
-    } else {
-      this.activeSessionId = undefined;
-    }
-
-    const pending: string[] = [];
-    let waiting: (() => void) | null = null;
-    let ended = false;
-    let aborted = false;
-
-    const systemInstructions = input.systemContext?.instructions;
-    pending.push(wrapPromptWithContext(input.prompt, systemInstructions));
-
-    const kick = (): void => {
-      waiting?.();
-    };
-
-    const self = this;
-    const IDLE_TIMEOUT_MS = Number(process.env.OPENCODE_IDLE_TIMEOUT_MS) || 300_000;
-
-    async function* gen(): AsyncGenerator<ProviderEvent> {
-      let initYielded = false;
-      const rt = await ensureSharedRuntime(self.options);
-      const { client, stream } = rt;
-
-      while (!aborted) {
-        while (pending.length === 0 && !ended && !aborted) {
-          await new Promise<void>((resolve) => {
-            waiting = resolve;
-          });
-          waiting = null;
-        }
-
-        if (aborted) return;
-        if (pending.length === 0 && ended) return;
-
-        const text = pending.shift()!;
-        let sessionId = self.activeSessionId;
-
-        if (!sessionId) {
-          const created = await client.session.create();
-          if (created.error) {
-            throw new Error(`OpenCode: failed to create session: ${JSON.stringify(created.error)}`);
-          }
-          sessionId = created.data?.id;
-          if (!sessionId) throw new Error('OpenCode: failed to create session (no id)');
-          self.activeSessionId = sessionId;
-        }
-
-        if (!initYielded) {
-          yield { type: 'init', continuation: sessionId };
-          initYielded = true;
-        }
-
-        const promptRes = await client.session.promptAsync({
-          path: { id: sessionId },
-          body: { parts: [{ type: 'text', text }] },
-        });
-        if (promptRes.error) {
-          self.activeSessionId = undefined;
-          throw new Error(`OpenCode promptAsync: ${JSON.stringify(promptRes.error)}`);
-        }
-
-        const partTextByMessageId = new Map<string, string>();
-        const roleByMessageId = new Map<string, string>();
-        let lastEventAt = Date.now();
-        let eventTimedOut = false;
-        const timeoutCheck = setInterval(() => {
-          if (Date.now() - lastEventAt > IDLE_TIMEOUT_MS) {
-            log(`OpenCode event timeout (${IDLE_TIMEOUT_MS}ms) — clearing session ${sessionId}`);
-            eventTimedOut = true;
-            self.activeSessionId = undefined;
-            destroySharedRuntime();
-            kick();
-          }
-        }, 5000);
-
-        try {
-          turn: while (true) {
-            if (aborted) return;
-            if (eventTimedOut) {
-              throw new Error(`OpenCode event timeout (${IDLE_TIMEOUT_MS}ms)`);
-            }
-
-            const { value: ev, done } = await stream.next();
-            if (done) {
-              throw new Error('OpenCode SSE stream ended unexpectedly');
-            }
-
-            if (!ev?.type || ev.type === 'server.connected' || ev.type === 'server.heartbeat') continue;
-
-            lastEventAt = Date.now();
-            yield { type: 'activity' };
-
-            switch (ev.type) {
-              case 'message.updated': {
-                const info = ev.properties.info as { id?: string; role?: string } | undefined;
-                if (info?.id && info?.role) {
-                  roleByMessageId.set(info.id, info.role);
-                }
-                break;
-              }
-              case 'message.part.updated': {
-                const part = ev.properties.part as { type?: string; messageID?: string; text?: string } | undefined;
-                if (part?.type === 'text' && part.messageID && part.text) {
-                  partTextByMessageId.set(part.messageID, part.text);
-                }
-                break;
-              }
-              case 'permission.updated': {
-                const perm = ev.properties as { id?: string; sessionID?: string };
-                if (perm.sessionID === sessionId && perm.id) {
-                  try {
-                    await client.postSessionIdPermissionsPermissionId({
-                      path: { id: sessionId, permissionID: perm.id },
-                      body: { response: 'always' },
-                    });
-                  } catch (err) {
-                    log(`Failed to auto-reply permission: ${err instanceof Error ? err.message : String(err)}`);
-                  }
-                }
-                break;
-              }
-              case 'session.status': {
-                const props = ev.properties as {
-                  sessionID?: string;
-                  status?: { type?: string; attempt?: number; message?: string };
-                };
-                if (props.sessionID !== sessionId) break;
-                const st = props.status;
-                if (
-                  st?.type === 'retry' &&
-                  typeof st.attempt === 'number' &&
-                  st.attempt >= SESSION_STATUS_RETRY_ERROR_AFTER &&
-                  st.message
-                ) {
-                  self.activeSessionId = undefined;
-                  throw new Error(`OpenCode retry limit (${st.attempt}): ${st.message}`);
-                }
-                break;
-              }
-              case 'session.error': {
-                const props = ev.properties as { sessionID?: string; error?: unknown };
-                if (props.sessionID === sessionId || props.sessionID === undefined) {
-                  self.activeSessionId = undefined;
-                  throw new Error(sessionErrorMessage(props));
-                }
-                break;
-              }
-              case 'session.idle': {
-                const sid = (ev.properties as { sessionID?: string }).sessionID;
-                if (sid === sessionId) {
-                  break turn;
-                }
-                break;
-              }
-              default:
-                break;
-            }
-          }
-        } finally {
-          clearInterval(timeoutCheck);
-        }
-
-        let resultText = '';
-        for (const [msgId, role] of roleByMessageId) {
-          if (role === 'assistant') {
-            resultText = partTextByMessageId.get(msgId) ?? resultText;
-          }
-        }
-        yield { type: 'result', text: resultText || null };
-      }
-    }
-
-    return {
-      push: (message: string) => {
-        pending.push(wrapPromptWithContext(message, systemInstructions));
-        kick();
-      },
-      end: () => {
-        ended = true;
-        kick();
-      },
-      events: gen(),
-      abort: () => {
-        aborted = true;
-        this.activeSessionId = undefined;
-        kick();
-        destroySharedRuntime();
-      },
-    };
-  }
-}
-
-registerProvider('opencode', (opts) => new OpenCodeProvider(opts));

emacs/nanoclaw.el

@@ -0,0 +1,504 @@
+;;; nanoclaw.el --- Emacs interface for NanoClaw AI assistant -*- lexical-binding: t -*-
+
+;; Author: NanoClaw
+;; Version: 0.1.0
+;; Package-Requires: ((emacs "27.1"))
+;; Keywords: ai, assistant, chat
+;;
+;; Vanilla Emacs (init.el):
+;;   (load-file "~/src/nanoclaw/emacs/nanoclaw.el")
+;;   (global-set-key (kbd "C-c n c") #'nanoclaw-chat)
+;;   (global-set-key (kbd "C-c n o") #'nanoclaw-org-send)
+;;
+;; Spacemacs (~/.spacemacs, in dotspacemacs/user-config):
+;;   (load-file "~/src/nanoclaw/emacs/nanoclaw.el")
+;;   (spacemacs/set-leader-keys "aNc" #'nanoclaw-chat)
+;;   (spacemacs/set-leader-keys "aNo" #'nanoclaw-org-send)
+;;
+;; Doom Emacs (config.el):
+;;   (load (expand-file-name "~/src/nanoclaw/emacs/nanoclaw.el"))
+;;   (map! :leader
+;;         :prefix ("N" . "NanoClaw")
+;;         :desc "Chat buffer" "c" #'nanoclaw-chat
+;;         :desc "Send org"    "o" #'nanoclaw-org-send)
+;;   ;; Evil users: teach evil about the C-c C-c send binding
+;;   (after! evil
+;;     (evil-define-key '(normal insert) nanoclaw-chat-mode-map
+;;       (kbd "C-c C-c") #'nanoclaw-chat-send))
+
+;;; Code:
+
+(require 'cl-lib)
+(require 'url)
+(require 'json)
+(require 'org)
+
+;; ---------------------------------------------------------------------------
+;; Customization
+
+(defgroup nanoclaw nil
+  "NanoClaw AI assistant interface."
+  :group 'tools
+  :prefix "nanoclaw-")
+
+(defcustom nanoclaw-host "localhost"
+  "Hostname where NanoClaw is running."
+  :type 'string
+  :group 'nanoclaw)
+
+(defcustom nanoclaw-port 8766
+  "Port for the NanoClaw Emacs channel HTTP server."
+  :type 'integer
+  :group 'nanoclaw)
+
+(defcustom nanoclaw-auth-token nil
+  "Bearer token for NanoClaw authentication (matches EMACS_AUTH_TOKEN in .env).
+Leave nil if EMACS_AUTH_TOKEN is not set."
+  :type '(choice (const nil) string)
+  :group 'nanoclaw)
+
+(defcustom nanoclaw-poll-interval 1.5
+  "Seconds between response polls when waiting for a reply."
+  :type 'number
+  :group 'nanoclaw)
+
+(defcustom nanoclaw-agent-name "Andy"
+  "Display name for the NanoClaw agent (matches ASSISTANT_NAME in .env)."
+  :type 'string
+  :group 'nanoclaw)
+
+(defcustom nanoclaw-convert-to-org t
+  "When non-nil, convert agent responses to org-mode format.
+Uses pandoc when available; falls back to regex substitutions."
+  :type 'boolean
+  :group 'nanoclaw)
+
+(defcustom nanoclaw-timestamp-format "%H:%M"
+  "Format string for timestamps shown next to agent replies in the chat buffer.
+Passed to `format-time-string'.  Set to nil to suppress timestamps."
+  :type '(choice (const nil) string)
+  :group 'nanoclaw)
+
+;; ---------------------------------------------------------------------------
+;; Formatting helpers
+
+(defun nanoclaw--to-org (text)
+  "Convert TEXT (markdown or plain) to org-mode markup.
+Tries pandoc -f gfm -t org when available; falls back to regex."
+  (if (not nanoclaw-convert-to-org)
+      text
+    (if (executable-find "pandoc")
+        (with-temp-buffer
+          (insert text)
+          (let* ((coding-system-for-read 'utf-8)
+                 (coding-system-for-write 'utf-8)
+                 (exit (call-process-region
+                        (point-min) (point-max)
+                        "pandoc" t t nil "-f" "gfm" "-t" "org" "--wrap=none")))
+            (if (zerop exit)
+                (string-trim (buffer-string))
+              text)))
+      (nanoclaw--md-to-org-regex text))))
+
+;; NOTE: This function expects standard markdown as input (e.g. **bold**, *italic*).
+;; Agents responding on this channel must output markdown, not org-mode syntax.
+;; If the agent outputs org-mode directly, markers like *bold* will be incorrectly
+;; re-converted to /bold/ by the italic rule.
+(defun nanoclaw--md-to-org-regex (text)
+  "Lightweight markdown → org conversion using regexp substitutions."
+  (let ((s text))
+    ;; Fenced code blocks  ```lang\n…\n```  →  #+begin_src lang\n…\n#+end_src
+    ;; (must run before inline-code to avoid mangling backticks)
+    (setq s (replace-regexp-in-string
+             "```\\([a-zA-Z0-9_-]*\\)\n\\(\\(?:.\\|\n\\)*?\\)```"
+             (lambda (m)
+               (let ((lang (match-string 1 m))
+                     (body (match-string 2 m)))
+                 (concat "#+begin_src " (if (string-empty-p lang) "text" lang)
+                         "\n" body "#+end_src")))
+             s t))
+    ;; Bold **text** → *text*, italic *text* → /text/
+    ;; Two-pass to prevent the italic regex from re-matching the bold result:
+    ;; 1. Mark bold spans with a placeholder (control char \x01)
+    (setq s (replace-regexp-in-string "\\*\\*\\(.+?\\)\\*\\*" "\x01\\1\x01" s))
+    ;; 2. Convert remaining single-star spans to italic
+    (setq s (replace-regexp-in-string "\\*\\(.+?\\)\\*" "/\\1/" s))
+    ;; 3. Resolve bold placeholders to org bold markers
+    (setq s (replace-regexp-in-string "\x01\\(.+?\\)\x01" "*\\1*" s))
+    ;; Strikethrough  ~~text~~ → +text+
+    (setq s (replace-regexp-in-string "~~\\(.+?\\)~~" "+\\1+" s))
+    ;; Underline  __text__ → _text_
+    (setq s (replace-regexp-in-string "__\\(.+?\\)__" "_\\1_" s))
+    ;; Inline code  `code` → ~code~
+    (setq s (replace-regexp-in-string "`\\([^`]+\\)`" "~\\1~" s))
+    ;; ATX headings  ## …  →  ** …
+    (setq s (replace-regexp-in-string
+             "^\\(#+\\) "
+             (lambda (m) (concat (make-string (length (match-string 1 m)) ?*) " "))
+             s))
+    ;; Links  [text](url) → [[url][text]]
+    (setq s (replace-regexp-in-string
+             "\\[\\([^]]+\\)\\](\\([^)]+\\))" "[[\\2][\\1]]" s))
+    s))
+
+(defun nanoclaw--format-timestamp ()
+  "Return a formatted timestamp string, or nil if disabled."
+  (when nanoclaw-timestamp-format
+    (format-time-string nanoclaw-timestamp-format)))
+
+;; ---------------------------------------------------------------------------
+;; Internal state
+
+(defvar nanoclaw--poll-timer nil
+  "Timer used to poll for responses in the chat buffer.")
+
+(defvar nanoclaw--last-timestamp 0
+  "Epoch ms of the most recently received message.")
+
+(defvar nanoclaw--pending nil
+  "Non-nil while waiting for a response.")
+
+(defvar-local nanoclaw--thinking-dot-count 0
+  "Dot cycle counter for the animated thinking indicator.")
+
+(defvar-local nanoclaw--input-beg nil
+  "Marker for the start of the current user input area.")
+
+;; ---------------------------------------------------------------------------
+;; HTTP helpers
+
+(defun nanoclaw--url (path)
+  "Return the full URL for PATH on the NanoClaw server."
+  (format "http://%s:%d%s" nanoclaw-host nanoclaw-port path))
+
+(defun nanoclaw--headers ()
+  "Return alist of HTTP headers for NanoClaw requests."
+  (let ((hdrs '(("Content-Type" . "application/json"))))
+    (when nanoclaw-auth-token
+      (push (cons "Authorization" (concat "Bearer " nanoclaw-auth-token)) hdrs))
+    hdrs))
+
+(defun nanoclaw--post (text callback)
+  "POST TEXT to NanoClaw and call CALLBACK with the response alist."
+  (let* ((url-request-method "POST")
+         (url-request-extra-headers (nanoclaw--headers))
+         (url-request-data (encode-coding-string
+                            (json-encode `((text . ,text)))
+                            'utf-8)))
+    (url-retrieve
+     (nanoclaw--url "/api/message")
+     (lambda (status)
+       (if (plist-get status :error)
+           (message "NanoClaw: POST error %s" (plist-get status :error))
+         (goto-char (point-min))
+         (re-search-forward "\n\n" nil t)
+         (let ((data (ignore-errors (json-read))))
+           (funcall callback data))))
+     nil t t)))
+
+(defun nanoclaw--poll (since callback)
+  "GET messages newer than SINCE (epoch ms) and call CALLBACK with the list."
+  (let* ((url-request-method "GET")
+         (url-request-extra-headers (nanoclaw--headers)))
+    (url-retrieve
+     (nanoclaw--url (format "/api/messages?since=%d" since))
+     (lambda (status)
+       (unless (plist-get status :error)
+         (goto-char (point-min))
+         (re-search-forward "\n\n" nil t)
+         (let* ((raw  (buffer-substring-no-properties (point) (point-max)))
+                (body (decode-coding-string raw 'utf-8))
+                (data (ignore-errors (json-read-from-string body)))
+                (msgs (cdr (assq 'messages data))))
+           (when msgs (funcall callback (append msgs nil))))))
+     nil t t)))
+
+;; ---------------------------------------------------------------------------
+;; Chat buffer
+
+(defvar nanoclaw-chat-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "RET")      #'newline)
+    (define-key map (kbd "<return>") #'newline)
+    (define-key map (kbd "C-c C-c") #'nanoclaw-chat-send)
+    map)
+  "Keymap for `nanoclaw-chat-mode'.")
+
+(define-derived-mode nanoclaw-chat-mode org-mode "NanoClaw"
+  "Major mode for the NanoClaw chat buffer.
+Derives from org-mode so that org markup (headings, bold, code blocks,
+etc.) is fontified automatically.  RET and <return> insert plain newlines
+for multi-line input; send with C-c C-c."
+  (setq-local word-wrap t)
+  (visual-line-mode 1)
+  ;; Disable org features that conflict with a linear chat buffer
+  (setq-local org-return-follows-link nil)
+  (setq-local org-cycle-emulate-tab nil)
+  ;; Ensure send binding beats org-mode's C-c C-c via the buffer-local map
+  (local-set-key (kbd "C-c C-c") #'nanoclaw-chat-send))
+
+(defun nanoclaw--advance-input-beg ()
+  "Move `nanoclaw--input-beg' to point-max in the chat buffer."
+  (with-current-buffer (nanoclaw--chat-buffer)
+    (when nanoclaw--input-beg (set-marker nanoclaw--input-beg nil))
+    (setq nanoclaw--input-beg (copy-marker (point-max)))))
+
+(defun nanoclaw--chat-buffer ()
+  "Return the NanoClaw chat buffer, creating it if necessary."
+  (or (get-buffer "*NanoClaw*")
+      (with-current-buffer (get-buffer-create "*NanoClaw*")
+        (nanoclaw-chat-mode)
+        (set-buffer-file-coding-system 'utf-8)
+        (add-hook 'kill-buffer-hook #'nanoclaw--stop-poll nil t)
+        (nanoclaw--insert-header)
+        (setq nanoclaw--input-beg (copy-marker (point-max)))
+        (current-buffer))))
+
+(defun nanoclaw--insert-header ()
+  "Insert the welcome header into the chat buffer."
+  (let ((inhibit-read-only t))
+    (insert (propertize
+             (format "── NanoClaw (%s) ──────────────────────────────\n\n"
+                     nanoclaw-agent-name)
+             'face 'font-lock-comment-face))))
+
+(defun nanoclaw--chat-insert (speaker text)
+  "Append SPEAKER: TEXT to the chat buffer."
+  (with-current-buffer (nanoclaw--chat-buffer)
+    (let* ((inhibit-read-only t)
+           (is-agent (not (string= speaker "You")))
+           (display-text (if is-agent (nanoclaw--to-org text) text))
+           (ts (nanoclaw--format-timestamp))
+           (label (if ts (format "%s [%s]" speaker ts) speaker))
+           (face  (if is-agent 'font-lock-string-face 'font-lock-keyword-face)))
+      (goto-char (point-max))
+      (insert (propertize (concat label ": ") 'face face))
+      (insert display-text "\n\n")
+      (goto-char (point-max))
+      (when is-agent
+        (nanoclaw--advance-input-beg)))))
+
+;;;###autoload
+(defun nanoclaw-chat ()
+  "Open the NanoClaw chat buffer."
+  (interactive)
+  (pop-to-buffer (nanoclaw--chat-buffer))
+  (goto-char (point-max)))
+
+(defun nanoclaw-chat-send ()
+  "Send the accumulated input area as a message to NanoClaw.
+Use C-c C-c to send; RET inserts a plain newline for multi-line messages."
+  (interactive)
+  (when nanoclaw--pending
+    (message "NanoClaw: waiting for previous response...")
+    (cl-return-from nanoclaw-chat-send))
+  (let* ((beg (if (and nanoclaw--input-beg (marker-buffer nanoclaw--input-beg))
+                  (marker-position nanoclaw--input-beg)
+                (line-beginning-position)))
+         (text (string-trim (buffer-substring-no-properties beg (point-max)))))
+    (when (string-empty-p text)
+      (user-error "Nothing to send"))
+    (let ((inhibit-read-only t))
+      (delete-region beg (point-max)))
+    (nanoclaw--chat-insert "You" text)
+    (nanoclaw--advance-input-beg)
+    (setq nanoclaw--pending t)
+    (nanoclaw--post text
+                    (lambda (data)
+                      (when data
+                        (setq nanoclaw--last-timestamp
+                              (or (cdr (assq 'timestamp data))
+                                  nanoclaw--last-timestamp))
+                        (nanoclaw--start-thinking)
+                        (nanoclaw--start-poll))))))
+
+(defun nanoclaw--start-poll ()
+  "Start polling for new messages."
+  (nanoclaw--stop-poll)
+  (setq nanoclaw--poll-timer
+        (run-with-timer nanoclaw-poll-interval nanoclaw-poll-interval
+                        #'nanoclaw--poll-tick)))
+
+(defun nanoclaw--stop-poll ()
+  "Stop the polling timer."
+  (when nanoclaw--poll-timer
+    (cancel-timer nanoclaw--poll-timer)
+    (setq nanoclaw--poll-timer nil)))
+
+(defun nanoclaw--start-thinking ()
+  "Insert an animated thinking indicator at the end of the chat buffer."
+  (with-current-buffer (nanoclaw--chat-buffer)
+    (let ((inhibit-read-only t))
+      (goto-char (point-max))
+      (setq nanoclaw--thinking-dot-count 1)
+      (insert (propertize (format "%s: .\n\n" nanoclaw-agent-name)
+                          'nanoclaw-thinking t
+                          'face 'font-lock-string-face)))))
+
+(defun nanoclaw--tick-thinking ()
+  "Advance the dot animation in the thinking indicator."
+  (let ((buf (get-buffer "*NanoClaw*")))
+    (when buf
+      (with-current-buffer buf
+        (when nanoclaw--pending
+          (let* ((inhibit-read-only t)
+                 (pos (text-property-any (point-min) (point-max)
+                                         'nanoclaw-thinking t)))
+            (when pos
+              (let* ((end (or (next-single-property-change
+                               pos 'nanoclaw-thinking) (point-max)))
+                     (n (1+ (mod nanoclaw--thinking-dot-count 3))))
+                (setq nanoclaw--thinking-dot-count n)
+                (delete-region pos end)
+                (save-excursion
+                  (goto-char pos)
+                  (insert (propertize
+                           (format "%s: %s\n\n" nanoclaw-agent-name
+                                   (make-string n ?.))
+                           'nanoclaw-thinking t
+                           'face 'font-lock-string-face)))))))))))
+
+(defun nanoclaw--clear-thinking ()
+  "Remove the thinking indicator from the chat buffer."
+  (let ((buf (get-buffer "*NanoClaw*")))
+    (when buf
+      (with-current-buffer buf
+        (let* ((inhibit-read-only t)
+               (pos (text-property-any (point-min) (point-max)
+                                       'nanoclaw-thinking t)))
+          (when pos
+            (delete-region pos (or (next-single-property-change
+                                    pos 'nanoclaw-thinking) (point-max)))))))))
+
+(defun nanoclaw--poll-tick ()
+  "Poll for new messages and insert them into the chat buffer."
+  (nanoclaw--tick-thinking)
+  (nanoclaw--poll
+   nanoclaw--last-timestamp
+   (lambda (msgs)
+     (dolist (msg msgs)
+       (let ((text (cdr (assq 'text msg)))
+             (ts   (cdr (assq 'timestamp msg))))
+         (when (and text (> ts nanoclaw--last-timestamp))
+           (setq nanoclaw--last-timestamp ts)
+           (nanoclaw--clear-thinking)
+           (nanoclaw--chat-insert nanoclaw-agent-name text))))
+     (when msgs
+       (setq nanoclaw--pending nil)
+       (nanoclaw--stop-poll)))))
+
+;; ---------------------------------------------------------------------------
+;; Org integration
+
+;;;###autoload
+(defun nanoclaw-org-send ()
+  "Send the current org subtree to NanoClaw and insert the response as a child.
+
+If a region is active, send the region text instead."
+  (interactive)
+  (unless (derived-mode-p 'org-mode)
+    (user-error "Not in an org-mode buffer"))
+  (let ((text (if (use-region-p)
+                  (buffer-substring-no-properties (region-beginning) (region-end))
+                (nanoclaw--org-subtree-text))))
+    (when (string-empty-p (string-trim text))
+      (user-error "Nothing to send"))
+    (message "NanoClaw: sending to %s..." nanoclaw-agent-name)
+    (let ((marker (point-marker))
+          (buf    (current-buffer)))
+      (nanoclaw--post
+       text
+       (lambda (data)
+         (let* ((ts (or (cdr (assq 'timestamp data)) (nanoclaw--now-ms)))
+                (level (with-current-buffer buf
+                         (save-excursion (goto-char marker) (org-outline-level))))
+                (ph (with-current-buffer buf
+                      (save-excursion
+                        (goto-char marker)
+                        (nanoclaw--org-insert-placeholder level)))))
+           (nanoclaw--poll-until-response
+            ts
+            (lambda (response)
+              (with-current-buffer buf
+                (save-excursion
+                  (when (marker-buffer ph)
+                    (let* ((inhibit-read-only t)
+                           (beg (marker-position ph))
+                           (end (save-excursion
+                                  (goto-char (1+ beg))
+                                  (org-next-visible-heading 1)
+                                  (point))))
+                      (delete-region beg end))
+                    (set-marker ph nil))
+                  (goto-char marker)
+                  (nanoclaw--org-insert-response response))))
+            (lambda ()
+              (message "NanoClaw: timed out waiting for response")
+              (when (marker-buffer ph)
+                (with-current-buffer (marker-buffer ph)
+                  (let* ((inhibit-read-only t)
+                         (beg (marker-position ph))
+                         (end (save-excursion
+                                (goto-char (1+ beg))
+                                (org-next-visible-heading 1)
+                                (point))))
+                    (delete-region beg end))
+                  (set-marker ph nil)))))))))))
+
+(defun nanoclaw--org-insert-placeholder (level)
+  "Insert a processing child heading at LEVEL+1 and return a marker at its start."
+  (org-back-to-heading t)
+  (org-end-of-subtree t t)
+  (let ((beg (point)))
+    (insert "\n" (make-string (1+ level) ?*) " "
+            nanoclaw-agent-name " [processing...]\n\n")
+    (copy-marker beg)))
+
+(defun nanoclaw--org-subtree-text ()
+  "Return the text of the org subtree at point (heading + body)."
+  (org-with-wide-buffer
+   (org-back-to-heading t)
+   (let ((start (point))
+         (end   (progn (org-end-of-subtree t t) (point))))
+     (buffer-substring-no-properties start end))))
+
+(defun nanoclaw--org-insert-response (text)
+  "Insert TEXT as a child org heading under the current subtree."
+  (org-back-to-heading t)
+  (let* ((level (org-outline-level))
+         (child-stars (make-string (1+ level) ?*))
+         (timestamp (format-time-string "[%Y-%m-%d %a %H:%M]"))
+         (body (nanoclaw--to-org text)))
+    (org-end-of-subtree t t)
+    (insert "\n" child-stars " " nanoclaw-agent-name " " timestamp "\n"
+            body "\n")))
+
+(defun nanoclaw--now-ms ()
+  "Return current time as milliseconds since epoch."
+  (let ((time (current-time)))
+    (+ (* (+ (* (car time) 65536) (cadr time)) 1000)
+       (/ (caddr time) 1000))))
+
+(defun nanoclaw--poll-until-response (since callback timeout-fn &optional attempts)
+  "Poll until a message newer than SINCE arrives, then call CALLBACK.
+Calls TIMEOUT-FN after 60 attempts (~90s)."
+  (let ((n (or attempts 0)))
+    (if (>= n 60)
+        (funcall timeout-fn)
+      (nanoclaw--poll
+       since
+       (lambda (msgs)
+         (let ((fresh (seq-filter (lambda (m) (> (cdr (assq 'timestamp m)) since))
+                                  msgs)))
+           (if fresh
+               (let ((text (mapconcat (lambda (m) (cdr (assq 'text m)))
+                                      fresh "\n")))
+                 (funcall callback text))
+             (run-with-timer nanoclaw-poll-interval nil
+                             #'nanoclaw--poll-until-response
+                             since callback timeout-fn (1+ n)))))))))
+
+;; ---------------------------------------------------------------------------
+
+(provide 'nanoclaw)
+;;; nanoclaw.el ends here

package.json

@@ -24,13 +24,31 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@beeper/chat-adapter-matrix": "^0.2.0",
+    "@bitbasti/chat-adapter-webex": "^0.1.0",
+    "@chat-adapter/discord": "^4.24.0",
+    "@chat-adapter/gchat": "^4.24.0",
+    "@chat-adapter/github": "^4.24.0",
+    "@chat-adapter/linear": "^4.26.0",
+    "@chat-adapter/slack": "^4.24.0",
+    "@chat-adapter/state-memory": "^4.24.0",
+    "@chat-adapter/teams": "^4.24.0",
+    "@chat-adapter/telegram": "4.26.0",
+    "@chat-adapter/whatsapp": "^4.24.0",
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
     "@onecli-sh/sdk": "^0.3.1",
+    "@resend/chat-sdk-adapter": "^0.1.1",
+    "@types/qrcode": "^1.5.6",
+    "@whiskeysockets/baileys": "7.0.0-rc.9",
     "better-sqlite3": "11.10.0",
     "chat": "^4.24.0",
+    "chat-adapter-imessage": "^0.1.1",
     "cron-parser": "5.5.0",
-    "kleur": "^4.1.5"
+    "kleur": "^4.1.5",
+    "pino": "^9.6.0",
+    "qrcode": "^1.5.4",
+    "wechat-ilink-client": "^0.1.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",

scripts/init-cli-agent.ts

@@ -1,5 +1,5 @@
 /**
- * Initialize the scratch CLI agent used during `/new-setup`.
+ * Initialize the scratch CLI agent used during `/setup`.
  *
  * Creates the synthetic `cli:local` user, grants owner role if no owner
  * exists yet, builds an agent group with a minimal CLAUDE.md, and wires it

setup/add-whatsapp.sh

@@ -16,7 +16,7 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$PROJECT_ROOT"
 
 # Keep in sync with .claude/skills/add-whatsapp/SKILL.md.
-BAILEYS_VERSION="@whiskeysockets/baileys@6.17.16"
+BAILEYS_VERSION="@whiskeysockets/baileys@7.0.0-rc.9"
 QRCODE_VERSION="qrcode@1.5.4"
 QRCODE_TYPES_VERSION="@types/qrcode@1.5.6"
 PINO_VERSION="pino@9.6.0"

setup/auth.ts

@@ -7,7 +7,7 @@
  *                             already exists unless --force is passed.
  *
  * The actual user-facing prompt (subscription vs API key, paste the token)
- * stays in the /new-setup SKILL.md. This step is just the machine side:
+ * stays in the /setup SKILL.md. This step is just the machine side:
  * it calls `onecli secrets list` / `onecli secrets create` and emits a
  * structured status block. The token value is never logged.
  */
@@ -124,7 +124,7 @@ export async function run(args: string[]): Promise<void> {
     emitStatus('AUTH', {
       STATUS: 'failed',
       ERROR: 'onecli_list_failed',
-      HINT: 'Is OneCLI running? Run `/new-setup` from the onecli step.',
+      HINT: 'Is OneCLI running? Run `/setup` from the onecli step.',
       LOG: 'logs/setup.log',
     });
     process.exit(1);

setup/cli-agent.ts

@@ -1,8 +1,8 @@
 /**
- * Step: cli-agent — Create the scratch CLI agent for `/new-setup`.
+ * Step: cli-agent — Create the scratch CLI agent for `/setup`.
  *
  * Thin wrapper around `scripts/init-cli-agent.ts`. Emits a status block so
- * /new-setup SKILL.md can parse the result without having to read the
+ * /setup SKILL.md can parse the result without having to read the
  * script's plain stdout.
  *
  * Args:

setup/groups.ts

@@ -0,0 +1,229 @@
+/**
+ * Step: groups — Fetch group metadata from messaging platforms, write to DB.
+ * WhatsApp requires an upfront sync (Baileys groupFetchAllParticipating).
+ * Other channels discover group names at runtime — this step auto-skips for them.
+ * Replaces 05-sync-groups.sh + 05b-list-groups.sh
+ */
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+import Database from 'better-sqlite3';
+
+import { STORE_DIR } from '../src/config.js';
+import { log } from '../src/log.js';
+import { emitStatus } from './status.js';
+
+function parseArgs(args: string[]): { list: boolean; limit: number } {
+  let list = false;
+  let limit = 30;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--list') list = true;
+    if (args[i] === '--limit' && args[i + 1]) {
+      limit = parseInt(args[i + 1], 10);
+      i++;
+    }
+  }
+  return { list, limit };
+}
+
+export async function run(args: string[]): Promise<void> {
+  const projectRoot = process.cwd();
+  const { list, limit } = parseArgs(args);
+
+  if (list) {
+    await listGroups(limit);
+    return;
+  }
+
+  await syncGroups(projectRoot);
+}
+
+async function listGroups(limit: number): Promise<void> {
+  const dbPath = path.join(STORE_DIR, 'messages.db');
+
+  if (!fs.existsSync(dbPath)) {
+    console.error('ERROR: database not found');
+    process.exit(1);
+  }
+
+  const db = new Database(dbPath, { readonly: true });
+  const rows = db
+    .prepare(
+      `SELECT jid, name FROM chats
+     WHERE jid LIKE '%@g.us' AND jid <> '__group_sync__' AND name <> jid
+     ORDER BY last_message_time DESC
+     LIMIT ?`,
+    )
+    .all(limit) as Array<{ jid: string; name: string }>;
+  db.close();
+
+  for (const row of rows) {
+    console.log(`${row.jid}|${row.name}`);
+  }
+}
+
+async function syncGroups(projectRoot: string): Promise<void> {
+  // Only WhatsApp needs an upfront group sync; other channels resolve names at runtime.
+  // Detect WhatsApp by checking for auth credentials on disk.
+  const authDir = path.join(projectRoot, 'store', 'auth');
+  const hasWhatsAppAuth =
+    fs.existsSync(authDir) && fs.readdirSync(authDir).length > 0;
+
+  if (!hasWhatsAppAuth) {
+    log.info('WhatsApp auth not found — skipping group sync');
+    emitStatus('SYNC_GROUPS', {
+      BUILD: 'skipped',
+      SYNC: 'skipped',
+      GROUPS_IN_DB: 0,
+      REASON: 'whatsapp_not_configured',
+      STATUS: 'success',
+      LOG: 'logs/setup.log',
+    });
+    return;
+  }
+
+  // Build TypeScript first
+  log.info('Building TypeScript');
+  let buildOk = false;
+  try {
+    execSync('pnpm run build', {
+      cwd: projectRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    buildOk = true;
+    log.info('Build succeeded');
+  } catch {
+    log.error('Build failed');
+    emitStatus('SYNC_GROUPS', {
+      BUILD: 'failed',
+      SYNC: 'skipped',
+      GROUPS_IN_DB: 0,
+      STATUS: 'failed',
+      ERROR: 'build_failed',
+      LOG: 'logs/setup.log',
+    });
+    process.exit(1);
+  }
+
+  // Run sync script via a temp file to avoid shell escaping issues with node -e
+  log.info('Fetching group metadata');
+  let syncOk = false;
+  try {
+    const syncScript = `
+import makeWASocket, { useMultiFileAuthState, makeCacheableSignalKeyStore, Browsers } from '@whiskeysockets/baileys';
+import pino from 'pino';
+import path from 'path';
+import fs from 'fs';
+import Database from 'better-sqlite3';
+
+const logger = pino({ level: 'silent' });
+const authDir = path.join('store', 'auth');
+const dbPath = path.join('store', 'messages.db');
+
+if (!fs.existsSync(authDir)) {
+  console.error('NO_AUTH');
+  process.exit(1);
+}
+
+const db = new Database(dbPath);
+db.pragma('journal_mode = WAL');
+db.exec('CREATE TABLE IF NOT EXISTS chats (jid TEXT PRIMARY KEY, name TEXT, last_message_time TEXT)');
+
+const upsert = db.prepare(
+  'INSERT INTO chats (jid, name, last_message_time) VALUES (?, ?, ?) ON CONFLICT(jid) DO UPDATE SET name = excluded.name'
+);
+
+const { state, saveCreds } = await useMultiFileAuthState(authDir);
+
+const sock = makeWASocket({
+  auth: { creds: state.creds, keys: makeCacheableSignalKeyStore(state.keys, logger) },
+  printQRInTerminal: false,
+  logger,
+  browser: Browsers.macOS('Chrome'),
+});
+
+const timeout = setTimeout(() => {
+  console.error('TIMEOUT');
+  process.exit(1);
+}, 30000);
+
+sock.ev.on('creds.update', saveCreds);
+
+sock.ev.on('connection.update', async (update) => {
+  if (update.connection === 'open') {
+    try {
+      const groups = await sock.groupFetchAllParticipating();
+      const now = new Date().toISOString();
+      let count = 0;
+      for (const [jid, metadata] of Object.entries(groups)) {
+        if (metadata.subject) {
+          upsert.run(jid, metadata.subject, now);
+          count++;
+        }
+      }
+      console.log('SYNCED:' + count);
+    } catch (err) {
+      console.error('FETCH_ERROR:' + err.message);
+    } finally {
+      clearTimeout(timeout);
+      sock.end(undefined);
+      db.close();
+      process.exit(0);
+    }
+  } else if (update.connection === 'close') {
+    clearTimeout(timeout);
+    console.error('CONNECTION_CLOSED');
+    process.exit(1);
+  }
+});
+`;
+
+    const tmpScript = path.join(projectRoot, '.tmp-group-sync.mjs');
+    fs.writeFileSync(tmpScript, syncScript, 'utf-8');
+    try {
+      const output = execSync(`node ${tmpScript}`, {
+        cwd: projectRoot,
+        encoding: 'utf-8',
+        timeout: 45000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      syncOk = output.includes('SYNCED:');
+      log.info('Sync output', { output: output.trim() });
+    } finally {
+      try { fs.unlinkSync(tmpScript); } catch { /* ignore cleanup errors */ }
+    }
+  } catch (err) {
+    log.error('Sync failed', { err });
+  }
+
+  // Count groups in DB using better-sqlite3 (no sqlite3 CLI)
+  let groupsInDb = 0;
+  const dbPath = path.join(STORE_DIR, 'messages.db');
+  if (fs.existsSync(dbPath)) {
+    try {
+      const db = new Database(dbPath, { readonly: true });
+      const row = db
+        .prepare(
+          "SELECT COUNT(*) as count FROM chats WHERE jid LIKE '%@g.us' AND jid <> '__group_sync__'",
+        )
+        .get() as { count: number };
+      groupsInDb = row.count;
+      db.close();
+    } catch {
+      // DB may not exist yet
+    }
+  }
+
+  const status = syncOk ? 'success' : 'failed';
+
+  emitStatus('SYNC_GROUPS', {
+    BUILD: buildOk ? 'success' : 'failed',
+    SYNC: syncOk ? 'success' : 'failed',
+    GROUPS_IN_DB: groupsInDb,
+    STATUS: status,
+    LOG: 'logs/setup.log',
+  });
+
+  if (status === 'failed') process.exit(1);
+}

setup/index.ts

@@ -13,8 +13,9 @@ const STEPS: Record<
   'set-env': () => import('./set-env.js'),
   environment: () => import('./environment.js'),
   container: () => import('./container.js'),
-  register: () => import('./register.js'),
   groups: () => import('./groups.js'),
+  register: () => import('./register.js'),
+  'pair-telegram': () => import('./pair-telegram.js'),
   'whatsapp-auth': () => import('./whatsapp-auth.js'),
   'signal-auth': () => import('./signal-auth.js'),
   mounts: () => import('./mounts.js'),

setup/install-discord.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-discord — bundles the preflight + install commands
-# from the /add-discord skill into one idempotent script so /new-setup can
+# from the /add-discord skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Discord adapter in from the `channels` branch; appends the

setup/install-docker.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-docker — bundles Docker install into one idempotent
-# script so /new-setup can run it without needing `curl | sh` in the allowlist
+# script so /setup can run it without needing `curl | sh` in the allowlist
 # (pipelines split at matching time, and `sh` receiving stdin can't be
 # pre-approved safely).
 #

setup/install-gchat.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-gchat — bundles the preflight + install commands
-# from the /add-gchat skill into one idempotent script so /new-setup can
+# from the /add-gchat skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Google Chat adapter in from the `channels` branch; appends the

setup/install-github.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-github — bundles the preflight + install commands
-# from the /add-github skill into one idempotent script so /new-setup can
+# from the /add-github skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the GitHub adapter in from the `channels` branch; appends the

setup/install-imessage.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-imessage — bundles the preflight + install commands
-# from the /add-imessage skill into one idempotent script so /new-setup can
+# from the /add-imessage skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the iMessage adapter in from the `channels` branch; appends the

setup/install-linear.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-linear — bundles the preflight + install commands
-# from the /add-linear skill into one idempotent script so /new-setup can
+# from the /add-linear skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Linear adapter in from the `channels` branch; appends the

setup/install-matrix.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-matrix — bundles the preflight + install commands
-# from the /add-matrix skill into one idempotent script so /new-setup can
+# from the /add-matrix skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Matrix adapter in from the `channels` branch; appends the

setup/install-node.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-node — bundles Node 22 install into one idempotent
-# script so /new-setup can run it without needing `curl | sudo -E bash -` in
+# script so /setup can run it without needing `curl | sudo -E bash -` in
 # the allowlist (that pattern is inherently unmatchable — bash reads from
 # stdin, so pre-approval can't inspect what's being executed).
 #

setup/install-resend.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-resend — bundles the preflight + install commands
-# from the /add-resend skill into one idempotent script so /new-setup can
+# from the /add-resend skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Resend adapter in from the `channels` branch; appends the

setup/install-slack.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-slack — bundles the preflight + install commands
-# from the /add-slack skill into one idempotent script so /new-setup can
+# from the /add-slack skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Slack adapter in from the `channels` branch; appends the

setup/install-teams.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-teams — bundles the preflight + install commands
-# from the /add-teams skill into one idempotent script so /new-setup can
+# from the /add-teams skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Teams adapter in from the `channels` branch; appends the

setup/install-telegram.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-telegram — bundles the preflight + install commands
-# from the /add-telegram skill into one idempotent script so /new-setup can
+# from the /add-telegram skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials and pairing.
 #
 # Copies the Telegram adapter, helpers, tests, and the pair-telegram setup

setup/install-webex.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-webex — bundles the preflight + install commands
-# from the /add-webex skill into one idempotent script so /new-setup can
+# from the /add-webex skill into one idempotent script so /setup can
 # run them programmatically before continuing to credentials.
 #
 # Copies the Webex adapter in from the `channels` branch; appends the

setup/install-whatsapp-cloud.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Setup helper: install-whatsapp-cloud — bundles the preflight + install
 # commands from the /add-whatsapp-cloud skill into one idempotent script so
-# /new-setup can run them programmatically before continuing to credentials.
+# /setup can run them programmatically before continuing to credentials.
 #
 # Copies the WhatsApp Cloud adapter in from the `channels` branch; appends the
 # self-registration import; installs the pinned @chat-adapter/whatsapp package;

setup/install-whatsapp.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Setup helper: install-whatsapp — bundles the preflight + install commands
-# from the /add-whatsapp skill into one idempotent script so /new-setup can
+# from the /add-whatsapp skill into one idempotent script so /setup can
 # run them programmatically before continuing to QR/pairing-code auth.
 #
 # Copies the native Baileys WhatsApp adapter, its whatsapp-auth and groups
@@ -66,7 +66,7 @@ if ! grep -q "'whatsapp-auth':" setup/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @whiskeysockets/baileys@6.17.16 qrcode@1.5.4 @types/qrcode@1.5.6 pino@9.6.0
+pnpm install @whiskeysockets/baileys@7.0.0-rc.9 qrcode@1.5.4 @types/qrcode@1.5.6 pino@9.6.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/probe.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Setup step: probe — single upfront parallel-ish scan that snapshots every
-# prerequisite and dependency for /new-setup's dynamic context injection.
+# prerequisite and dependency for /setup's dynamic context injection.
 # Rendered into the SKILL.md prompt via `!bash setup/probe.sh` so Claude sees
 # the current system state before generating its first response.
 #

setup/providers/codex-registration.test.ts

@@ -1,22 +0,0 @@
-/**
- * Setup-side registration guard for the codex provider (the third barrel of
- * the multi-point archetype): imports the REAL setup/providers barrel and
- * asserts the registry carries codex with its auth + install check. Red if
- * the barrel line is deleted, the barrel fails to evaluate, or the payload
- * module breaks. (Importing ./codex.js directly would self-register and stay
- * green when the barrel line is deleted.)
- */
-import { describe, expect, it } from 'vitest';
-
-import { getSetupProvider } from './registry.js';
-import './index.js'; // the real setup provider barrel
-
-describe('codex setup registration', () => {
-  it('registers codex with auth + install check via the barrel', () => {
-    const codex = getSetupProvider('codex');
-    expect(codex).toBeDefined();
-    expect(typeof codex!.runAuth).toBe('function');
-    expect(typeof codex!.runInstallCheck).toBe('function');
-    expect(typeof codex!.offerFailureAssist).toBe('function');
-  });
-});

setup/providers/codex.test.ts

@@ -1,101 +0,0 @@
-import { EventEmitter } from 'events';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import { describe, expect, it, vi } from 'vitest';
-
-// Mock child_process so runCodexLoginAuth never spawns a real codex CLI; the
-// spawn stand-in plays `codex login` writing auth.json into whatever
-// CODEX_HOME it was handed.
-const mockSpawn = vi.fn();
-const mockSpawnSync = vi.fn();
-const mockExecFileSync = vi.fn();
-vi.mock('child_process', () => ({
-  spawn: (...args: unknown[]) => mockSpawn(...args),
-  spawnSync: (...args: unknown[]) => mockSpawnSync(...args),
-  execFileSync: (...args: unknown[]) => mockExecFileSync(...args),
-}));
-
-// Keep the auth flow's structured logging out of logs/setup.log.
-vi.mock('../logs.js', () => ({ step: vi.fn(), userInput: vi.fn() }));
-
-import { buildCodexFailurePrompt, runCodexLoginAuth, verifyCodexInstall } from './codex.js';
-
-// Structural guard for the codex payload wiring: provider files, both barrel
-// imports, and the pinned Dockerfile install. Goes red if any of them is
-// removed without going through the /add-codex (or its REMOVE.md) path.
-describe('verifyCodexInstall', () => {
-  it('passes on a tree with the codex payload wired', () => {
-    const { ok, problems } = verifyCodexInstall();
-    expect(problems).toEqual([]);
-    expect(ok).toBe(true);
-  });
-});
-
-// Pure prompt builder for the failure-assist hook — no spawning involved.
-describe('buildCodexFailurePrompt', () => {
-  it('carries the failure context and the de-duped reference list', () => {
-    const projectRoot = '/repo';
-    const prompt = buildCodexFailurePrompt(
-      {
-        stepName: 'verify',
-        msg: 'first-chat ping timed out',
-        hint: 'check the container logs',
-        rawLogPath: '/repo/logs/setup-steps/verify.log',
-      },
-      projectRoot,
-    );
-
-    expect(prompt).toContain('Failed step: verify');
-    expect(prompt).toContain('Error: first-chat ping timed out');
-    expect(prompt).toContain('Hint: check the container logs');
-    expect(prompt).toContain('README.md'); // BIG_PICTURE_FILES
-    expect(prompt).toContain('setup/verify.ts'); // STEP_FILES['verify']
-    expect(prompt).toContain('logs/setup.log');
-    expect(prompt).toContain('logs/setup-steps/verify.log'); // relativized rawLogPath
-  });
-
-  it('falls back to the step-log directory when no raw log path is given', () => {
-    const prompt = buildCodexFailurePrompt({ stepName: 'verify', msg: 'boom' }, '/repo');
-    expect(prompt).toContain('logs/setup-steps/');
-    expect(prompt).not.toContain('Hint:');
-  });
-});
-
-// Session-isolation invariant: the ChatGPT session vaulted for the gateway
-// must never be the user's personal ~/.codex session — sharing one OAuth
-// session across two consumers gets the whole family invalidated server-side
-// when refresh tokens rotate (see the header of codex.ts).
-describe('runCodexLoginAuth', () => {
-  it('logs in under an isolated CODEX_HOME, vaults from it, and deletes it', async () => {
-    mockSpawnSync.mockReturnValue({ status: 0, stdout: '', stderr: '' });
-    mockExecFileSync.mockReturnValue('');
-
-    let loginEnv: NodeJS.ProcessEnv | undefined;
-    mockSpawn.mockImplementation((...args: unknown[]) => {
-      const opts = args[2] as { env?: NodeJS.ProcessEnv };
-      loginEnv = opts.env;
-      fs.writeFileSync(path.join(opts.env!.CODEX_HOME!, 'auth.json'), '{"tokens":{}}');
-      const child = new EventEmitter();
-      setImmediate(() => child.emit('close', 0));
-      return child;
-    });
-
-    await runCodexLoginAuth('browser');
-
-    // The login spawn ran under a CODEX_HOME that is not the personal one.
-    const codexHome = loginEnv?.CODEX_HOME;
-    expect(codexHome).toBeDefined();
-    expect(codexHome).not.toBe(path.join(os.homedir(), '.codex'));
-
-    // The vault snapshot was read from the isolated dir, not ~/.codex.
-    const vaultCall = mockExecFileSync.mock.calls.find((c) => c[0] === 'onecli');
-    expect(vaultCall).toBeDefined();
-    const vaultArgs = vaultCall![1] as string[];
-    expect(vaultArgs[vaultArgs.indexOf('--file') + 1]).toBe(path.join(codexHome!, 'auth.json'));
-
-    // The isolated dir holds a live credential — gone once vaulted.
-    expect(fs.existsSync(codexHome!)).toBe(false);
-  });
-});

setup/providers/codex.ts

@@ -1,441 +0,0 @@
-/**
- * Codex provider setup — auth walk-through + install verification.
- *
- * Codex-owned payload code: when the codex provider moves to the `providers`
- * branch, this file travels with it and `/add-codex` copies it back in. The
- * only trunk reach-in is one import + one picker entry in setup/auto.ts.
- *
- * Auth honors the v2 credential invariant — everything lands in the OneCLI
- * vault, nothing in .env, nothing in the container:
- *   - ChatGPT subscription (the common case): `codex login` (browser) or
- *     `codex login --device-auth` (URL + pairing code) runs with CODEX_HOME
- *     pointed at a throwaway dir; the auth.json written there is stored
- *     WHOLE in the vault (`--file … --host-pattern chatgpt.com`) and the dir
- *     is deleted. The gateway injects it in flight; the container only ever
- *     sees the `onecli-managed` placeholder.
- *   - API key: pasted once, stored as an `openai` secret for api.openai.com.
- *
- * Session-isolation invariant: the vaulted ChatGPT session must be DEDICATED
- * to the gateway. Never vault a copy of the user's live ~/.codex/auth.json.
- * OpenAI rotates refresh tokens, so two consumers sharing one OAuth session
- * strand each other on refresh, and replaying the stale token trips reuse
- * detection — which invalidates the whole session family server-side
- * (`token_invalidated`) for the gateway AND the user's personal Codex CLI.
- */
-import { execFileSync, spawn, spawnSync } from 'child_process';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-
-import * as p from '@clack/prompts';
-import k from 'kleur';
-
-import { brightSelect } from '../lib/bright-select.js';
-import { type AssistContext, BIG_PICTURE_FILES, STEP_FILES } from '../lib/claude-assist.js';
-import { brandBody, note } from '../lib/theme.js';
-import * as setupLog from '../logs.js';
-import { type FailureAssistResult, registerSetupProvider } from './registry.js';
-
-// ─── OneCLI vault helpers ────────────────────────────────────────────────
-
-interface OnecliSecret {
-  id: string;
-  name: string;
-  type: string;
-  hostPattern: string | null;
-}
-
-function listSecrets(): OnecliSecret[] {
-  const out = execFileSync('onecli', ['secrets', 'list'], { encoding: 'utf-8' });
-  const parsed = JSON.parse(out) as { data?: unknown };
-  return Array.isArray(parsed.data) ? (parsed.data as OnecliSecret[]) : [];
-}
-
-function findOpenAISecret(secrets: OnecliSecret[]): OnecliSecret | undefined {
-  return secrets.find((s) => {
-    const name = s.name.toLowerCase();
-    const type = s.type.toLowerCase();
-    const hostPattern = (s.hostPattern ?? '').toLowerCase();
-    return (
-      name === 'codex' ||
-      name === 'openai' ||
-      type === 'openai' ||
-      hostPattern.includes('api.openai.com') ||
-      hostPattern.includes('chatgpt.com')
-    );
-  });
-}
-
-function openAISecretExists(): boolean {
-  try {
-    return findOpenAISecret(listSecrets()) !== undefined;
-  } catch {
-    return false;
-  }
-}
-
-// ─── auth step ───────────────────────────────────────────────────────────
-
-function ensureAnswer<T>(value: T | symbol): T {
-  if (p.isCancel(value)) {
-    p.cancel('Setup cancelled.');
-    process.exit(1);
-  }
-  return value as T;
-}
-
-export async function runCodexAuthStep(): Promise<void> {
-  if (openAISecretExists()) {
-    p.log.success(brandBody('Your OpenAI account is already connected.'));
-    setupLog.step('auth', 'skipped', 0, { REASON: 'openai-secret-already-present', PROVIDER: 'codex' });
-    return;
-  }
-
-  const method = ensureAnswer(
-    await brightSelect<'browser' | 'device' | 'api' | 'skip'>({
-      message: 'How would you like to connect Codex?',
-      options: [
-        {
-          value: 'browser',
-          label: 'Sign in with my ChatGPT subscription',
-          hint: 'recommended if you have Plus or Pro — opens a browser',
-        },
-        {
-          value: 'device',
-          label: 'ChatGPT device pairing',
-          hint: 'no browser handoff — shows a URL and a code',
-        },
-        {
-          value: 'api',
-          label: 'Paste an OpenAI API key',
-          hint: 'pay-per-use; stored in OneCLI, never copied into the container',
-        },
-        {
-          value: 'skip',
-          label: "Skip — I'll connect later",
-          hint: 'Codex groups will start, but model calls will fail auth',
-        },
-      ],
-    }),
-  );
-  setupLog.userInput('codex_auth_method', method);
-
-  if (method === 'skip') {
-    const confirmed = ensureAnswer(
-      await p.confirm({
-        message: "Skip Codex sign-in? Codex won't be able to answer until you connect an OpenAI account.",
-        initialValue: false,
-      }),
-    );
-    if (!confirmed) return runCodexAuthStep();
-    setupLog.step('auth', 'skipped', 0, { REASON: 'user-skipped', PROVIDER: 'codex' });
-    p.log.warn(brandBody('Codex sign-in skipped. Add an OpenAI account to OneCLI before using Codex groups.'));
-    return;
-  }
-
-  if (method === 'api') {
-    await runCodexApiKeyAuth();
-    return;
-  }
-
-  await runCodexLoginAuth(method);
-}
-
-async function runCodexApiKeyAuth(): Promise<void> {
-  const key = ensureAnswer(
-    await p.password({
-      message: 'Paste your OpenAI API key (sk-…)',
-      validate: (v) => (v && v.trim().startsWith('sk-') ? undefined : 'That does not look like an OpenAI API key.'),
-    }),
-  ) as string;
-
-  try {
-    execFileSync(
-      'onecli',
-      [
-        'secrets',
-        'create',
-        '--name',
-        'Codex',
-        '--type',
-        'openai',
-        '--value',
-        key.trim(),
-        '--host-pattern',
-        'api.openai.com',
-      ],
-      { stdio: ['ignore', 'pipe', 'pipe'] },
-    );
-  } catch (err) {
-    setupLog.step('auth', 'failed', 0, { PROVIDER: 'codex', METHOD: 'api', ERROR: String(err) });
-    p.log.error(
-      brandBody(
-        "Couldn't save your OpenAI key to the vault. Make sure OneCLI is running (`onecli version`), then retry.",
-      ),
-    );
-    process.exit(1);
-  }
-  setupLog.step('auth', 'success', 0, { PROVIDER: 'codex', METHOD: 'api' });
-  p.log.success(brandBody('OpenAI account connected.'));
-}
-
-export async function runCodexLoginAuth(method: 'browser' | 'device'): Promise<void> {
-  const codexCheck = spawnSync('codex', ['--version'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-  if (codexCheck.status !== 0) {
-    p.log.error(
-      brandBody(
-        'The Codex CLI is not installed on this machine. Install it with `npm install -g @openai/codex`, then re-run setup — or choose the API key option instead.',
-      ),
-    );
-    setupLog.step('auth', 'failed', 0, { PROVIDER: 'codex', METHOD: method, ERROR: 'codex_cli_missing' });
-    process.exit(1);
-  }
-
-  if (method === 'browser') {
-    p.log.step(brandBody('Opening the Codex sign-in flow…'));
-    console.log(k.dim('   (a browser will open for sign-in; this part is interactive)'));
-  } else {
-    p.log.step(brandBody('Starting Codex device-code pairing…'));
-    console.log(k.dim('   (a URL and code will appear below — open the URL and enter the code)'));
-  }
-  console.log();
-
-  // Session-isolation invariant (see file header): the login runs under a
-  // throwaway CODEX_HOME so the vaulted session is dedicated to the gateway
-  // and never shared with the user's personal ~/.codex.
-  const loginHome = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-vault-login-'));
-  // Holds a live credential after login — must go on every exit path. The
-  // failure branches call process.exit, which skips finally blocks, so each
-  // removes it explicitly.
-  const removeLoginHome = (): void => fs.rmSync(loginHome, { recursive: true, force: true });
-
-  const args = method === 'device' ? ['login', '--device-auth'] : ['login'];
-  const start = Date.now();
-  const code = await runInherit('codex', args, { CODEX_HOME: loginHome });
-  const durationMs = Date.now() - start;
-  console.log();
-
-  if (code !== 0) {
-    removeLoginHome();
-    setupLog.step('auth', 'failed', durationMs, { PROVIDER: 'codex', METHOD: method, EXIT_CODE: String(code) });
-    p.log.error(
-      brandBody(
-        "Couldn't complete the Codex sign-in. Re-run setup and try again, or choose the API key option instead.",
-      ),
-    );
-    process.exit(1);
-  }
-
-  const authJsonPath = path.join(loginHome, 'auth.json');
-  if (!fs.existsSync(authJsonPath)) {
-    removeLoginHome();
-    setupLog.step('auth', 'failed', durationMs, { PROVIDER: 'codex', METHOD: method, ERROR: 'auth_json_not_found' });
-    p.log.error(
-      brandBody('Codex login succeeded but no auth.json was written. Try again, or paste an API key instead.'),
-    );
-    process.exit(1);
-  }
-
-  try {
-    execFileSync(
-      'onecli',
-      [
-        'secrets',
-        'create',
-        '--name',
-        'Codex',
-        '--type',
-        'openai',
-        '--file',
-        authJsonPath,
-        '--host-pattern',
-        'chatgpt.com',
-      ],
-      { stdio: ['ignore', 'pipe', 'pipe'] },
-    );
-  } catch (err) {
-    removeLoginHome();
-    setupLog.step('auth', 'failed', durationMs, { PROVIDER: 'codex', METHOD: method, ERROR: String(err) });
-    p.log.error(
-      brandBody(
-        "Couldn't save your Codex credentials to the vault. Make sure OneCLI is running (`onecli version`), then retry.",
-      ),
-    );
-    process.exit(1);
-  }
-  removeLoginHome();
-  setupLog.step('auth', 'success', durationMs, { PROVIDER: 'codex', METHOD: method });
-  p.log.success(brandBody('OpenAI account connected — credentials live in your OneCLI vault, never in the container.'));
-}
-
-function runInherit(cmd: string, args: string[], extraEnv?: Record<string, string>): Promise<number> {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, args, {
-      stdio: 'inherit',
-      env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
-    });
-    child.on('close', (code) => resolve(code ?? 1));
-    child.on('error', () => resolve(1));
-  });
-}
-
-// ─── failure assist ──────────────────────────────────────────────────────
-
-/**
- * The Codex CLI can debug a setup failure only if the binary runs AND
- * ~/.codex/auth.json exists (API-key-only installs keep the key in the
- * OneCLI vault, so the host-side CLI has nothing to authenticate with).
- */
-export function isCodexCliUsable(): boolean {
-  const codexCheck = spawnSync('codex', ['--version'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-  if (codexCheck.status !== 0) return false;
-  return fs.existsSync(path.join(os.homedir(), '.codex', 'auth.json'));
-}
-
-/**
- * Failure prompt handed to the interactive Codex session — same content as
- * the dispatcher's Claude system prompt: what failed, the job ("diagnose and
- * fix, be concise, exit when done"), and a de-duped file reference list.
- */
-export function buildCodexFailurePrompt(ctx: AssistContext, projectRoot: string): string {
-  const stepRefs = STEP_FILES[ctx.stepName] ?? [];
-  const references = [
-    ...BIG_PICTURE_FILES,
-    ...stepRefs,
-    'logs/setup.log',
-    ctx.rawLogPath ? path.relative(projectRoot, ctx.rawLogPath) : 'logs/setup-steps/',
-  ].filter((v, i, a) => a.indexOf(v) === i);
-
-  const lines: string[] = [
-    "The user is running NanoClaw's interactive setup flow and hit a failure.",
-    '',
-    `Failed step: ${ctx.stepName}`,
-    `Error: ${ctx.msg}`,
-  ];
-
-  if (ctx.hint) lines.push(`Hint: ${ctx.hint}`);
-
-  lines.push(
-    '',
-    'Your job: help them diagnose and fix this issue. Read the referenced files',
-    'and logs to understand what went wrong, then help them fix it. You can read',
-    'files, run commands, check logs, and explain what happened. Be concise.',
-    "When they're ready to resume setup, tell them to exit Codex.",
-    '',
-    'Relevant files (read as needed):',
-  );
-  for (const f of references) lines.push(`  - ${f}`);
-
-  return lines.join('\n');
-}
-
-/**
- * Registry hook: offer to debug a setup failure with the Codex CLI. Returns
- * 'unavailable' when the CLI can't run here so the dispatcher can fall back
- * to its guarded Claude offer.
- */
-export async function offerCodexFailureAssist(ctx: AssistContext, projectRoot: string): Promise<FailureAssistResult> {
-  if (!isCodexCliUsable()) return 'unavailable';
-
-  const want = ensureAnswer(
-    await p.confirm({
-      message: 'Want to debug this with Codex?',
-      initialValue: true,
-    }),
-  );
-  if (!want) return 'declined';
-
-  const prompt = buildCodexFailurePrompt(ctx, projectRoot);
-
-  note(
-    [
-      'Launching Codex to help debug this failure.',
-      'It has the context of what went wrong.',
-      '',
-      k.dim("Exit Codex (Ctrl-C or /quit) when you're ready to come back to setup."),
-    ].join('\n'),
-    'Handing off to Codex',
-  );
-
-  return new Promise<FailureAssistResult>((resolve) => {
-    // codex accepts a positional initial prompt for the interactive TUI.
-    const child = spawn('codex', [prompt], { cwd: projectRoot, stdio: 'inherit' });
-    child.on('close', () => {
-      p.log.success(brandBody("Back from Codex. Let's continue."));
-      resolve('launched');
-    });
-    child.on('error', () => {
-      p.log.error("Couldn't launch Codex.");
-      resolve('unavailable');
-    });
-  });
-}
-
-// ─── install verification ────────────────────────────────────────────────
-
-/**
- * Verify the codex provider payload is fully wired — the same pre-flight the
- * /add-codex skill checks. While codex ships in trunk these always pass; once
- * the payload moves to the providers branch, a failed check means the install
- * step should run (or the user finishes via /add-codex).
- */
-export function verifyCodexInstall(): { ok: boolean; problems: string[] } {
-  const problems: string[] = [];
-  const root = process.cwd();
-
-  const requiredFiles = [
-    'src/providers/codex.ts',
-    'src/providers/codex-agents-md.ts',
-    'container/agent-runner/src/providers/codex.ts',
-    'container/agent-runner/src/providers/codex-app-server.ts',
-  ];
-  for (const file of requiredFiles) {
-    if (!fs.existsSync(path.join(root, file))) problems.push(`missing file: ${file}`);
-  }
-
-  for (const barrel of ['src/providers/index.ts', 'container/agent-runner/src/providers/index.ts']) {
-    const barrelPath = path.join(root, barrel);
-    if (!fs.existsSync(barrelPath) || !fs.readFileSync(barrelPath, 'utf-8').includes("import './codex.js';")) {
-      problems.push(`missing barrel import in ${barrel}`);
-    }
-  }
-
-  const dockerfilePath = path.join(root, 'container', 'Dockerfile');
-  const dockerfile = fs.existsSync(dockerfilePath) ? fs.readFileSync(dockerfilePath, 'utf-8') : '';
-  if (!/ARG CODEX_VERSION=/.test(dockerfile) || !dockerfile.includes('@openai/codex@${CODEX_VERSION}')) {
-    problems.push('container/Dockerfile missing the pinned @openai/codex install');
-  }
-
-  return { ok: problems.length === 0, problems };
-}
-
-export async function runCodexInstallCheck(): Promise<void> {
-  p.log.step(brandBody('Checking the Codex provider install…'));
-  const { ok, problems } = verifyCodexInstall();
-  if (ok) {
-    setupLog.step('codex-install', 'success', 0, {});
-    p.log.success(brandBody('Codex installed properly.'));
-    return;
-  }
-
-  setupLog.step('codex-install', 'failed', 0, { PROBLEMS: problems.join('; ') });
-  p.log.warn(brandBody('The Codex provider is not fully installed:'));
-  for (const problem of problems) console.log(k.dim(`   • ${problem}`));
-  p.log.warn(
-    brandBody(
-      'Finish it with your coding agent of choice: open Codex CLI or Claude Code in this repo and run the /add-codex skill. Setup will continue — Codex groups will work once the install completes.',
-    ),
-  );
-}
-
-// Self-registration: the setup picker and the standalone `provider-auth` step
-// render from the registry — this call is codex's only reach-in to the setup
-// flow (guarded by the barrel-driven registration test).
-registerSetupProvider({
-  value: 'codex',
-  label: 'Codex',
-  hint: 'OpenAI — ChatGPT subscription or API key',
-  runAuth: runCodexAuthStep,
-  runInstallCheck: runCodexInstallCheck,
-  offerFailureAssist: offerCodexFailureAssist,
-});

setup/whatsapp-auth.ts

@@ -1,5 +1,5 @@
 /**
- * Step: whatsapp-auth — standalone WhatsApp (Baileys) authentication.
+ * Step: whatsapp-auth — standalone WhatsApp (Baileys v7) authentication.
  *
  * Forked from the channels-branch version so setup:auto's driver can render
  * the terminal UX itself (inside clack) instead of the step dumping a raw QR
@@ -27,7 +27,6 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { createRequire } from 'module';
 // Named import (not default) — pino's d.ts under NodeNext resolves the
 // default export to `typeof pino` (namespace), which isn't callable. The
 // named `pino` export resolves to the callable function.
@@ -47,26 +46,23 @@ const AUTH_DIR = path.join(process.cwd(), 'store', 'auth');
 const PAIRING_CODE_FILE = path.join(process.cwd(), 'store', 'pairing-code.txt');
 const baileysLogger = pino({ level: 'silent' });
 
-// Baileys v6 bug: getPlatformId sends charCode (49) instead of enum value (1).
-// Fixed in Baileys 7.x but not backported. Without this patch pairing codes
-// fail with "couldn't link device" because WhatsApp receives an invalid
-// platform id. createRequire because proto is not a named ESM export.
-const _require = createRequire(import.meta.url);
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { proto } = _require('@whiskeysockets/baileys') as { proto: any };
-try {
-  const _generics = _require(
-    '@whiskeysockets/baileys/lib/Utils/generics',
-  ) as Record<string, unknown>;
-  _generics.getPlatformId = (browser: string): string => {
-    const platformType =
-      proto.DeviceProps.PlatformType[
-        browser.toUpperCase() as keyof typeof proto.DeviceProps.PlatformType
-      ];
-    return platformType ? platformType.toString() : '1';
-  };
-} catch {
-  // If CJS require fails, QR auth still works; only pairing code may be affected.
+/** Fetch current WA Web version — wppconnect tracker, then Baileys sw.js scrape. */
+async function resolveWaWebVersion(): Promise<[number, number, number]> {
+  try {
+    const res = await fetch('https://wppconnect.io/whatsapp-versions/', {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.ok) {
+      const html = await res.text();
+      const match = html.match(/2\.3000\.(\d+)/);
+      if (match) return [2, 3000, Number(match[1])];
+    }
+  } catch { /* fall through */ }
+  try {
+    const { version } = await fetchLatestWaWebVersion({});
+    if (version) return version as [number, number, number];
+  } catch { /* fall through */ }
+  throw new Error('Could not fetch current WhatsApp Web version — cannot connect with stale version');
 }
 
 type AuthMethod = 'qr' | 'pairing-code';
@@ -139,9 +135,7 @@ export async function run(args: string[]): Promise<void> {
 
     async function connectSocket(isReconnect = false): Promise<void> {
       const { state, saveCreds } = await useMultiFileAuthState(AUTH_DIR);
-      const { version } = await fetchLatestWaWebVersion({}).catch(() => ({
-        version: undefined,
-      }));
+      const version = await resolveWaWebVersion();
 
       const sock = makeWASocket({
         version,

src/channels/deltachat-registration.test.ts

@@ -0,0 +1,28 @@
+/**
+ * Integration test for the deltachat channel's single reach-in: the
+ * self-registration import in the `src/channels/index.ts` barrel. Importing the
+ * barrel runs deltachat.ts's top-level `registerChannelAdapter('deltachat', …)`;
+ * without the import the channel is silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './deltachat.js';` line is deleted, or the barrel fails to evaluate for
+ * any reason (so the channel genuinely would not register), this goes red. A
+ * structural check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and
+ * deltachat.ts only instantiates DeltaChatOverJsonRpc inside setup() (run at host
+ * startup), never at import — so nothing spawns here. It does require the adapter
+ * package to be installed, which holds in a composed install: the skill's
+ * `pnpm install` step runs before this test in the apply flow.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('deltachat channel registration', () => {
+  it('registers deltachat via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('deltachat');
+  });
+});

src/channels/deltachat.ts

@@ -0,0 +1,338 @@
+/**
+ * DeltaChat channel adapter.
+ *
+ * Bridges NanoClaw with DeltaChat via the @deltachat/stdio-rpc-server JSON-RPC
+ * process. Each DeltaChat chat becomes a separate NanoClaw messaging group
+ * (platformId = chatId string, e.g. "12"). No thread model — supportsThreads: false.
+ *
+ * Required env vars (.env): DC_EMAIL, DC_PASSWORD,
+ *                           DC_IMAP_HOST, DC_IMAP_PORT,
+ *                           DC_SMTP_HOST, DC_SMTP_PORT
+ * Optional env vars (.env): DC_IMAP_SECURITY (default: "1" = SSL/TLS),
+ *                           DC_SMTP_SECURITY (default: "2" = STARTTLS)
+ *                           Security values: 1=SSL/TLS, 2=STARTTLS, 3=plain
+ * Optional env vars (service unit): DC_ACCOUNT_DIR (default: "dc-account"),
+ *                                   DC_DISPLAY_NAME, DC_AVATAR_PATH
+ */
+import { existsSync, mkdtempSync, writeFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { basename, join, resolve } from 'path';
+
+import { getDb, hasTable } from '../db/connection.js';
+import { readEnvFile } from '../env.js';
+import { log } from '../log.js';
+import type { ChannelAdapter, ChannelSetup, OutboundMessage } from './adapter.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+import { DeltaChatOverJsonRpc } from '@deltachat/stdio-rpc-server';
+
+const REQUIRED_ENV = [
+  'DC_EMAIL',
+  'DC_PASSWORD',
+  'DC_IMAP_HOST',
+  'DC_IMAP_PORT',
+  'DC_SMTP_HOST',
+  'DC_SMTP_PORT',
+] as const;
+
+const OPTIONAL_ENV = ['DC_IMAP_SECURITY', 'DC_SMTP_SECURITY'] as const;
+
+type DcEnv = { [K in (typeof REQUIRED_ENV)[number]]: string } & { [K in (typeof OPTIONAL_ENV)[number]]?: string };
+
+function isDcAdmin(userId: string): boolean {
+  try {
+    const db = getDb();
+    if (!hasTable(db, 'user_roles')) return true;
+    return (
+      db
+        .prepare(
+          `SELECT 1 FROM user_roles
+       WHERE user_id = ?
+         AND (role = 'owner' OR role = 'admin')
+         AND agent_group_id IS NULL
+       LIMIT 1`,
+        )
+        .get(userId) != null
+    );
+  } catch {
+    return false;
+  }
+}
+
+function createAdapter(env: DcEnv): ChannelAdapter {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let dc: any = null;
+  let accountId = 0;
+  let connectivity = 0;
+  let lastImapIdleTs = Date.now();
+  let consecutiveBadChecks = 0;
+  let watchdogTimer: ReturnType<typeof setInterval> | null = null;
+  let networkTimer: ReturnType<typeof setInterval> | null = null;
+
+  async function restartIo(reason: string): Promise<void> {
+    log.warn('DeltaChat: restarting IO', { reason });
+    try {
+      await dc.rpc.stopIo(accountId);
+      await dc.rpc.startIo(accountId);
+      lastImapIdleTs = Date.now();
+      consecutiveBadChecks = 0;
+    } catch (err) {
+      log.error('DeltaChat: IO restart failed', { err });
+    }
+  }
+
+  const adapter: ChannelAdapter = {
+    name: 'deltachat',
+    channelType: 'deltachat',
+    supportsThreads: false,
+
+    async setup(config: ChannelSetup): Promise<void> {
+      const accountDir = process.env.DC_ACCOUNT_DIR ?? 'dc-account';
+      dc = new DeltaChatOverJsonRpc(accountDir, {});
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      dc.on('Error', (_: any, event: any) => log.error('DeltaChat RPC error', { msg: event.msg ?? event }));
+
+      const accounts = await dc.rpc.getAllAccounts();
+      accountId = accounts[0]?.id;
+      if (!accountId) accountId = await dc.rpc.addAccount();
+
+      const imapSecurity = env.DC_IMAP_SECURITY ?? '1';
+      const smtpSecurity = env.DC_SMTP_SECURITY ?? '2';
+
+      if (!(await dc.rpc.isConfigured(accountId))) {
+        await dc.rpc.setConfig(accountId, 'addr', env.DC_EMAIL);
+        await dc.rpc.setConfig(accountId, 'mail_pw', env.DC_PASSWORD);
+        await dc.rpc.setConfig(accountId, 'mail_server', env.DC_IMAP_HOST);
+        await dc.rpc.setConfig(accountId, 'mail_port', env.DC_IMAP_PORT);
+        await dc.rpc.setConfig(accountId, 'send_server', env.DC_SMTP_HOST);
+        await dc.rpc.setConfig(accountId, 'send_port', env.DC_SMTP_PORT);
+        await dc.rpc.configure(accountId);
+        log.info('DeltaChat: account configured', { email: env.DC_EMAIL });
+      } else {
+        log.info('DeltaChat: account ready', { email: env.DC_EMAIL });
+      }
+
+      await dc.rpc.setConfig(accountId, 'mail_security', imapSecurity);
+      await dc.rpc.setConfig(accountId, 'send_security', smtpSecurity);
+      await dc.rpc.setConfig(accountId, 'displayname', process.env.DC_DISPLAY_NAME ?? 'NanoClaw');
+      const avatarPath = process.env.DC_AVATAR_PATH;
+      if (avatarPath && existsSync(avatarPath)) {
+        await dc.rpc.setConfig(accountId, 'selfavatar', avatarPath);
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      dc.on('IncomingMsg', async (contextId: number, event: any) => {
+        if (contextId !== accountId) return;
+        try {
+          let msg = await dc.rpc.getMessage(accountId, event.msgId);
+          if (msg.isInfo) return;
+
+          // Wait for large-message download to complete
+          if (msg.downloadState !== 'Done') {
+            await dc.rpc.downloadFullMessage(accountId, event.msgId);
+            for (let i = 0; i < 30; i++) {
+              await new Promise((r) => setTimeout(r, 1000));
+              msg = await dc.rpc.getMessage(accountId, event.msgId);
+              if (msg.downloadState === 'Done') break;
+            }
+          }
+
+          if (!msg.text && !msg.file) return;
+
+          const contact = await dc.rpc.getContact(accountId, msg.fromId);
+          const chat = await dc.rpc.getBasicChatInfo(accountId, event.chatId);
+
+          if (/^\/set-avatar$/i.test((msg.text || '').trim()) && msg.file) {
+            const userId = `deltachat:${contact.address}`;
+            try {
+              if (isDcAdmin(userId)) {
+                const absPath = resolve(msg.file as string);
+                await dc.rpc.setConfig(accountId, 'selfavatar', absPath);
+                await dc.rpc.sendMsg(accountId, event.chatId, { text: 'Avatar updated.' });
+              } else {
+                await dc.rpc.sendMsg(accountId, event.chatId, { text: 'Permission denied.' });
+              }
+            } catch (avatarErr: unknown) {
+              log.error('DeltaChat: failed to set avatar', {
+                err: avatarErr instanceof Error ? avatarErr.message : JSON.stringify(avatarErr),
+              });
+              await dc.rpc.sendMsg(accountId, event.chatId, { text: 'Failed to set avatar.' }).catch(() => {});
+            }
+            return;
+          }
+
+          const content: Record<string, unknown> = {
+            text: msg.text || '',
+            sender: contact.displayName || contact.address,
+            senderId: contact.address,
+          };
+          if (msg.file) {
+            content.attachments = [
+              {
+                name: basename(msg.file as string),
+                type: 'file',
+                localPath: msg.file,
+              },
+            ];
+          }
+
+          const isGroup = chat?.isGroup ?? false;
+          await config.onInbound(String(event.chatId), null, {
+            id: String(event.msgId),
+            kind: 'chat',
+            content,
+            timestamp: new Date().toISOString(),
+            isGroup,
+            isMention: !isGroup,
+          });
+        } catch (err: unknown) {
+          log.error('DeltaChat: error handling incoming message', {
+            err: err instanceof Error ? err.message : JSON.stringify(err),
+          });
+        }
+      });
+
+      dc.on('ImapInboxIdle', (contextId: number) => {
+        if (contextId === accountId) lastImapIdleTs = Date.now();
+      });
+
+      dc.on('ConnectivityChanged', async (contextId: number) => {
+        if (contextId !== accountId) return;
+        try {
+          connectivity = await dc.rpc.getConnectivity(accountId);
+        } catch {
+          /* ignore */
+        }
+      });
+
+      await dc.rpc.startIo(accountId);
+      try {
+        connectivity = await dc.rpc.getConnectivity(accountId);
+      } catch {
+        /* ignore */
+      }
+      log.info('DeltaChat: IO started', { email: env.DC_EMAIL });
+
+      // Log invite link on every startup so the operator can bootstrap the first contact.
+      // In DeltaChat, contacts can't simply be added by email — the user must open this
+      // https://i.delta.chat/ invite URL in their DeltaChat app (or scan invite-qr.svg) to initiate contact.
+      try {
+        // null chatId → Setup-Contact invite (not group-specific)
+        const [inviteUrl, svg] = await dc.rpc.getChatSecurejoinQrCodeSvg(accountId, null);
+        const accountDir = resolve(process.env.DC_ACCOUNT_DIR ?? 'dc-account');
+        const svgPath = join(accountDir, 'invite-qr.svg');
+        writeFileSync(svgPath, svg);
+        log.info('DeltaChat: invite link — open URL in DeltaChat app or scan ' + svgPath, { url: inviteUrl });
+      } catch (err: unknown) {
+        log.warn('DeltaChat: could not generate invite link', {
+          err: err instanceof Error ? err.message : JSON.stringify(err),
+        });
+      }
+
+      // Connectivity watchdog: restart IO if IMAP goes quiet or connectivity drops
+      watchdogTimer = setInterval(
+        async () => {
+          try {
+            const conn = await dc.rpc.getConnectivity(accountId);
+            connectivity = conn;
+            if (conn < 3000) {
+              consecutiveBadChecks++;
+              if (consecutiveBadChecks >= 2) {
+                await restartIo(`connectivity=${conn} for 2 consecutive checks`);
+              }
+            } else {
+              consecutiveBadChecks = 0;
+            }
+            const idleAgeMin = (Date.now() - lastImapIdleTs) / 60000;
+            if (idleAgeMin > 20) {
+              await restartIo(`no IMAP IDLE in ${idleAgeMin.toFixed(0)}min`);
+            }
+          } catch (err: unknown) {
+            log.warn('DeltaChat: watchdog error', {
+              err: err instanceof Error ? err.message : String(err),
+            });
+          }
+        },
+        5 * 60 * 1000,
+      );
+
+      // Nudge the network stack every 10 minutes (recovers from prolonged idle)
+      networkTimer = setInterval(
+        async () => {
+          try {
+            await dc.rpc.maybeNetwork();
+          } catch {
+            /* ignore */
+          }
+        },
+        10 * 60 * 1000,
+      );
+    },
+
+    async teardown(): Promise<void> {
+      if (watchdogTimer) clearInterval(watchdogTimer);
+      if (networkTimer) clearInterval(networkTimer);
+      try {
+        await dc?.rpc.stopIo(accountId);
+      } catch {
+        /* ignore */
+      }
+      try {
+        dc?.close();
+      } catch {
+        /* ignore */
+      }
+    },
+
+    isConnected(): boolean {
+      // 4000 = fully connected (IMAP), 3000 = connecting; treat ≥3000 as live
+      return connectivity >= 3000;
+    },
+
+    async deliver(platformId: string, _threadId: string | null, message: OutboundMessage): Promise<string | undefined> {
+      const chatId = parseInt(platformId, 10);
+      if (isNaN(chatId)) {
+        log.warn('DeltaChat: invalid platformId for delivery', { platformId });
+        return undefined;
+      }
+      const content = message.content as Record<string, unknown>;
+      const text = typeof content.text === 'string' ? content.text : '';
+
+      if (message.files && message.files.length > 0) {
+        const tempDir = mkdtempSync(join(tmpdir(), 'nanoclaw-dc-'));
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          let firstId: any;
+          for (let i = 0; i < message.files.length; i++) {
+            const f = message.files[i];
+            const tempPath = join(tempDir, f.filename);
+            writeFileSync(tempPath, f.data);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const params: any = { file: tempPath };
+            if (i === 0 && text) params.text = text;
+            const sentId = await dc.rpc.sendMsg(accountId, chatId, params);
+            if (i === 0) firstId = sentId;
+          }
+          return firstId != null ? String(firstId) : undefined;
+        } finally {
+          rmSync(tempDir, { recursive: true, force: true });
+        }
+      }
+
+      if (!text) return undefined;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const sentId: any = await dc.rpc.sendMsg(accountId, chatId, { text });
+      return sentId != null ? String(sentId) : undefined;
+    },
+  };
+
+  return adapter;
+}
+
+registerChannelAdapter('deltachat', {
+  factory: () => {
+    const env = readEnvFile([...REQUIRED_ENV, ...OPTIONAL_ENV]);
+    if (!env.DC_EMAIL || !env.DC_PASSWORD) return null;
+    return createAdapter(env as DcEnv);
+  },
+});

src/channels/discord-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the discord channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs discord.ts's
+ * top-level `registerChannelAdapter('discord', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './discord.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and discord.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/discord`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * discord is a Chat SDK channel: discord.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('discord channel registration', () => {
+  it('registers discord via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('discord');
+  });
+});

src/channels/discord.ts

@@ -0,0 +1,38 @@
+/**
+ * Discord channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createDiscordAdapter } from '@chat-adapter/discord';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge, type ReplyContext } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractReplyContext(raw: Record<string, any>): ReplyContext | null {
+  if (!raw.referenced_message) return null;
+  const reply = raw.referenced_message;
+  return {
+    text: reply.content || '',
+    sender: reply.author?.global_name || reply.author?.username || 'Unknown',
+  };
+}
+
+registerChannelAdapter('discord', {
+  factory: () => {
+    const env = readEnvFile(['DISCORD_BOT_TOKEN', 'DISCORD_PUBLIC_KEY', 'DISCORD_APPLICATION_ID']);
+    if (!env.DISCORD_BOT_TOKEN) return null;
+    const discordAdapter = createDiscordAdapter({
+      botToken: env.DISCORD_BOT_TOKEN,
+      publicKey: env.DISCORD_PUBLIC_KEY,
+      applicationId: env.DISCORD_APPLICATION_ID,
+    });
+    return createChatSdkBridge({
+      adapter: discordAdapter,
+      concurrency: 'concurrent',
+      botToken: env.DISCORD_BOT_TOKEN,
+      extractReplyContext,
+      supportsThreads: true,
+    });
+  },
+});

src/channels/emacs-registration.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Integration test for the emacs channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs emacs.ts's
+ * top-level `registerChannelAdapter('emacs', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './emacs.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * emacs is a native adapter with no npm dependency (it uses the Node http builtin); it talks to an Emacs HTTP client.
+ * Importing the barrel is safe: registration is a pure top-level call and emacs.ts
+ * opens connections / spawns subprocesses only inside setup() (run at host startup),
+ * never at import. There is no adapter package to guard here — this test guards the
+ * one barrel reach-in (red if `import './emacs.js';` is deleted or the barrel fails
+ * to evaluate).
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('emacs channel registration', () => {
+  it('registers emacs via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('emacs');
+  });
+});

src/channels/emacs.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Tests for the v2 emacs channel adapter.
+ *
+ * Exercises the HTTP surface (POST /api/message, GET /api/messages) and
+ * the ChannelAdapter lifecycle (setup / teardown / isConnected / deliver).
+ */
+import http from 'http';
+import type { AddressInfo } from 'net';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createEmacsAdapter } from './emacs.js';
+import type { ChannelAdapter, ChannelSetup } from './adapter.js';
+
+vi.mock('../log.js', () => ({
+  log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+function makeSetup(overrides: Partial<ChannelSetup> = {}): ChannelSetup {
+  return {
+    onInbound: vi.fn(),
+    onInboundEvent: vi.fn(),
+    onMetadata: vi.fn(),
+    onAction: vi.fn(),
+    ...overrides,
+  };
+}
+
+/** Ask the OS for a free port, then immediately release it. Small race window
+ * before the adapter grabs it, but sufficient for local test use. */
+async function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = http.createServer();
+    srv.once('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const port = (srv.address() as AddressInfo).port;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+async function req(
+  port: number,
+  method: string,
+  path: string,
+  body?: string,
+  extraHeaders: Record<string, string> = {},
+): Promise<{ status: number; data: unknown }> {
+  return new Promise((resolve, reject) => {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json', ...extraHeaders };
+    const request = http.request({ host: '127.0.0.1', port, method, path, headers }, (res) => {
+      let raw = '';
+      res.on('data', (chunk: Buffer) => (raw += chunk.toString()));
+      res.on('end', () => {
+        try {
+          resolve({ status: res.statusCode!, data: JSON.parse(raw) });
+        } catch {
+          resolve({ status: res.statusCode!, data: raw });
+        }
+      });
+    });
+    request.on('error', reject);
+    if (body) request.write(body);
+    request.end();
+  });
+}
+
+describe('emacs adapter', () => {
+  let adapter: ChannelAdapter;
+  let port: number;
+
+  beforeEach(async () => {
+    port = await getFreePort();
+    adapter = createEmacsAdapter({ port, authToken: null, platformId: 'default' });
+  });
+
+  afterEach(async () => {
+    if (adapter.isConnected()) await adapter.teardown();
+  });
+
+  describe('lifecycle', () => {
+    it('isConnected is false before setup', () => {
+      expect(adapter.isConnected()).toBe(false);
+    });
+
+    it('isConnected is true after setup', async () => {
+      await adapter.setup(makeSetup());
+      expect(adapter.isConnected()).toBe(true);
+    });
+
+    it('isConnected is false after teardown', async () => {
+      await adapter.setup(makeSetup());
+      await adapter.teardown();
+      expect(adapter.isConnected()).toBe(false);
+    });
+
+    it('teardown is a no-op before setup', async () => {
+      await expect(adapter.teardown()).resolves.not.toThrow();
+    });
+
+    it('calls onMetadata after setup with channel name', async () => {
+      const onMetadata = vi.fn();
+      await adapter.setup(makeSetup({ onMetadata }));
+      expect(onMetadata).toHaveBeenCalledWith('default', 'Emacs', false);
+    });
+  });
+
+  describe('POST /api/message', () => {
+    let onInbound: ChannelSetup['onInbound'] & { mock: { calls: unknown[][] } };
+
+    beforeEach(async () => {
+      onInbound = vi.fn() as unknown as typeof onInbound;
+      await adapter.setup(makeSetup({ onInbound }));
+    });
+
+    it('fires onInbound with chat kind and sender metadata', async () => {
+      const { status, data } = await req(port, 'POST', '/api/message', JSON.stringify({ text: 'hello' }));
+      expect(status).toBe(200);
+      expect((data as { messageId: string }).messageId).toMatch(/^emacs-/);
+      expect(onInbound).toHaveBeenCalledOnce();
+      const [platformId, threadId, msg] = onInbound.mock.calls[0] as [string, string | null, { content: unknown }];
+      expect(platformId).toBe('default');
+      expect(threadId).toBeNull();
+      expect(msg).toMatchObject({
+        kind: 'chat',
+        content: { text: 'hello', sender: 'Emacs', senderId: 'emacs:default' },
+      });
+    });
+
+    it('returns 400 for empty text', async () => {
+      const { status } = await req(port, 'POST', '/api/message', JSON.stringify({ text: '' }));
+      expect(status).toBe(400);
+      expect(onInbound).not.toHaveBeenCalled();
+    });
+
+    it('returns 400 for whitespace-only text', async () => {
+      const { status } = await req(port, 'POST', '/api/message', JSON.stringify({ text: '   ' }));
+      expect(status).toBe(400);
+    });
+
+    it('returns 400 for invalid JSON', async () => {
+      const { status } = await req(port, 'POST', '/api/message', 'not-json');
+      expect(status).toBe(400);
+    });
+
+    it('returns 404 for unknown paths', async () => {
+      const { status } = await req(port, 'POST', '/api/unknown', JSON.stringify({ text: 'hi' }));
+      expect(status).toBe(404);
+    });
+  });
+
+  describe('GET /api/messages + deliver', () => {
+    beforeEach(async () => {
+      await adapter.setup(makeSetup());
+    });
+
+    it('returns empty buffer initially', async () => {
+      const { status, data } = await req(port, 'GET', '/api/messages?since=0');
+      expect(status).toBe(200);
+      expect(data).toEqual({ messages: [] });
+    });
+
+    it('deliver pushes text for the poll endpoint to return', async () => {
+      await adapter.deliver('default', null, { kind: 'chat', content: { text: 'reply' } });
+      const { data } = await req(port, 'GET', '/api/messages?since=0');
+      const messages = (data as { messages: { text: string; timestamp: number }[] }).messages;
+      expect(messages).toHaveLength(1);
+      expect(messages[0]?.text).toBe('reply');
+      expect(typeof messages[0]?.timestamp).toBe('number');
+    });
+
+    it('deliver accepts plain-string content', async () => {
+      await adapter.deliver('default', null, { kind: 'chat', content: 'raw text' });
+      const { data } = await req(port, 'GET', '/api/messages?since=0');
+      expect((data as { messages: { text: string }[] }).messages[0]?.text).toBe('raw text');
+    });
+
+    it('deliver skips empty text silently', async () => {
+      await adapter.deliver('default', null, { kind: 'chat', content: { text: '' } });
+      const { data } = await req(port, 'GET', '/api/messages?since=0');
+      expect((data as { messages: unknown[] }).messages).toHaveLength(0);
+    });
+
+    it('deliver rejects unknown platformId', async () => {
+      const result = await adapter.deliver('other', null, { kind: 'chat', content: { text: 'x' } });
+      expect(result).toBeUndefined();
+      const { data } = await req(port, 'GET', '/api/messages?since=0');
+      expect((data as { messages: unknown[] }).messages).toHaveLength(0);
+    });
+
+    it('filters out messages at or before the since cutoff', async () => {
+      await adapter.deliver('default', null, { kind: 'chat', content: { text: 'old' } });
+      const since = Date.now();
+      await new Promise((r) => setTimeout(r, 5));
+      await adapter.deliver('default', null, { kind: 'chat', content: { text: 'new' } });
+      const { data } = await req(port, 'GET', `/api/messages?since=${since}`);
+      const texts = (data as { messages: { text: string }[] }).messages.map((m) => m.text);
+      expect(texts).not.toContain('old');
+      expect(texts).toContain('new');
+    });
+
+    it('caps buffer at 200 messages, evicting the oldest', async () => {
+      for (let i = 0; i < 205; i++) {
+        await adapter.deliver('default', null, { kind: 'chat', content: { text: `m-${i}` } });
+      }
+      const { data } = await req(port, 'GET', '/api/messages?since=0');
+      const messages = (data as { messages: { text: string }[] }).messages;
+      expect(messages).toHaveLength(200);
+      expect(messages.map((m) => m.text)).not.toContain('m-0');
+      expect(messages.map((m) => m.text)).toContain('m-5');
+      expect(messages.map((m) => m.text)).toContain('m-204');
+    });
+  });
+
+  describe('auth', () => {
+    let authAdapter: ChannelAdapter;
+    let authPort: number;
+
+    beforeEach(async () => {
+      authPort = await getFreePort();
+      authAdapter = createEmacsAdapter({ port: authPort, authToken: 'secret', platformId: 'default' });
+      await authAdapter.setup(makeSetup());
+    });
+
+    afterEach(async () => {
+      if (authAdapter.isConnected()) await authAdapter.teardown();
+    });
+
+    it('rejects POST without Authorization header', async () => {
+      const { status } = await req(authPort, 'POST', '/api/message', JSON.stringify({ text: 'hi' }));
+      expect(status).toBe(401);
+    });
+
+    it('rejects POST with wrong token', async () => {
+      const { status } = await req(authPort, 'POST', '/api/message', JSON.stringify({ text: 'hi' }), {
+        Authorization: 'Bearer wrong',
+      });
+      expect(status).toBe(401);
+    });
+
+    it('accepts POST with correct Bearer token', async () => {
+      const { status } = await req(authPort, 'POST', '/api/message', JSON.stringify({ text: 'hi' }), {
+        Authorization: 'Bearer secret',
+      });
+      expect(status).toBe(200);
+    });
+
+    it('rejects GET without Authorization header', async () => {
+      const { status } = await req(authPort, 'GET', '/api/messages?since=0');
+      expect(status).toBe(401);
+    });
+
+    it('accepts GET with correct Bearer token', async () => {
+      const { status } = await req(authPort, 'GET', '/api/messages?since=0', undefined, {
+        Authorization: 'Bearer secret',
+      });
+      expect(status).toBe(200);
+    });
+  });
+});

src/channels/emacs.ts

@@ -0,0 +1,186 @@
+/**
+ * Emacs channel adapter (v2) — native HTTP bridge.
+ *
+ * Stands up a localhost HTTP server that the nanoclaw.el client talks to:
+ *  - POST /api/message — user typed a message in Emacs; fire onInbound
+ *  - GET  /api/messages?since=<ms> — Emacs polls for agent replies
+ *
+ * Single-user, single-chat: one adapter instance = one messaging group with
+ * `platform_id = "default"` (override with EMACS_PLATFORM_ID). No threads,
+ * no cold DM. Self-registers on import.
+ */
+import http from 'http';
+
+import { readEnvFile } from '../env.js';
+import { log } from '../log.js';
+import { registerChannelAdapter } from './channel-registry.js';
+import type { ChannelAdapter, ChannelSetup, InboundMessage, OutboundMessage } from './adapter.js';
+
+const OUTBOUND_BUFFER_MAX = 200;
+
+interface BufferedMessage {
+  text: string;
+  timestamp: number;
+}
+
+interface EmacsAdapterOptions {
+  port: number;
+  authToken: string | null;
+  platformId: string;
+}
+
+function createEmacsAdapter(opts: EmacsAdapterOptions): ChannelAdapter {
+  let server: http.Server | null = null;
+  let setupConfig: ChannelSetup | null = null;
+  const outboundBuffer: BufferedMessage[] = [];
+
+  function checkAuth(req: http.IncomingMessage, res: http.ServerResponse): boolean {
+    if (!opts.authToken) return true;
+    if (req.headers['authorization'] === `Bearer ${opts.authToken}`) return true;
+    res
+      .writeHead(401, { 'Content-Type': 'application/json; charset=utf-8' })
+      .end(JSON.stringify({ error: 'Unauthorized' }));
+    return false;
+  }
+
+  function handlePost(req: http.IncomingMessage, res: http.ServerResponse): void {
+    let body = '';
+    req.on('data', (chunk) => (body += chunk));
+    req.on('end', () => {
+      let text: string;
+      try {
+        const parsed = JSON.parse(body) as { text?: string };
+        text = parsed.text ?? '';
+      } catch {
+        res
+          .writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' })
+          .end(JSON.stringify({ error: 'Invalid JSON' }));
+        return;
+      }
+
+      if (!text.trim()) {
+        res
+          .writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' })
+          .end(JSON.stringify({ error: 'text required' }));
+        return;
+      }
+
+      const timestamp = new Date().toISOString();
+      const id = `emacs-${Date.now()}`;
+
+      const inbound: InboundMessage = {
+        id,
+        kind: 'chat',
+        content: {
+          text,
+          sender: 'Emacs',
+          senderId: `emacs:${opts.platformId}`,
+        },
+        timestamp,
+      };
+
+      try {
+        setupConfig?.onInbound(opts.platformId, null, inbound);
+      } catch (err) {
+        log.error('Emacs onInbound failed', { err });
+      }
+
+      res
+        .writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' })
+        .end(JSON.stringify({ messageId: id, timestamp: Date.now() }));
+    });
+  }
+
+  function handlePoll(url: URL, res: http.ServerResponse): void {
+    const since = parseInt(url.searchParams.get('since') ?? '0', 10);
+    const messages = outboundBuffer.filter((m) => m.timestamp > since);
+    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' }).end(JSON.stringify({ messages }));
+  }
+
+  return {
+    name: 'emacs',
+    channelType: 'emacs',
+    supportsThreads: false,
+
+    async setup(config: ChannelSetup): Promise<void> {
+      setupConfig = config;
+
+      server = http.createServer((req, res) => {
+        if (!checkAuth(req, res)) return;
+
+        const url = new URL(req.url ?? '/', `http://localhost:${opts.port}`);
+        if (req.method === 'POST' && url.pathname === '/api/message') {
+          handlePost(req, res);
+        } else if (req.method === 'GET' && url.pathname === '/api/messages') {
+          handlePoll(url, res);
+        } else {
+          res
+            .writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' })
+            .end(JSON.stringify({ error: 'Not found' }));
+        }
+      });
+
+      await new Promise<void>((resolve, reject) => {
+        server!.once('error', reject);
+        server!.listen(opts.port, '127.0.0.1', () => {
+          log.info('Emacs channel listening', { port: opts.port, platformId: opts.platformId });
+          resolve();
+        });
+      });
+
+      // Stamp a human-readable name on the messaging_groups row on first boot.
+      config.onMetadata(opts.platformId, 'Emacs', false);
+    },
+
+    async teardown(): Promise<void> {
+      if (!server) return;
+      await new Promise<void>((resolve) => server!.close(() => resolve()));
+      server = null;
+      log.info('Emacs channel stopped');
+    },
+
+    isConnected(): boolean {
+      return server?.listening ?? false;
+    },
+
+    async deliver(platformId: string, _threadId: string | null, message: OutboundMessage): Promise<string | undefined> {
+      if (platformId !== opts.platformId) {
+        log.warn('Emacs deliver called with unknown platformId', { platformId });
+        return undefined;
+      }
+      const text = extractText(message.content);
+      if (!text) return undefined;
+
+      const id = `emacs-out-${Date.now()}`;
+      outboundBuffer.push({ text, timestamp: Date.now() });
+      while (outboundBuffer.length > OUTBOUND_BUFFER_MAX) outboundBuffer.shift();
+      return id;
+    },
+  };
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (content && typeof content === 'object') {
+    const c = content as { text?: unknown };
+    if (typeof c.text === 'string') return c.text;
+  }
+  return '';
+}
+
+registerChannelAdapter('emacs', {
+  factory: () => {
+    const env = readEnvFile(['EMACS_ENABLED', 'EMACS_CHANNEL_PORT', 'EMACS_AUTH_TOKEN', 'EMACS_PLATFORM_ID']);
+    const enabled = process.env.EMACS_ENABLED || env.EMACS_ENABLED;
+    if (!enabled || enabled === 'false') return null;
+
+    const portStr = process.env.EMACS_CHANNEL_PORT || env.EMACS_CHANNEL_PORT || '8766';
+    const port = parseInt(portStr, 10);
+    const authToken = process.env.EMACS_AUTH_TOKEN || env.EMACS_AUTH_TOKEN || null;
+    const platformId = process.env.EMACS_PLATFORM_ID || env.EMACS_PLATFORM_ID || 'default';
+
+    return createEmacsAdapter({ port, authToken, platformId });
+  },
+});
+
+export { createEmacsAdapter };

src/channels/gchat-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the gchat channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs gchat.ts's
+ * top-level `registerChannelAdapter('gchat', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './gchat.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and gchat.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/gchat`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * gchat is a Chat SDK channel: gchat.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('gchat channel registration', () => {
+  it('registers gchat via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('gchat');
+  });
+});

src/channels/gchat.ts

@@ -0,0 +1,20 @@
+/**
+ * Google Chat channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createGoogleChatAdapter } from '@chat-adapter/gchat';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('gchat', {
+  factory: () => {
+    const env = readEnvFile(['GCHAT_CREDENTIALS']);
+    if (!env.GCHAT_CREDENTIALS) return null;
+    const gchatAdapter = createGoogleChatAdapter({
+      credentials: JSON.parse(env.GCHAT_CREDENTIALS),
+    });
+    return createChatSdkBridge({ adapter: gchatAdapter, concurrency: 'concurrent', supportsThreads: true });
+  },
+});

src/channels/github-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the github channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs github.ts's
+ * top-level `registerChannelAdapter('github', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './github.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and github.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/github`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * github is a Chat SDK channel: github.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('github channel registration', () => {
+  it('registers github via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('github');
+  });
+});

src/channels/github.ts

@@ -0,0 +1,23 @@
+/**
+ * GitHub channel adapter (v2) — uses Chat SDK bridge.
+ * PR comment threads as conversations.
+ * Self-registers on import.
+ */
+import { createGitHubAdapter } from '@chat-adapter/github';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('github', {
+  factory: () => {
+    const env = readEnvFile(['GITHUB_TOKEN', 'GITHUB_WEBHOOK_SECRET', 'GITHUB_BOT_USERNAME']);
+    if (!env.GITHUB_TOKEN) return null;
+    const githubAdapter = createGitHubAdapter({
+      token: env.GITHUB_TOKEN,
+      webhookSecret: env.GITHUB_WEBHOOK_SECRET,
+      userName: env.GITHUB_BOT_USERNAME,
+    });
+    return createChatSdkBridge({ adapter: githubAdapter, concurrency: 'queue', supportsThreads: true });
+  },
+});

src/channels/imessage-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the imessage channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs imessage.ts's
+ * top-level `registerChannelAdapter('imessage', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './imessage.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and imessage.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`chat-adapter-imessage`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * imessage is a Chat SDK channel: imessage.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('imessage channel registration', () => {
+  it('registers imessage via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('imessage');
+  });
+});

src/channels/imessage.ts

@@ -0,0 +1,29 @@
+/**
+ * iMessage channel adapter (v2) — uses Chat SDK bridge.
+ * Supports local mode (macOS Full Disk Access) and remote mode (Photon API).
+ * Self-registers on import.
+ */
+import { createiMessageAdapter } from 'chat-adapter-imessage';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('imessage', {
+  factory: () => {
+    const env = readEnvFile(['IMESSAGE_ENABLED', 'IMESSAGE_LOCAL', 'IMESSAGE_SERVER_URL', 'IMESSAGE_API_KEY']);
+    const isLocal = env.IMESSAGE_LOCAL !== 'false';
+    if (isLocal && !env.IMESSAGE_ENABLED) return null;
+    if (!isLocal && !env.IMESSAGE_SERVER_URL) return null;
+    const rawAdapter = createiMessageAdapter({
+      local: isLocal,
+      serverUrl: env.IMESSAGE_SERVER_URL,
+      apiKey: env.IMESSAGE_API_KEY,
+    });
+    // Polyfill channelIdFromThreadId (community adapter doesn't implement it)
+    const imessageAdapter = Object.assign(rawAdapter, {
+      channelIdFromThreadId: (threadId: string) => threadId,
+    });
+    return createChatSdkBridge({ adapter: imessageAdapter, concurrency: 'concurrent', supportsThreads: false });
+  },
+});

src/channels/index.ts

@@ -1,9 +1,60 @@
 // Channel self-registration barrel.
 // Each import triggers the channel module's registerChannelAdapter() call.
 //
-// Main ships with one default channel — `cli`, the always-on local-terminal
-// channel. Other channel skills (/add-slack, /add-discord, /add-whatsapp,
-// ...) copy their module from the `channels` branch and append a
-// self-registration import below.
+// The `channels` branch keeps this file fully populated — it's the
+// fully-loaded, runnable branch. Individual `/add-<channel>` skills pull
+// single files from this branch onto a user's install, appending their
+// own import lines to a leaner barrel on main.
 
+// cli — default channel that ships with main (always on, no credentials).
 import './cli.js';
+
+// discord
+import './discord.js';
+
+// slack
+// import './slack.js';
+
+// telegram
+import './telegram.js';
+
+// github
+// import './github.js';
+
+// linear
+import './linear.js';
+
+// google chat
+// import './gchat.js';
+
+// microsoft teams
+// import './teams.js';
+
+// whatsapp cloud api
+// import './whatsapp-cloud.js';
+
+// resend (email)
+// import './resend.js';
+
+// matrix
+// import './matrix.js';
+
+// webex
+// import './webex.js';
+
+// imessage
+import './imessage.js';
+
+// gmail (native, no Chat SDK)
+
+// whatsapp (native, no Chat SDK)
+import './whatsapp.js';
+
+// signal (native, no Chat SDK — signal-cli TCP JSON-RPC daemon)
+// import './signal.js';
+
+// emacs (native HTTP bridge, no Chat SDK)
+// import './emacs.js';
+
+// deltachat (native, no Chat SDK)
+// import './deltachat.js'

src/channels/linear-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the linear channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs linear.ts's
+ * top-level `registerChannelAdapter('linear', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './linear.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and linear.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/linear`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * linear is a Chat SDK channel: linear.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('linear channel registration', () => {
+  it('registers linear via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('linear');
+  });
+});

src/channels/linear.ts

@@ -0,0 +1,45 @@
+/**
+ * Linear channel adapter (v2) — uses Chat SDK bridge.
+ * Issue comment threads as conversations.
+ * Self-registers on import.
+ *
+ * Linear OAuth apps can't be @-mentioned, so this adapter relies on the
+ * bridge's default onNewMessage catch-all to forward every comment.
+ */
+import { createLinearAdapter } from '@chat-adapter/linear';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('linear', {
+  factory: () => {
+    const env = readEnvFile([
+      'LINEAR_API_KEY',
+      'LINEAR_CLIENT_ID',
+      'LINEAR_CLIENT_SECRET',
+      'LINEAR_WEBHOOK_SECRET',
+      'LINEAR_BOT_USERNAME',
+      'LINEAR_TEAM_KEY',
+    ]);
+    if (!env.LINEAR_API_KEY && !env.LINEAR_CLIENT_ID) return null;
+
+    const auth = env.LINEAR_CLIENT_ID
+      ? { clientId: env.LINEAR_CLIENT_ID, clientSecret: env.LINEAR_CLIENT_SECRET }
+      : { apiKey: env.LINEAR_API_KEY };
+
+    const linearAdapter = createLinearAdapter({
+      ...auth,
+      webhookSecret: env.LINEAR_WEBHOOK_SECRET,
+      userName: env.LINEAR_BOT_USERNAME,
+    });
+
+    // Override channelIdFromThreadId to return a team-based channel ID.
+    // The upstream adapter returns per-issue UUIDs which creates a new
+    // messaging group for every issue. We want one group per team.
+    const teamKey = env.LINEAR_TEAM_KEY || 'default';
+    linearAdapter.channelIdFromThreadId = () => `linear:${teamKey}`;
+
+    return createChatSdkBridge({ adapter: linearAdapter, concurrency: 'queue', supportsThreads: true });
+  },
+});

src/channels/matrix-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the matrix channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs matrix.ts's
+ * top-level `registerChannelAdapter('matrix', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './matrix.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and matrix.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@beeper/chat-adapter-matrix`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * matrix is a Chat SDK channel: matrix.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('matrix channel registration', () => {
+  it('registers matrix via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('matrix');
+  });
+});

src/channels/matrix.ts

@@ -0,0 +1,206 @@
+/**
+ * Matrix channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ *
+ * Supports two auth methods (resolved by the adapter from env):
+ *   - Access token: MATRIX_ACCESS_TOKEN + MATRIX_USER_ID
+ *   - Password:     MATRIX_USERNAME + MATRIX_PASSWORD (+ optional MATRIX_USER_ID)
+ *
+ * Optional env vars:
+ *   MATRIX_BOT_USERNAME         — display name for the bot (default: "bot")
+ *   MATRIX_INVITE_AUTOJOIN      — "true" to auto-accept room invites
+ *   MATRIX_INVITE_AUTOJOIN_ALLOWLIST — comma-separated user IDs allowed to invite
+ *   MATRIX_RECOVERY_KEY         — enable E2EE cross-signing
+ *   MATRIX_DEVICE_ID            — stable device ID across restarts
+ */
+import { createMatrixAdapter } from '@beeper/chat-adapter-matrix';
+
+import { log } from '../log.js';
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+const ENV_KEYS = [
+  'MATRIX_BASE_URL',
+  'MATRIX_ACCESS_TOKEN',
+  'MATRIX_USERNAME',
+  'MATRIX_PASSWORD',
+  'MATRIX_USER_ID',
+  'MATRIX_BOT_USERNAME',
+  'MATRIX_DEVICE_ID',
+  'MATRIX_RECOVERY_KEY',
+  'MATRIX_INVITE_AUTOJOIN',
+  'MATRIX_INVITE_AUTOJOIN_ALLOWLIST',
+] as const;
+
+/**
+ * Wrap the Matrix adapter so DM conversations are identified by user handle
+ * across the whole system, not by ephemeral room IDs.
+ *
+ * Matrix DMs live in rooms (e.g. "!abc:server"), but NanoClaw identifies
+ * channels by platform_id. Using a user handle as platform_id means both
+ * the user and the messaging group reference the same stable identifier.
+ *
+ * Two directions to bridge:
+ *   - Outbound: delivery passes "matrix:@user:server" → resolve to room via openDM
+ *   - Inbound: adapter emits "matrix:!room:server" → rewrite to user handle
+ *     so the router finds the existing messaging group instead of creating
+ *     a new one.
+ *
+ * Both resolutions are cached for the process lifetime.
+ */
+function wrapWithDmResolution(adapter: ReturnType<typeof createMatrixAdapter>): typeof adapter {
+  const origPostMessage = adapter.postMessage.bind(adapter);
+  const origStartTyping = adapter.startTyping.bind(adapter);
+  const origChannelIdFromThreadId = adapter.channelIdFromThreadId.bind(adapter);
+
+  // roomId → user handle, used to rewrite inbound channel IDs.
+  const roomToUserCache = new Map<string, string>();
+
+  function isUserHandle(threadId: string): boolean {
+    try {
+      const { roomID } = adapter.decodeThreadId(threadId);
+      return !roomID.startsWith('!');
+    } catch {
+      return true;
+    }
+  }
+
+  async function resolveThreadId(threadId: string): Promise<string> {
+    if (!isUserHandle(threadId)) return threadId;
+
+    const userHandle = threadId.startsWith('matrix:') ? threadId.slice('matrix:'.length) : threadId;
+    log.info('Matrix: resolving DM room for user handle', { userHandle });
+    const resolved = await adapter.openDM(userHandle);
+
+    try {
+      const { roomID } = adapter.decodeThreadId(resolved);
+      roomToUserCache.set(roomID, userHandle);
+    } catch {
+      // decode failure is non-fatal — outbound still works
+    }
+
+    return resolved;
+  }
+
+  // Rewrite inbound room-based channel IDs to user-handle form for DM rooms.
+  // Non-DM rooms pass through unchanged.
+  adapter.channelIdFromThreadId = (threadId: string): string => {
+    try {
+      const { roomID } = adapter.decodeThreadId(threadId);
+      if (!roomID.startsWith('!')) return origChannelIdFromThreadId(threadId);
+
+      const cached = roomToUserCache.get(roomID);
+      if (cached) return `matrix:${cached}`;
+
+      // Not cached — check if this is a DM by membership count
+      const client = (adapter as any).client;
+      const room = client?.getRoom(roomID);
+      if (!room) return origChannelIdFromThreadId(threadId);
+      if (room.getJoinedMemberCount() > 2) return origChannelIdFromThreadId(threadId);
+
+      const botId = (adapter as any).userID;
+      const otherMember = room.getJoinedMembers().find((m: { userId: string }) => m.userId !== botId);
+      if (!otherMember) return origChannelIdFromThreadId(threadId);
+
+      roomToUserCache.set(roomID, otherMember.userId);
+      return `matrix:${otherMember.userId}`;
+    } catch {
+      return origChannelIdFromThreadId(threadId);
+    }
+  };
+
+  // The Chat SDK calls adapter.isDM(threadId) synchronously to decide whether
+  // to dispatch to onDirectMessage handlers. The Matrix adapter doesn't expose
+  // this method — it only has an async isDirectRoom(). We add a synchronous
+  // isDM that checks room membership count: 2 members = DM.
+  (adapter as any).isDM = (threadId: string): boolean => {
+    try {
+      const { roomID } = adapter.decodeThreadId(threadId);
+      const client = (adapter as any).client;
+      if (!client) return false;
+      const room = client.getRoom(roomID);
+      if (!room) return false;
+      const members = room.getJoinedMemberCount();
+      return members <= 2;
+    } catch {
+      return false;
+    }
+  };
+
+  adapter.postMessage = async (
+    threadId: string,
+    ...args: Parameters<typeof origPostMessage> extends [string, ...infer R] ? R : never
+  ) => {
+    const resolvedTid = await resolveThreadId(threadId);
+    return origPostMessage(resolvedTid, ...args);
+  };
+
+  adapter.startTyping = async (threadId: string) => {
+    const resolvedTid = await resolveThreadId(threadId);
+    return origStartTyping(resolvedTid);
+  };
+
+  return adapter;
+}
+
+registerChannelAdapter('matrix', {
+  factory: () => {
+    const env = readEnvFile([...ENV_KEYS]);
+    if (!env.MATRIX_BASE_URL) return null;
+    if (!env.MATRIX_ACCESS_TOKEN && !(env.MATRIX_USERNAME && env.MATRIX_PASSWORD)) return null;
+
+    for (const key of ENV_KEYS) {
+      if (env[key]) process.env[key] = env[key];
+    }
+
+    // Default: auto-join room invites so DMs work without manual acceptance
+    if (!process.env.MATRIX_INVITE_AUTOJOIN) {
+      process.env.MATRIX_INVITE_AUTOJOIN = 'true';
+    }
+
+    const matrixAdapter = wrapWithDmResolution(createMatrixAdapter());
+    const bridge = createChatSdkBridge({ adapter: matrixAdapter, concurrency: 'concurrent', supportsThreads: false });
+
+    // Matrix user IDs contain ":" (e.g. "@user:matrix.org") which the shared
+    // permissions module interprets as already-prefixed. Wrap onInbound to
+    // ensure senderId always carries the "matrix:" channel prefix so user
+    // records match between init-first-agent and inbound routing.
+    const origSetup = bridge.setup.bind(bridge);
+    bridge.setup = async (hostConfig) => {
+      const origOnInbound = hostConfig.onInbound.bind(hostConfig);
+      await origSetup({
+        ...hostConfig,
+        onInbound: (platformId, threadId, message) => {
+          if (message.content && typeof message.content === 'object') {
+            const content = message.content as Record<string, unknown>;
+            if (typeof content.senderId === 'string' && !content.senderId.startsWith('matrix:')) {
+              content.senderId = `matrix:${content.senderId}`;
+            }
+          }
+          return origOnInbound(platformId, threadId, message);
+        },
+      });
+
+      // Wait for Matrix sync to reach PREPARED state before returning from setup.
+      // Without this, the host's delivery poll and sweep timer start immediately
+      // and can starve the SDK's sync generator microtask queue, blocking
+      // incremental syncs so new inbound messages never get dispatched.
+      await new Promise<void>((resolve) => {
+        const check = setInterval(() => {
+          if ((matrixAdapter as unknown as { liveSyncReady?: boolean }).liveSyncReady) {
+            log.info('Matrix sync ready');
+            clearInterval(check);
+            resolve();
+          }
+        }, 500);
+        setTimeout(() => {
+          clearInterval(check);
+          resolve();
+        }, 30_000);
+      });
+    };
+
+    return bridge;
+  },
+});

src/channels/resend-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the resend channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs resend.ts's
+ * top-level `registerChannelAdapter('resend', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './resend.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and resend.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@resend/chat-sdk-adapter`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * resend is a Chat SDK channel: resend.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('resend channel registration', () => {
+  it('registers resend via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('resend');
+  });
+});

src/channels/resend.ts

@@ -0,0 +1,23 @@
+/**
+ * Resend (email) channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createResendAdapter } from '@resend/chat-sdk-adapter';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('resend', {
+  factory: () => {
+    const env = readEnvFile(['RESEND_API_KEY', 'RESEND_FROM_ADDRESS', 'RESEND_FROM_NAME', 'RESEND_WEBHOOK_SECRET']);
+    if (!env.RESEND_API_KEY) return null;
+    const resendAdapter = createResendAdapter({
+      apiKey: env.RESEND_API_KEY,
+      fromAddress: env.RESEND_FROM_ADDRESS,
+      fromName: env.RESEND_FROM_NAME,
+      webhookSecret: env.RESEND_WEBHOOK_SECRET,
+    });
+    return createChatSdkBridge({ adapter: resendAdapter, concurrency: 'queue', supportsThreads: false });
+  },
+});

src/channels/signal-registration.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Integration test for the signal channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs signal.ts's
+ * top-level `registerChannelAdapter('signal', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './signal.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * signal is a native adapter with no npm dependency (it drives the external signal-cli binary over a local TCP socket); it talks to signal-cli.
+ * Importing the barrel is safe: registration is a pure top-level call and signal.ts
+ * opens connections / spawns subprocesses only inside setup() (run at host startup),
+ * never at import. There is no adapter package to guard here — this test guards the
+ * one barrel reach-in (red if `import './signal.js';` is deleted or the barrel fails
+ * to evaluate).
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('signal channel registration', () => {
+  it('registers signal via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('signal');
+  });
+});

src/channels/signal.test.ts

@@ -0,0 +1,961 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+
+// --- Mocks ---
+
+vi.mock('./channel-registry.js', () => ({ registerChannelAdapter: vi.fn() }));
+vi.mock('../env.js', () => ({ readEnvFile: vi.fn(() => ({})) }));
+vi.mock('../log.js', () => ({
+  log: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+vi.mock('node:child_process', () => ({
+  spawn: vi.fn(),
+  execFileSync: vi.fn(),
+}));
+
+// --- TCP socket mock ---
+
+import { EventEmitter } from 'events';
+
+const tcpRef = vi.hoisted(() => ({
+  rpcResponses: new Map<string, unknown>(),
+  fakeSocket: null as any,
+}));
+
+function createFakeSocket(): EventEmitter & {
+  write: ReturnType<typeof vi.fn>;
+  destroy: ReturnType<typeof vi.fn>;
+  destroyed: boolean;
+} {
+  const sock = new EventEmitter() as any;
+  sock.destroyed = false;
+  sock.destroy = vi.fn(() => {
+    sock.destroyed = true;
+    sock.emit('close');
+  });
+  sock.write = vi.fn((data: string) => {
+    try {
+      const req = JSON.parse(data.trim());
+      const result = tcpRef.rpcResponses.get(req.method) ?? { ok: true };
+      const response = JSON.stringify({ jsonrpc: '2.0', id: req.id, result }) + '\n';
+      setImmediate(() => sock.emit('data', Buffer.from(response)));
+    } catch {
+      /* ignore */
+    }
+  });
+  return sock;
+}
+
+vi.mock('node:net', () => ({
+  createConnection: vi.fn((_port: number, _host: string, cb?: () => void) => {
+    const sock = createFakeSocket();
+    tcpRef.fakeSocket = sock;
+    if (cb) setImmediate(cb);
+    return sock;
+  }),
+}));
+
+import type { ChannelSetup } from './adapter.js';
+import { createSignalAdapter } from './signal.js';
+
+// --- Test helpers ---
+
+function createMockSetup() {
+  return {
+    onInbound: vi.fn() as unknown as ChannelSetup['onInbound'] & ReturnType<typeof vi.fn>,
+    onInboundEvent: vi.fn() as unknown as ChannelSetup['onInboundEvent'] & ReturnType<typeof vi.fn>,
+    onMetadata: vi.fn() as unknown as ChannelSetup['onMetadata'] & ReturnType<typeof vi.fn>,
+    onAction: vi.fn() as unknown as ChannelSetup['onAction'] & ReturnType<typeof vi.fn>,
+  };
+}
+
+function createAdapter() {
+  return createSignalAdapter({
+    cliPath: 'signal-cli',
+    account: '+15551234567',
+    tcpHost: '127.0.0.1',
+    tcpPort: 7583,
+    manageDaemon: false,
+    signalDataDir: '/tmp/signal-cli-test-data',
+  });
+}
+
+function getRpcCalls(): Array<{
+  method: string;
+  params: Record<string, unknown>;
+  id: string;
+}> {
+  if (!tcpRef.fakeSocket) return [];
+  return tcpRef.fakeSocket.write.mock.calls
+    .map((c: any[]) => {
+      try {
+        return JSON.parse(c[0].trim());
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function getRpcCallsForMethod(method: string) {
+  return getRpcCalls().filter((c) => c.method === method);
+}
+
+function pushEvent(envelope: Record<string, unknown>) {
+  if (!tcpRef.fakeSocket) throw new Error('TCP socket not connected');
+  const notification =
+    JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'receive',
+      params: { envelope },
+    }) + '\n';
+  tcpRef.fakeSocket.emit('data', Buffer.from(notification));
+}
+
+// --- Tests ---
+
+describe('SignalAdapter', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tcpRef.rpcResponses.clear();
+    tcpRef.fakeSocket = null;
+    tcpRef.rpcResponses.set('send', { timestamp: 1234567890 });
+    tcpRef.rpcResponses.set('sendTyping', {});
+  });
+
+  afterEach(() => {
+    try {
+      tcpRef.fakeSocket?.destroy();
+    } catch {
+      // already closed
+    }
+  });
+
+  // --- Connection lifecycle ---
+
+  describe('connection lifecycle', () => {
+    it('connects when daemon is reachable', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      expect(adapter.isConnected()).toBe(true);
+      expect(tcpRef.fakeSocket).not.toBeNull();
+
+      await adapter.teardown();
+    });
+
+    it('isConnected() returns false before setup', () => {
+      const adapter = createAdapter();
+      expect(adapter.isConnected()).toBe(false);
+    });
+
+    it('disconnects cleanly', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      expect(adapter.isConnected()).toBe(true);
+
+      await adapter.teardown();
+      expect(adapter.isConnected()).toBe(false);
+    });
+
+    it('throws NetworkError if daemon is unreachable', async () => {
+      const { createConnection } = await import('node:net');
+      vi.mocked(createConnection).mockImplementationOnce((...args: any[]) => {
+        const sock = createFakeSocket();
+        setImmediate(() => sock.emit('error', new Error('Connection refused')));
+        return sock as any;
+      });
+
+      const adapter = createAdapter();
+      await expect(adapter.setup(createMockSetup())).rejects.toThrow(/not reachable/);
+    });
+  });
+
+  // --- Inbound message handling ---
+
+  describe('inbound message handling', () => {
+    it('delivers DM via onInbound', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        sourceName: 'Alice',
+        dataMessage: {
+          timestamp: 1700000000000,
+          message: 'Hello from Signal',
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(cfg.onMetadata).toHaveBeenCalledWith('+15555550123', 'Alice', false);
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        '+15555550123',
+        null,
+        expect.objectContaining({
+          id: '1700000000000',
+          kind: 'chat',
+          content: expect.objectContaining({
+            text: 'Hello from Signal',
+            sender: '+15555550123',
+            senderName: 'Alice',
+          }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+
+    it('delivers group message with group platformId', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550999',
+        sourceName: 'Bob',
+        dataMessage: {
+          timestamp: 1700000000000,
+          message: 'Group hello',
+          groupInfo: { groupId: 'abc123', groupName: 'Family' },
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(cfg.onMetadata).toHaveBeenCalledWith('group:abc123', 'Family', true);
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        'group:abc123',
+        null,
+        expect.objectContaining({
+          content: expect.objectContaining({
+            text: 'Group hello',
+            sender: '+15555550999',
+          }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+
+    it('skips sync messages (own outbound)', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15551234567',
+        syncMessage: {
+          sentMessage: {
+            timestamp: 1700000000000,
+            message: 'My own message',
+            destination: '+15555550123',
+          },
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).not.toHaveBeenCalled();
+
+      await adapter.teardown();
+    });
+
+    it('processes Note to Self sync messages as inbound', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15551234567',
+        syncMessage: {
+          sentMessage: {
+            timestamp: 1700000000000,
+            message: 'Hello Bee',
+            destinationNumber: '+15551234567',
+          },
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        '+15551234567',
+        null,
+        expect.objectContaining({
+          content: expect.objectContaining({
+            text: 'Hello Bee',
+            senderName: 'Me',
+            isFromMe: true,
+          }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+
+    it('skips empty messages', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        dataMessage: { timestamp: 1700000000000, message: '   ' },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).not.toHaveBeenCalled();
+
+      await adapter.teardown();
+    });
+
+    it('skips echoed outbound messages', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Echo test' },
+      });
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        dataMessage: { timestamp: 1700000000000, message: 'Echo test' },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).not.toHaveBeenCalled();
+
+      await adapter.teardown();
+    });
+
+    it('forwards image attachments as [Image: <path>] plus structured attachments array', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        sourceName: 'Alice',
+        dataMessage: {
+          timestamp: 1700000000000,
+          attachments: [{ id: 'att123abc', contentType: 'image/jpeg', size: 50000 }],
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        '+15555550123',
+        null,
+        expect.objectContaining({
+          content: expect.objectContaining({
+            text: expect.stringMatching(/^\[Image: .+att123abc\]$/),
+            attachments: [expect.objectContaining({ contentType: 'image/jpeg' })],
+          }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- groupV2 ---
+
+  describe('group routing', () => {
+    it('routes to groupV2.id when present, falling back to legacy groupInfo.groupId', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        sourceName: 'Alice',
+        dataMessage: {
+          timestamp: 1700000000000,
+          message: 'hello v2',
+          groupV2: { id: 'v2group=' },
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).toHaveBeenCalledWith('group:v2group=', null, expect.anything());
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- mention resolution ---
+
+  describe('mention resolution', () => {
+    it('replaces inline mention placeholders with display names', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        sourceName: 'Alice',
+        dataMessage: {
+          timestamp: 1700000000000,
+          message: 'hey  are you here?',
+          mentions: [{ start: 4, length: 1, name: 'Bob', uuid: 'bob-uuid' }],
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        '+15555550123',
+        null,
+        expect.objectContaining({
+          content: expect.objectContaining({ text: 'hey @Bob are you here?' }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- Quote context ---
+
+  describe('quote context', () => {
+    it('emits a nested replyTo object matching the formatter contract', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        sourceName: 'Alice',
+        dataMessage: {
+          timestamp: 1700000000000,
+          message: 'I disagree',
+          quote: {
+            id: 1699999999000,
+            authorNumber: '+15555550888',
+            authorName: 'Pineapple Pete',
+            text: 'Pineapple belongs on pizza',
+          },
+        },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        '+15555550123',
+        null,
+        expect.objectContaining({
+          content: expect.objectContaining({
+            text: 'I disagree',
+            replyTo: {
+              id: '1699999999000',
+              sender: 'Pineapple Pete',
+              text: 'Pineapple belongs on pizza',
+            },
+          }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- deliver ---
+
+  describe('deliver', () => {
+    it('sends DM via TCP RPC', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Hello' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls.length).toBeGreaterThan(0);
+
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params).toEqual(
+        expect.objectContaining({
+          recipient: ['+15555550123'],
+          message: 'Hello',
+          account: '+15551234567',
+        }),
+      );
+
+      await adapter.teardown();
+    });
+
+    it('sends group message via groupId', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      await adapter.deliver('group:abc123', null, {
+        kind: 'text',
+        content: { text: 'Group msg' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params).toEqual(
+        expect.objectContaining({
+          groupId: 'abc123',
+          message: 'Group msg',
+        }),
+      );
+
+      await adapter.teardown();
+    });
+
+    it('chunks long messages', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      const longText = 'x'.repeat(5000);
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: longText },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls.length).toBeGreaterThan(1);
+
+      await adapter.teardown();
+    });
+
+    it('extracts text from string content', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: 'Plain string content',
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls.length).toBeGreaterThan(0);
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('Plain string content');
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- Outbound attachments ---
+
+  describe('deliver — attachments', () => {
+    // Real fs writes happen in tmpdir(); confirm the bytes round-trip and
+    // are cleaned up after deliver returns.
+    it('sends a single attachment via attachments[] param', async () => {
+      const fs = await import('node:fs');
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'file',
+        content: {},
+        files: [{ filename: 'report.md', data: Buffer.from('# Report\n\nbody') }],
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls.length).toBe(1);
+      const params = sendCalls[0].params as Record<string, unknown>;
+      expect(params.recipient).toEqual(['+15555550123']);
+      expect(params.account).toBe('+15551234567');
+      expect(params.message).toBeUndefined();
+      const paths = params.attachments as string[];
+      expect(paths).toHaveLength(1);
+      expect(paths[0]).toMatch(/signal-out-\d+-[a-z0-9]+-report\.md$/);
+      // Temp file should no longer exist — finally{} cleanup ran
+      expect(fs.existsSync(paths[0])).toBe(false);
+
+      await adapter.teardown();
+    });
+
+    it('sends text first, then attachment, when both are present', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'file',
+        content: { text: 'Here is the digest' },
+        files: [{ filename: 'digest.md', data: Buffer.from('content') }],
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls).toHaveLength(2);
+      // First call: text message
+      expect(sendCalls[0].params).toEqual(
+        expect.objectContaining({ message: 'Here is the digest', recipient: ['+15555550123'] }),
+      );
+      expect((sendCalls[0].params as Record<string, unknown>).attachments).toBeUndefined();
+      // Second call: attachment, no message
+      expect(sendCalls[1].params).toEqual(
+        expect.objectContaining({ recipient: ['+15555550123'] }),
+      );
+      const attachments = (sendCalls[1].params as Record<string, unknown>).attachments as string[];
+      expect(attachments).toHaveLength(1);
+
+      await adapter.teardown();
+    });
+
+    it('sends multiple attachments in a single send call', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'file',
+        content: {},
+        files: [
+          { filename: 'a.txt', data: Buffer.from('a') },
+          { filename: 'b.png', data: Buffer.from([0x89, 0x50, 0x4e, 0x47]) },
+        ],
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls).toHaveLength(1);
+      const attachments = (sendCalls[0].params as Record<string, unknown>).attachments as string[];
+      expect(attachments).toHaveLength(2);
+      expect(attachments[0]).toMatch(/-a\.txt$/);
+      expect(attachments[1]).toMatch(/-b\.png$/);
+
+      await adapter.teardown();
+    });
+
+    it('uses groupId for group destinations', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('group:abc123', null, {
+        kind: 'file',
+        content: {},
+        files: [{ filename: 'pic.jpg', data: Buffer.from('jpg') }],
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls).toHaveLength(1);
+      const params = sendCalls[0].params as Record<string, unknown>;
+      expect(params.groupId).toBe('abc123');
+      expect(params.recipient).toBeUndefined();
+
+      await adapter.teardown();
+    });
+
+    /**
+     * Defensive test: `OutboundFile.filename` is operator-supplied data, so
+     * the implementation must not let a filename containing path separators
+     * escape the temp directory. We feed an attempt-to-traverse filename and
+     * assert the resolved path stays strictly inside `tmpdir()`.
+     */
+    it('keeps temp paths inside tmpdir even when filename contains path separators', async () => {
+      const path = await import('node:path');
+      const os = await import('node:os');
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'file',
+        content: {},
+        files: [{ filename: '../sneaky.txt', data: Buffer.from('x') }],
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const paths = (sendCalls[0].params as Record<string, unknown>).attachments as string[];
+      const resolvedTmp = path.resolve(os.tmpdir());
+      const resolvedResult = path.resolve(paths[0]);
+      // path.resolve normalizes away any "../"; if sanitization failed, the
+      // result would resolve to tmpdir's parent.
+      expect(resolvedResult.startsWith(resolvedTmp + path.sep)).toBe(true);
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- Text styles ---
+
+  describe('text styles', () => {
+    it('sends bold text with textStyle parameter', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Hello **world**' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls.length).toBeGreaterThan(0);
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('Hello world');
+      expect(last.params.textStyle).toEqual(['6:5:BOLD']);
+
+      await adapter.teardown();
+    });
+
+    it('sends inline code with MONOSPACE style', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Run `npm test` now' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('Run npm test now');
+      expect(last.params.textStyle).toEqual(['4:8:MONOSPACE']);
+
+      await adapter.teardown();
+    });
+
+    it('sends plain text without textStyle', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'No formatting here' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('No formatting here');
+      expect(last.params.textStyle).toBeUndefined();
+
+      await adapter.teardown();
+    });
+
+    it('falls back to original markup when textStyle is rejected', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      let sendCount = 0;
+      tcpRef.fakeSocket.write.mockImplementation((data: string) => {
+        try {
+          const req = JSON.parse(data.trim());
+          if (req.method === 'send') {
+            sendCount++;
+            if (sendCount === 1) {
+              const response =
+                JSON.stringify({
+                  jsonrpc: '2.0',
+                  id: req.id,
+                  error: { message: 'Unknown parameter: textStyle' },
+                }) + '\n';
+              setImmediate(() => tcpRef.fakeSocket.emit('data', Buffer.from(response)));
+              return;
+            }
+          }
+          const response =
+            JSON.stringify({
+              jsonrpc: '2.0',
+              id: req.id,
+              result: { ok: true },
+            }) + '\n';
+          setImmediate(() => tcpRef.fakeSocket.emit('data', Buffer.from(response)));
+        } catch {
+          /* ignore */
+        }
+      });
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Hello **world**' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      expect(sendCalls.length).toBe(2);
+      expect(sendCalls[1].params.message).toBe('Hello **world**');
+      expect(sendCalls[1].params.textStyle).toBeUndefined();
+
+      await adapter.teardown();
+    });
+
+    it('tracks nested styles with correct offsets', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: '**bold with `code` inside**' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('bold with code inside');
+      // BOLD covers the full inner span, MONOSPACE points at "code" in the
+      // final plain text (offset 10, length 4) — not the intermediate text.
+      const styles = (last.params.textStyle as string[]).slice().sort();
+      expect(styles).toEqual(['0:21:BOLD', '10:4:MONOSPACE']);
+
+      await adapter.teardown();
+    });
+
+    it('maps *single-asterisk* to ITALIC', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Hello *world*' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('Hello world');
+      expect(last.params.textStyle).toEqual(['6:5:ITALIC']);
+
+      await adapter.teardown();
+    });
+
+    it('maps _underscore_ to ITALIC', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      tcpRef.fakeSocket.write.mockClear();
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'hey _there_' },
+      });
+
+      const sendCalls = getRpcCallsForMethod('send');
+      const last = sendCalls[sendCalls.length - 1];
+      expect(last.params.message).toBe('hey there');
+      expect(last.params.textStyle).toEqual(['4:5:ITALIC']);
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- Echo cache ---
+
+  describe('echo cache', () => {
+    it('does not drop same-text inbound from a different recipient', async () => {
+      // Bot sends "Hello" to Alice. Immediately after, Bob sends "Hello" from
+      // a different DM. Bob's message must still route — the earlier echo key
+      // was scoped to Alice.
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Hello' },
+      });
+
+      pushEvent({
+        sourceNumber: '+15555550999',
+        sourceName: 'Bob',
+        dataMessage: { timestamp: 1700000000000, message: 'Hello' },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).toHaveBeenCalledWith(
+        '+15555550999',
+        null,
+        expect.objectContaining({
+          content: expect.objectContaining({ text: 'Hello', sender: '+15555550999' }),
+        }),
+      );
+
+      await adapter.teardown();
+    });
+
+    it('still skips echo on the same recipient', async () => {
+      const adapter = createAdapter();
+      const cfg = createMockSetup();
+      await adapter.setup(cfg);
+
+      await adapter.deliver('+15555550123', null, {
+        kind: 'text',
+        content: { text: 'Echo test' },
+      });
+
+      pushEvent({
+        sourceNumber: '+15555550123',
+        dataMessage: { timestamp: 1700000000000, message: 'Echo test' },
+      });
+
+      await new Promise((r) => setTimeout(r, 50));
+      expect(cfg.onInbound).not.toHaveBeenCalled();
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- Connection drop ---
+
+  describe('connection drop', () => {
+    it('flips isConnected to false when the socket closes', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+      expect(adapter.isConnected()).toBe(true);
+
+      // Simulate the daemon dropping the TCP connection.
+      tcpRef.fakeSocket.destroy();
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(adapter.isConnected()).toBe(false);
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- setTyping ---
+
+  describe('setTyping', () => {
+    it('sends typing indicator for DMs', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      await adapter.setTyping!('+15555550123', null);
+
+      expect(getRpcCallsForMethod('sendTyping')).toHaveLength(1);
+
+      await adapter.teardown();
+    });
+
+    it('skips typing for groups', async () => {
+      const adapter = createAdapter();
+      await adapter.setup(createMockSetup());
+
+      await adapter.setTyping!('group:abc123', null);
+
+      expect(getRpcCallsForMethod('sendTyping')).toHaveLength(0);
+
+      await adapter.teardown();
+    });
+  });
+
+  // --- Adapter properties ---
+
+  describe('adapter properties', () => {
+    it('has channelType "signal"', () => {
+      const adapter = createAdapter();
+      expect(adapter.channelType).toBe('signal');
+    });
+
+    it('does not support threads', () => {
+      const adapter = createAdapter();
+      expect(adapter.supportsThreads).toBe(false);
+    });
+  });
+});

src/channels/signal.ts

@@ -0,0 +1,983 @@
+/**
+ * Signal channel adapter for NanoClaw v2.
+ *
+ * Uses signal-cli's TCP JSON-RPC daemon for bidirectional messaging.
+ * Requires signal-cli (https://github.com/AsamK/signal-cli) installed
+ * and a linked account.
+ *
+ * Ported from v1 — see v1 source for commit history.
+ */
+import { execFileSync, execSync, spawn } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createConnection, type Socket } from 'node:net';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { ChannelAdapter, ChannelSetup, InboundMessage, OutboundMessage } from './adapter.js';
+import { registerChannelAdapter } from './channel-registry.js';
+import { readEnvFile } from '../env.js';
+import { log } from '../log.js';
+
+// ---------------------------------------------------------------------------
+// Signal CLI daemon management
+// ---------------------------------------------------------------------------
+
+interface DaemonHandle {
+  stop: () => void;
+  exited: Promise<void>;
+  isExited: () => boolean;
+}
+
+function spawnSignalDaemon(cliPath: string, account: string, host: string, port: number): DaemonHandle {
+  const args: string[] = [];
+  if (account) args.push('-a', account);
+  args.push('daemon', '--tcp', `${host}:${port}`, '--no-receive-stdout');
+  args.push('--receive-mode', 'on-start');
+
+  const child = spawn(cliPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+  let exited = false;
+
+  const exitedPromise = new Promise<void>((resolve) => {
+    child.once('exit', (code, signal) => {
+      exited = true;
+      if (code !== 0 && code !== null) {
+        const reason = signal ? `signal ${signal}` : `code ${code}`;
+        log.error('signal-cli daemon exited', { reason });
+      }
+      resolve();
+    });
+    child.on('error', (err) => {
+      exited = true;
+      log.error('signal-cli spawn error', { err });
+      resolve();
+    });
+  });
+
+  child.stdout?.on('data', (data: Buffer) => {
+    for (const line of data.toString().split(/\r?\n/)) {
+      if (line.trim()) log.debug('signal-cli stdout', { line: line.trim() });
+    }
+  });
+  child.stderr?.on('data', (data: Buffer) => {
+    for (const line of data.toString().split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      if (/\b(ERROR|WARN|FAILED|SEVERE)\b/i.test(line)) {
+        log.warn('signal-cli stderr', { line: line.trim() });
+      } else {
+        log.debug('signal-cli stderr', { line: line.trim() });
+      }
+    }
+  });
+
+  return {
+    stop: () => {
+      if (!child.killed && !exited) child.kill('SIGTERM');
+    },
+    exited: exitedPromise,
+    isExited: () => exited,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// TCP JSON-RPC client for signal-cli daemon (--tcp mode)
+//
+// signal-cli 0.14.x --tcp exposes a newline-delimited JSON-RPC socket.
+// Requests are sent as JSON + newline; responses and push notifications
+// (inbound messages) arrive the same way.
+// ---------------------------------------------------------------------------
+
+const RPC_TIMEOUT_MS = 15_000;
+
+class SignalTcpClient {
+  private socket: Socket | null = null;
+  private buffer = '';
+  private pending = new Map<
+    string,
+    {
+      resolve: (value: unknown) => void;
+      reject: (err: Error) => void;
+      timer: ReturnType<typeof setTimeout>;
+    }
+  >();
+  private onNotification: ((method: string, params: unknown) => void) | null = null;
+  private onClose: (() => void) | null = null;
+
+  constructor(
+    private host: string,
+    private port: number,
+  ) {}
+
+  connect(handlers?: {
+    onNotification?: (method: string, params: unknown) => void;
+    onClose?: () => void;
+  }): Promise<void> {
+    this.onNotification = handlers?.onNotification ?? null;
+    this.onClose = handlers?.onClose ?? null;
+    return new Promise((resolve, reject) => {
+      const sock = createConnection(this.port, this.host, () => {
+        this.socket = sock;
+        resolve();
+      });
+      sock.on('error', (err) => {
+        if (!this.socket) {
+          reject(err);
+          return;
+        }
+        log.warn('Signal TCP socket error', { err });
+      });
+      sock.on('data', (chunk) => this.onData(chunk));
+      sock.on('close', () => {
+        const wasConnected = this.socket !== null;
+        this.socket = null;
+        for (const [, p] of this.pending) {
+          clearTimeout(p.timer);
+          p.reject(new Error('Signal TCP connection closed'));
+        }
+        this.pending.clear();
+        if (wasConnected) this.onClose?.();
+      });
+    });
+  }
+
+  async rpc<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T> {
+    if (!this.socket) throw new Error('Signal TCP not connected');
+    const id = Math.random().toString(36).slice(2);
+    const msg = JSON.stringify({ jsonrpc: '2.0', method, params, id }) + '\n';
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Signal RPC timeout: ${method}`));
+      }, RPC_TIMEOUT_MS);
+
+      this.pending.set(id, {
+        resolve: resolve as (v: unknown) => void,
+        reject,
+        timer,
+      });
+      this.socket!.write(msg);
+    });
+  }
+
+  close() {
+    this.socket?.destroy();
+    this.socket = null;
+  }
+
+  isConnected(): boolean {
+    return this.socket !== null && !this.socket.destroyed;
+  }
+
+  private onData(chunk: Buffer) {
+    this.buffer += chunk.toString();
+    let newlineIdx = this.buffer.indexOf('\n');
+    while (newlineIdx !== -1) {
+      const line = this.buffer.slice(0, newlineIdx).trim();
+      this.buffer = this.buffer.slice(newlineIdx + 1);
+      if (line) this.handleLine(line);
+      newlineIdx = this.buffer.indexOf('\n');
+    }
+  }
+
+  private handleLine(line: string) {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      log.debug('Signal TCP: unparseable line', { line: line.slice(0, 200) });
+      return;
+    }
+
+    if (parsed.id && this.pending.has(parsed.id)) {
+      const p = this.pending.get(parsed.id)!;
+      this.pending.delete(parsed.id);
+      clearTimeout(p.timer);
+      if (parsed.error) {
+        p.reject(new Error(parsed.error.message ?? 'Signal RPC error'));
+      } else {
+        p.resolve(parsed.result);
+      }
+      return;
+    }
+
+    if (parsed.method && this.onNotification) {
+      this.onNotification(parsed.method, parsed.params);
+    }
+  }
+}
+
+async function signalTcpCheck(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.destroy();
+      resolve(result);
+    };
+    const sock = createConnection(port, host, () => finish(true));
+    sock.on('error', () => finish(false));
+    const timer = setTimeout(() => finish(false), 5000);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Echo cache
+// ---------------------------------------------------------------------------
+
+const ECHO_TTL_MS = 10_000;
+
+/**
+ * Per-recipient dedup for messages we sent ourselves.
+ *
+ * signal-cli echoes our own outbound back via syncMessage (and, for Note to
+ * Self, via sentMessage-with-self-destination). Without dedup, the agent sees
+ * its own replies as new inbound and loops. We remember `(platformId, text)`
+ * briefly after every send, and drop the first match within TTL.
+ *
+ * Keying on text alone is not enough: if we send "hi" to Alice and Bob then
+ * sends "hi" from a different chat, Bob's real message gets silently dropped.
+ */
+class EchoCache {
+  private entries = new Map<string, number>();
+
+  private keyFor(platformId: string, text: string): string {
+    return `${platformId}\x00${text.trim()}`;
+  }
+
+  remember(platformId: string, text: string): void {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    this.entries.set(this.keyFor(platformId, trimmed), Date.now());
+    this.cleanup();
+  }
+
+  isEcho(platformId: string, text: string): boolean {
+    const trimmed = text.trim();
+    if (!trimmed) return false;
+    const key = this.keyFor(platformId, trimmed);
+    const ts = this.entries.get(key);
+    if (!ts) return false;
+    if (Date.now() - ts > ECHO_TTL_MS) {
+      this.entries.delete(key);
+      return false;
+    }
+    this.entries.delete(key);
+    return true;
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, ts] of this.entries) {
+      if (now - ts > ECHO_TTL_MS) this.entries.delete(key);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Signal envelope types
+// ---------------------------------------------------------------------------
+
+interface SignalQuote {
+  id?: number;
+  author?: string;
+  authorNumber?: string;
+  authorUuid?: string;
+  authorName?: string;
+  text?: string;
+}
+
+interface SignalMention {
+  start?: number;
+  length?: number;
+  uuid?: string;
+  number?: string;
+  name?: string;
+}
+
+interface SignalDataMessage {
+  timestamp?: number;
+  message?: string;
+  mentions?: SignalMention[];
+  groupInfo?: { groupId?: string; groupName?: string; type?: string };
+  groupV2?: { id?: string };
+  quote?: SignalQuote;
+  attachments?: Array<{
+    id?: string;
+    contentType?: string;
+    filename?: string;
+    size?: number;
+  }>;
+}
+
+interface SignalEnvelope {
+  source?: string;
+  sourceName?: string;
+  sourceNumber?: string;
+  sourceUuid?: string;
+  dataMessage?: SignalDataMessage;
+  syncMessage?: {
+    sentMessage?: SignalDataMessage & {
+      destination?: string;
+      destinationNumber?: string;
+    };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace inline `@<placeholder>` mention markers with display names so the
+ * agent sees `@Alice` instead of a raw UUID. Signal's protocol uses a single
+ * placeholder character (typically U+FFFC) at each mention's `start` offset.
+ */
+function resolveMentions(text: string, mentions?: SignalMention[]): string {
+  if (!mentions || mentions.length === 0) return text;
+  const sorted = [...mentions].sort((a, b) => (a.start ?? 0) - (b.start ?? 0));
+  let result = '';
+  let cursor = 0;
+  for (const m of sorted) {
+    const start = m.start ?? 0;
+    const length = m.length ?? 1;
+    const name = m.name || m.number || (m.uuid ? m.uuid.slice(0, 8) : 'someone');
+    if (start < cursor) continue;
+    result += text.slice(cursor, start) + `@${name}`;
+    cursor = start + length;
+  }
+  result += text.slice(cursor);
+  return result;
+}
+
+/**
+ * Optional voice-note transcription. Tries (in order):
+ *   1. local whisper.cpp CLI when `WHISPER_BIN` is set
+ *   2. OpenAI Whisper API when `OPENAI_API_KEY` is set
+ * Returns null if neither path is configured or transcription fails — caller
+ * falls back to a `[Voice Message]` placeholder.
+ *
+ * Signal voice notes are AAC/ADTS; whisper-cpp wants WAV. ffmpeg is invoked
+ * if available to convert; if ffmpeg is missing the local path is skipped.
+ */
+async function transcribeAudioOptional(filePath: string): Promise<string | null> {
+  const whisperBin = process.env.WHISPER_BIN;
+  if (whisperBin) {
+    try {
+      const wavPath = `${filePath}.wav`;
+      execSync(`ffmpeg -y -loglevel error -i "${filePath}" -ar 16000 -ac 1 "${wavPath}"`, { stdio: 'ignore' });
+      const model = process.env.WHISPER_MODEL || `${homedir()}/.local/share/whisper/models/ggml-base.en.bin`;
+      const out = execSync(`"${whisperBin}" -m "${model}" -f "${wavPath}" -nt -otxt -of "${wavPath}"`, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      try {
+        unlinkSync(wavPath);
+        unlinkSync(`${wavPath}.txt`);
+      } catch {}
+      const text = out.replace(/\[[^\]]*\]/g, '').trim();
+      if (text) return text;
+    } catch (err) {
+      log.debug('Signal: local whisper transcription failed, trying OpenAI', { err });
+    }
+  }
+
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (apiKey) {
+    try {
+      const buf = readFileSync(filePath);
+      const boundary = `----nanoclaw-${Date.now()}`;
+      const body = Buffer.concat([
+        Buffer.from(
+          `--${boundary}\r\nContent-Disposition: form-data; name="model"\r\n\r\nwhisper-1\r\n--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="audio.aac"\r\nContent-Type: audio/aac\r\n\r\n`,
+        ),
+        buf,
+        Buffer.from(`\r\n--${boundary}--\r\n`),
+      ]);
+      const res = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': `multipart/form-data; boundary=${boundary}`,
+        },
+        body,
+      });
+      if (res.ok) {
+        const json = (await res.json()) as { text?: string };
+        if (json.text) return json.text.trim();
+      }
+    } catch (err) {
+      log.debug('Signal: OpenAI transcription failed', { err });
+    }
+  }
+
+  return null;
+}
+
+function chunkText(text: string, limit: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= limit) {
+      chunks.push(remaining);
+      break;
+    }
+    let splitAt = remaining.lastIndexOf('\n', limit);
+    if (splitAt <= 0) splitAt = limit;
+    chunks.push(remaining.slice(0, splitAt));
+    remaining = remaining.slice(splitAt).replace(/^\n/, '');
+  }
+  return chunks;
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// ---------------------------------------------------------------------------
+// Signal text styles — convert Markdown to Signal's offset-based formatting
+// ---------------------------------------------------------------------------
+
+interface SignalTextStyle {
+  style: 'BOLD' | 'ITALIC' | 'STRIKETHROUGH' | 'MONOSPACE' | 'SPOILER';
+  start: number;
+  length: number;
+}
+
+interface StyledText {
+  text: string;
+  textStyles: SignalTextStyle[];
+}
+
+/**
+ * Convert Markdown-ish input to Signal's offset-based style ranges.
+ *
+ * Walks the input recursively: at each level we find the leftmost matching
+ * pattern, descend into its captured inner text (so `**bold with \`code\`
+ * inside**` stays bold-plus-monospace rather than leaking stripped markers),
+ * then continue past the match. Style offsets are recorded against the
+ * *output* text length as it's built, so nested styles always point at the
+ * right span of the final plain text.
+ */
+function parseSignalStyles(input: string): StyledText {
+  const styles: SignalTextStyle[] = [];
+
+  // Ordering matters: longer/greedier delimiters first so `` ``` `` beats
+  // `` ` ``, `**` beats `*`. The italic-`*` pattern refuses to start on
+  // whitespace so `*` isn't mistakenly opened on " * " in list-like text.
+  const patterns: Array<{ regex: RegExp; style: SignalTextStyle['style'] }> = [
+    { regex: /```([\s\S]+?)```/, style: 'MONOSPACE' },
+    { regex: /`([^`]+)`/, style: 'MONOSPACE' },
+    { regex: /\*\*([^]+?)\*\*/, style: 'BOLD' },
+    { regex: /~~([^]+?)~~/, style: 'STRIKETHROUGH' },
+    { regex: /\|\|([^]+?)\|\|/, style: 'SPOILER' },
+    { regex: /\*([^*\s][^*]*?)\*/, style: 'ITALIC' },
+    { regex: /_([^_\s][^_]*?)_/, style: 'ITALIC' },
+  ];
+
+  function walk(segment: string, outputBase: number): string {
+    let earliest: { start: number; match: RegExpExecArray; style: SignalTextStyle['style'] } | null = null;
+    for (const { regex, style } of patterns) {
+      const m = regex.exec(segment);
+      if (!m) continue;
+      if (earliest === null || m.index < earliest.start) {
+        earliest = { start: m.index, match: m, style };
+      }
+    }
+    if (!earliest) return segment;
+
+    const before = segment.slice(0, earliest.start);
+    const fullMatch = earliest.match[0];
+    const inner = earliest.match[1];
+    const afterStart = earliest.start + fullMatch.length;
+    const after = segment.slice(afterStart);
+
+    const innerOut = walk(inner, outputBase + before.length);
+    styles.push({
+      style: earliest.style,
+      start: outputBase + before.length,
+      length: innerOut.length,
+    });
+    const afterOut = walk(after, outputBase + before.length + innerOut.length);
+
+    return before + innerOut + afterOut;
+  }
+
+  const text = walk(input, 0);
+  return { text, textStyles: styles };
+}
+
+// ---------------------------------------------------------------------------
+// SignalAdapter — v2 ChannelAdapter implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Platform ID format:
+ *   DM:    phone number or UUID (e.g. "+15555550123")
+ *   Group: "group:<groupId>" (e.g. "group:abc123")
+ *
+ * channelType is always "signal". The router combines channelType + platformId
+ * to look up or create the messaging_group.
+ */
+export function createSignalAdapter(config: {
+  cliPath: string;
+  account: string;
+  tcpHost: string;
+  tcpPort: number;
+  manageDaemon: boolean;
+  signalDataDir: string;
+}): ChannelAdapter {
+  let daemon: DaemonHandle | null = null;
+  let tcp: SignalTcpClient | null = null;
+  let connected = false;
+  const echoCache = new EchoCache();
+  let setup: ChannelSetup | null = null;
+
+  // -- inbound handling --
+
+  function handleNotification(method: string, params: unknown): void {
+    if (method === 'receive') {
+      const envelope = (params as any)?.envelope;
+      if (envelope) {
+        handleEnvelope(envelope).catch((err) => {
+          log.error('Signal: error handling envelope', { err });
+        });
+      }
+    }
+  }
+
+  async function handleEnvelope(envelope: SignalEnvelope): Promise<void> {
+    if (!setup) return;
+
+    // Sync messages (sent from another device)
+    const syncSent = envelope.syncMessage?.sentMessage;
+    if (syncSent) {
+      const dest = (syncSent.destinationNumber ?? syncSent.destination ?? '').trim();
+      // "Note to Self" — destination is our own account
+      if (dest === config.account) {
+        const text = (syncSent.message ?? '').trim();
+        if (!text) return;
+        const platformId = config.account;
+        if (echoCache.isEcho(platformId, text)) return;
+        const timestamp = syncSent.timestamp ? new Date(syncSent.timestamp).toISOString() : new Date().toISOString();
+
+        setup.onMetadata(platformId, 'Note to Self', false);
+
+        const msg: InboundMessage = {
+          id: String(syncSent.timestamp ?? Date.now()),
+          kind: 'chat',
+          content: {
+            text,
+            sender: config.account,
+            senderId: `signal:${config.account}`,
+            senderName: 'Me',
+            isFromMe: true,
+            ...(syncSent.quote ? quoteToContent(syncSent.quote) : {}),
+          },
+          timestamp,
+        };
+        await setup.onInbound(platformId, null, msg);
+        return;
+      }
+      // Other sync messages are our outbound — skip
+      return;
+    }
+
+    const dataMessage = envelope.dataMessage;
+    if (!dataMessage) return;
+
+    const rawText = (dataMessage.message ?? '').trim();
+    const text = rawText ? resolveMentions(rawText, dataMessage.mentions) : '';
+
+    const audioAttachment = dataMessage.attachments?.find((a) => a.contentType?.startsWith('audio/') && a.id);
+    const imageAttachments = dataMessage.attachments?.filter((a) => a.contentType?.startsWith('image/') && a.id) ?? [];
+    const hasVoice = !text && !!audioAttachment;
+
+    if (!text && !hasVoice && imageAttachments.length === 0) return;
+
+    const sender = (envelope.sourceNumber ?? envelope.sourceUuid ?? envelope.source ?? '').trim();
+    if (!sender) return;
+
+    const senderName = (envelope.sourceName?.trim() || sender).trim();
+
+    // Modern Signal groups use groupV2; legacy groupInfo.groupId is the
+    // pre-V2 fallback. Without the V2 read, V2-only groups appear as DMs
+    // because `groupInfo` is undefined.
+    const groupInfo = dataMessage.groupInfo;
+    const groupId = dataMessage.groupV2?.id ?? groupInfo?.groupId;
+    const isGroup = Boolean(groupId);
+
+    const platformId = isGroup ? `group:${groupId}` : sender;
+
+    if (text && echoCache.isEcho(platformId, text)) {
+      log.debug('Signal: skipping echo', { platformId });
+      return;
+    }
+    const timestamp = dataMessage.timestamp ? new Date(dataMessage.timestamp).toISOString() : new Date().toISOString();
+
+    const chatName = groupInfo?.groupName ?? (isGroup ? `Group ${groupId?.slice(0, 8)}` : senderName);
+
+    setup.onMetadata(platformId, chatName, isGroup);
+
+    let content = text;
+
+    // Voice attachment — try transcription if WHISPER_BIN or OPENAI_API_KEY
+    // is configured; otherwise fall back to the original placeholder so
+    // operators who don't want transcription get the same UX as before.
+    if (hasVoice && audioAttachment?.id) {
+      const attachmentPath = join(config.signalDataDir, 'attachments', audioAttachment.id);
+      if (existsSync(attachmentPath)) {
+        log.info('Signal: voice attachment received', {
+          platformId,
+          attachmentId: audioAttachment.id,
+          path: attachmentPath,
+        });
+        const transcript = await transcribeAudioOptional(attachmentPath);
+        if (transcript) {
+          content = `[Voice: ${transcript}]`;
+          log.info('Signal: voice transcribed', { platformId, length: transcript.length });
+        } else {
+          content = '[Voice Message]';
+        }
+      } else {
+        log.warn('Signal: voice attachment file not found', {
+          id: audioAttachment.id,
+          path: attachmentPath,
+        });
+        content = '[Voice Message - file not found]';
+      }
+    }
+
+    // Image attachments — emit `[Image: <path>]` lines so the agent's Read
+    // tool can pick them up, and surface the structured `attachments` array
+    // for consumers that prefer that shape. Without this, vision-capable
+    // models never see images sent over Signal.
+    const attachmentRefs: Array<{ path: string; contentType: string }> = [];
+    for (const img of imageAttachments) {
+      const imagePath = join(config.signalDataDir, 'attachments', img.id!);
+      const imageLine = `[Image: ${imagePath}]`;
+      content = content ? `${content}\n${imageLine}` : imageLine;
+      attachmentRefs.push({ path: imagePath, contentType: img.contentType || 'image/jpeg' });
+    }
+
+    const msg: InboundMessage = {
+      id: String(dataMessage.timestamp ?? Date.now()),
+      kind: 'chat',
+      content: {
+        text: content,
+        sender,
+        senderId: `signal:${sender}`,
+        senderName,
+        ...(attachmentRefs.length > 0 ? { attachments: attachmentRefs } : {}),
+        ...(dataMessage.quote ? quoteToContent(dataMessage.quote) : {}),
+      },
+      timestamp,
+    };
+    await setup.onInbound(platformId, null, msg);
+
+    log.info('Signal message received', { platformId, sender: senderName });
+  }
+
+  /**
+   * Build the `replyTo` object the agent-runner formatter expects (see
+   * `container/agent-runner/src/formatter.ts:formatReplyContext`). The
+   * formatter requires both `sender` and `text` to render the
+   * `<quoted_message>` block; absent either, it omits the block entirely.
+   *
+   * The previous shape (`replyToSenderName` / `replyToMessageContent` /
+   * `replyToMessageId` flat keys) did not match the formatter contract, so
+   * quote-reply context was silently dropped end-to-end.
+   */
+  function quoteToContent(quote: SignalQuote): Record<string, unknown> {
+    const sender = quote.authorName || quote.authorNumber || quote.author || quote.authorUuid || 'someone';
+    const text = quote.text || '';
+    return {
+      replyTo: {
+        id: quote.id ? String(quote.id) : undefined,
+        sender,
+        text,
+      },
+    };
+  }
+
+  // -- send helpers --
+
+  async function sendText(platformId: string, text: string): Promise<void> {
+    if (!connected || !tcp) return;
+
+    echoCache.remember(platformId, text);
+
+    const MAX_CHUNK = 4000;
+    const chunks = text.length <= MAX_CHUNK ? [text] : chunkText(text, MAX_CHUNK);
+
+    for (const chunk of chunks) {
+      try {
+        const { text: plainText, textStyles } = parseSignalStyles(chunk);
+        const params: Record<string, unknown> = { message: plainText };
+        if (config.account) params.account = config.account;
+        if (textStyles.length > 0) {
+          params.textStyle = textStyles.map((s) => `${s.start}:${s.length}:${s.style}`);
+        }
+
+        if (platformId.startsWith('group:')) {
+          params.groupId = platformId.slice('group:'.length);
+        } else {
+          params.recipient = [platformId];
+        }
+
+        try {
+          await tcp.rpc('send', params);
+        } catch (styledErr) {
+          if (textStyles.length > 0) {
+            log.debug('Signal: textStyle rejected, retrying with markup');
+            delete params.textStyle;
+            params.message = chunk;
+            await tcp.rpc('send', params);
+          } else {
+            throw styledErr;
+          }
+        }
+      } catch (err) {
+        log.error('Signal: send failed', { platformId, err });
+      }
+    }
+
+    log.info('Signal message sent', { platformId, length: text.length });
+  }
+
+  /**
+   * Send one or more file attachments via signal-cli's `send` JSON-RPC, which
+   * accepts an `attachments` array of host filesystem paths. The OutboundFile
+   * Buffer is materialized to an OS temp file so signal-cli can read it, then
+   * removed in the finally block.
+   *
+   * Caption text, if any, is sent first via `sendText` (which handles chunking
+   * + textStyles) — keeps this function single-purpose and avoids a long
+   * caption colliding with signal-cli's per-message size limits.
+   */
+  async function sendAttachments(platformId: string, files: { filename: string; data: Buffer }[]): Promise<void> {
+    if (!connected || !tcp) return;
+    if (files.length === 0) return;
+
+    const tempPaths: string[] = [];
+    for (const file of files) {
+      const safeName = file.filename.replace(/[/\\\0]/g, '_');
+      const tempPath = join(tmpdir(), `signal-out-${Date.now()}-${Math.random().toString(36).slice(2, 8)}-${safeName}`);
+      writeFileSync(tempPath, file.data);
+      tempPaths.push(tempPath);
+    }
+
+    try {
+      const params: Record<string, unknown> = { attachments: tempPaths };
+      if (config.account) params.account = config.account;
+      if (platformId.startsWith('group:')) {
+        params.groupId = platformId.slice('group:'.length);
+      } else {
+        params.recipient = [platformId];
+      }
+      await tcp.rpc('send', params);
+      log.info('Signal attachments sent', { platformId, count: files.length, filenames: files.map((f) => f.filename) });
+    } catch (err) {
+      log.error('Signal: attachment send failed', { platformId, count: files.length, err });
+    } finally {
+      for (const p of tempPaths) {
+        try {
+          unlinkSync(p);
+        } catch {
+          /* best-effort cleanup */
+        }
+      }
+    }
+  }
+
+  async function waitForDaemon(): Promise<boolean> {
+    const maxWait = 30_000;
+    const pollInterval = 1000;
+    const start = Date.now();
+
+    while (Date.now() - start < maxWait) {
+      if (daemon?.isExited()) return false;
+      const ok = await signalTcpCheck(config.tcpHost, config.tcpPort);
+      if (ok) return true;
+      await sleep(pollInterval);
+    }
+    return false;
+  }
+
+  // -- adapter --
+
+  const adapter: ChannelAdapter = {
+    name: 'signal',
+    channelType: 'signal',
+    supportsThreads: false,
+
+    async setup(cfg: ChannelSetup): Promise<void> {
+      setup = cfg;
+
+      if (config.manageDaemon) {
+        daemon = spawnSignalDaemon(config.cliPath, config.account, config.tcpHost, config.tcpPort);
+        const ready = await waitForDaemon();
+        if (!ready) {
+          daemon.stop();
+          throw new Error('Signal daemon failed to start. Is signal-cli installed and your account linked?');
+        }
+      } else {
+        const ok = await signalTcpCheck(config.tcpHost, config.tcpPort);
+        if (!ok) {
+          const err = new Error(
+            `Signal daemon not reachable at ${config.tcpHost}:${config.tcpPort}. Start it manually or set SIGNAL_MANAGE_DAEMON=true`,
+          );
+          (err as any).name = 'NetworkError';
+          throw err;
+        }
+      }
+
+      tcp = new SignalTcpClient(config.tcpHost, config.tcpPort);
+      await tcp.connect({
+        onNotification: handleNotification,
+        // Signal the adapter that the daemon dropped us. No auto-reconnect yet
+        // — subsequent deliver/setTyping calls short-circuit on `connected`
+        // and log rather than throw into the retry loop. Operators see this in
+        // logs/nanoclaw.log and can restart the service.
+        onClose: () => {
+          if (!connected) return;
+          connected = false;
+          log.warn('Signal channel lost TCP connection to signal-cli daemon', {
+            account: config.account,
+            host: config.tcpHost,
+            port: config.tcpPort,
+          });
+        },
+      });
+
+      try {
+        await tcp.rpc('updateProfile', {
+          name: 'NanoClaw',
+          account: config.account,
+        });
+      } catch {
+        log.debug('Signal: could not set profile name');
+      }
+
+      try {
+        await tcp.rpc('updateConfiguration', {
+          typingIndicators: true,
+          account: config.account,
+        });
+      } catch {
+        log.debug('Signal: could not enable typing indicators');
+      }
+
+      connected = true;
+      log.info('Signal channel connected', {
+        account: config.account,
+        host: config.tcpHost,
+        port: config.tcpPort,
+      });
+    },
+
+    async teardown(): Promise<void> {
+      connected = false;
+      tcp?.close();
+      tcp = null;
+      if (daemon && config.manageDaemon) {
+        daemon.stop();
+        await daemon.exited;
+      }
+      daemon = null;
+      log.info('Signal channel disconnected');
+    },
+
+    isConnected(): boolean {
+      return connected;
+    },
+
+    async deliver(platformId: string, _threadId: string | null, message: OutboundMessage): Promise<string | undefined> {
+      const content = message.content as Record<string, unknown> | string | undefined;
+      let text: string | null = null;
+      if (typeof content === 'string') {
+        text = content;
+      } else if (content && typeof content === 'object' && typeof content.text === 'string') {
+        text = content.text;
+      }
+
+      const files = message.files ?? [];
+
+      // Send accompanying text first so it lands above the attachment(s) in
+      // the recipient's chat. Both branches no-op cleanly if their input is
+      // empty, so any combination of (text, files) works.
+      if (text) await sendText(platformId, text);
+      if (files.length > 0) await sendAttachments(platformId, files);
+      return undefined;
+    },
+
+    async setTyping(platformId: string, _threadId: string | null): Promise<void> {
+      if (!connected || !tcp) return;
+      if (platformId.startsWith('group:')) return;
+
+      try {
+        const params: Record<string, unknown> = { recipient: [platformId] };
+        if (config.account) params.account = config.account;
+        await tcp.rpc('sendTyping', params);
+      } catch (err) {
+        log.debug('Signal: typing indicator failed', { platformId, err });
+      }
+    },
+  };
+
+  return adapter;
+}
+
+// ---------------------------------------------------------------------------
+// Self-registration
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TCP_HOST = '127.0.0.1';
+const DEFAULT_TCP_PORT = 7583;
+
+registerChannelAdapter('signal', {
+  factory: () => {
+    const envVars = readEnvFile([
+      'SIGNAL_ACCOUNT',
+      'SIGNAL_TCP_HOST',
+      'SIGNAL_TCP_PORT',
+      'SIGNAL_CLI_PATH',
+      'SIGNAL_MANAGE_DAEMON',
+      'SIGNAL_DATA_DIR',
+    ]);
+
+    const account = process.env.SIGNAL_ACCOUNT || envVars.SIGNAL_ACCOUNT || '';
+    if (!account) {
+      log.debug('Signal: SIGNAL_ACCOUNT not set, skipping channel');
+      return null;
+    }
+
+    const cliPath = process.env.SIGNAL_CLI_PATH || envVars.SIGNAL_CLI_PATH || 'signal-cli';
+    const tcpHost = process.env.SIGNAL_TCP_HOST || envVars.SIGNAL_TCP_HOST || DEFAULT_TCP_HOST;
+    const tcpPort = parseInt(process.env.SIGNAL_TCP_PORT || envVars.SIGNAL_TCP_PORT || String(DEFAULT_TCP_PORT), 10);
+    const manageDaemon = (process.env.SIGNAL_MANAGE_DAEMON || envVars.SIGNAL_MANAGE_DAEMON || 'true') === 'true';
+
+    const signalDataDir =
+      process.env.SIGNAL_DATA_DIR || envVars.SIGNAL_DATA_DIR || join(homedir(), '.local', 'share', 'signal-cli');
+
+    // Only check for `signal-cli` on PATH when the operator left cliPath at
+    // the default AND asked us to manage the daemon. A custom absolute path
+    // is treated as an explicit promise and spawn will surface its own ENOENT.
+    if (manageDaemon && cliPath === 'signal-cli') {
+      try {
+        execFileSync('which', ['signal-cli'], { stdio: 'ignore' });
+      } catch {
+        log.debug('Signal: signal-cli binary not found, skipping channel');
+        return null;
+      }
+    }
+
+    return createSignalAdapter({
+      cliPath,
+      account,
+      tcpHost,
+      tcpPort,
+      manageDaemon,
+      signalDataDir,
+    });
+  },
+});

src/channels/slack-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the slack channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs slack.ts's
+ * top-level `registerChannelAdapter('slack', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './slack.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and slack.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package to be installed, which holds
+ * in a composed install: the skill's `pnpm install` step runs before this test.
+ *
+ * Note on the Chat SDK family: slack.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js — with a specific options
+ * shape. That core-consumption is a typed call, so the build/typecheck leg
+ * (`pnpm run build`) guards it against upstream drift, not this test. Every Chat SDK
+ * channel (discord, telegram, teams, gchat, webex, …) follows this same shape:
+ * swap the channel name below and the adapter package in the build.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('slack channel registration', () => {
+  it('registers slack via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('slack');
+  });
+});

src/channels/slack.ts

@@ -0,0 +1,30 @@
+/**
+ * Slack channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createSlackAdapter } from '@chat-adapter/slack';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('slack', {
+  factory: () => {
+    const env = readEnvFile(['SLACK_BOT_TOKEN', 'SLACK_SIGNING_SECRET']);
+    if (!env.SLACK_BOT_TOKEN) return null;
+    const slackAdapter = createSlackAdapter({
+      botToken: env.SLACK_BOT_TOKEN,
+      signingSecret: env.SLACK_SIGNING_SECRET,
+    });
+    const bridge = createChatSdkBridge({ adapter: slackAdapter, concurrency: 'concurrent', supportsThreads: true });
+    bridge.resolveChannelName = async (platformId: string) => {
+      try {
+        const info = await slackAdapter.fetchThread(platformId);
+        return (info as { channelName?: string }).channelName ?? null;
+      } catch {
+        return null;
+      }
+    };
+    return bridge;
+  },
+});

src/channels/teams-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the teams channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs teams.ts's
+ * top-level `registerChannelAdapter('teams', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './teams.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and teams.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/teams`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * teams is a Chat SDK channel: teams.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('teams channel registration', () => {
+  it('registers teams via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('teams');
+  });
+});

src/channels/teams.ts

@@ -0,0 +1,23 @@
+/**
+ * Microsoft Teams channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createTeamsAdapter } from '@chat-adapter/teams';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('teams', {
+  factory: () => {
+    const env = readEnvFile(['TEAMS_APP_ID', 'TEAMS_APP_PASSWORD', 'TEAMS_APP_TENANT_ID', 'TEAMS_APP_TYPE']);
+    if (!env.TEAMS_APP_ID) return null;
+    const teamsAdapter = createTeamsAdapter({
+      appId: env.TEAMS_APP_ID,
+      appPassword: env.TEAMS_APP_PASSWORD,
+      appType: (env.TEAMS_APP_TYPE as 'SingleTenant' | 'MultiTenant') || undefined,
+      appTenantId: env.TEAMS_APP_TENANT_ID || undefined,
+    });
+    return createChatSdkBridge({ adapter: teamsAdapter, concurrency: 'concurrent', supportsThreads: true });
+  },
+});

src/channels/telegram-markdown-sanitize.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeTelegramLegacyMarkdown } from './telegram-markdown-sanitize.js';
+
+describe('sanitizeTelegramLegacyMarkdown', () => {
+  it('downgrades CommonMark **bold** to legacy *bold*', () => {
+    expect(sanitizeTelegramLegacyMarkdown('**Host path**')).toBe('*Host path*');
+  });
+
+  it('downgrades CommonMark __bold__ to legacy _italic_', () => {
+    expect(sanitizeTelegramLegacyMarkdown('__label__')).toBe('_label_');
+  });
+
+  it('leaves balanced legacy *bold* and _italic_ alone', () => {
+    expect(sanitizeTelegramLegacyMarkdown('a *b* c _d_ e')).toBe('a *b* c _d_ e');
+  });
+
+  it('preserves inline code spans untouched', () => {
+    const input = 'see `file_name.py` and `**not bold**` here';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+
+  it('preserves fenced code blocks untouched', () => {
+    const input = '```\nfoo_bar **baz**\n```';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+
+  it('strips formatting chars on odd delimiter count (unbalanced *)', () => {
+    expect(sanitizeTelegramLegacyMarkdown('a * b *c*')).toBe('a  b c');
+  });
+
+  it('strips formatting chars on odd delimiter count (unbalanced _)', () => {
+    expect(sanitizeTelegramLegacyMarkdown('file_name has _one italic_')).toBe('filename has one italic');
+  });
+
+  it('strips brackets when unbalanced', () => {
+    expect(sanitizeTelegramLegacyMarkdown('see [docs here')).toBe('see docs here');
+  });
+
+  it('leaves matched brackets (e.g. links) alone when counts balance', () => {
+    const input = 'see [docs](https://example.com) for more';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+
+  it('fixes the real failing message', () => {
+    const input =
+      'Sure! What do you want to mount, and where should it appear inside the container?\n\n' +
+      '- **Host path** (on your machine): e.g. `~/projects/webapp`\n' +
+      '- **Container path**: e.g. `workspace/webapp`\n' +
+      '- **Read-only or read-write?**';
+    const out = sanitizeTelegramLegacyMarkdown(input);
+    expect(out).not.toContain('**');
+    expect(out).toContain('*Host path*');
+    expect(out).toContain('`~/projects/webapp`');
+    expect((out.match(/\*/g) ?? []).length % 2).toBe(0);
+  });
+
+  it('is a no-op on empty string', () => {
+    expect(sanitizeTelegramLegacyMarkdown('')).toBe('');
+  });
+
+  it('replaces dash list bullets with • so the adapter does not re-emit `*` markers', () => {
+    expect(sanitizeTelegramLegacyMarkdown('- one\n- two')).toBe('• one\n• two');
+  });
+
+  it('preserves indented list structure', () => {
+    expect(sanitizeTelegramLegacyMarkdown('  - nested')).toBe('  • nested');
+  });
+
+  it('flattens Markdown horizontal rules (---, ***, ___)', () => {
+    const input = 'before\n---\n***\n___\nafter';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe('before\n⎯⎯⎯\n⎯⎯⎯\n⎯⎯⎯\nafter');
+  });
+
+  it('leaves horizontal rules inside code blocks alone', () => {
+    const input = '```\n---\n```';
+    expect(sanitizeTelegramLegacyMarkdown(input)).toBe(input);
+  });
+});

src/channels/telegram-markdown-sanitize.ts

@@ -0,0 +1,55 @@
+/**
+ * Sanitize outbound text for Telegram's legacy `Markdown` parse mode.
+ *
+ * WORKAROUND: The @chat-adapter/telegram adapter hardcodes parse_mode=Markdown
+ * (legacy) but its converter emits CommonMark. Messages with `**bold**`, odd
+ * delimiter counts, or malformed links are rejected by Telegram and dropped
+ * after retries. Remove this once upstream ships real mode-aware conversion
+ * (vercel/chat PR #367 adds the knob; a follow-up is needed for the converter).
+ */
+
+const CODE_PATTERN = /```[\s\S]*?```|`[^`\n]*`/g;
+const PLACEHOLDER_PREFIX = '\x00CODE';
+const PLACEHOLDER_SUFFIX = '\x00';
+
+export function sanitizeTelegramLegacyMarkdown(input: string): string {
+  if (!input) return input;
+
+  const codeSegments: string[] = [];
+  let text = input.replace(CODE_PATTERN, (m) => {
+    codeSegments.push(m);
+    return `${PLACEHOLDER_PREFIX}${codeSegments.length - 1}${PLACEHOLDER_SUFFIX}`;
+  });
+
+  // The adapter re-parses and re-stringifies markdown before sending, which
+  // rewrites `- item` list bullets into `* item` — injecting unbalanced
+  // asterisks that Telegram's legacy Markdown parser then rejects. Replace
+  // list bullets with a plain Unicode bullet so the adapter treats the line
+  // as prose.
+  text = text.replace(/^(\s*)[-+]\s+/gm, '$1• ');
+
+  // Flatten Markdown horizontal rules (bare --- / *** / ___ lines) to a
+  // plain Unicode divider. The parser doesn't understand HR syntax and the
+  // `*` / `_` characters would otherwise unbalance the delimiter counts below.
+  text = text.replace(/^[ \t]*[-_*]{3,}[ \t]*$/gm, '⎯⎯⎯');
+
+  text = text.replace(/\*\*([^*\n]+?)\*\*/g, '*$1*');
+  text = text.replace(/__([^_\n]+?)__/g, '_$1_');
+
+  const starCount = (text.match(/\*/g) ?? []).length;
+  const underCount = (text.match(/_/g) ?? []).length;
+  if (starCount % 2 !== 0 || underCount % 2 !== 0) {
+    text = text.replace(/[*_]/g, '');
+  }
+
+  const openBrackets = (text.match(/\[/g) ?? []).length;
+  const closeBrackets = (text.match(/\]/g) ?? []).length;
+  if (openBrackets !== closeBrackets) {
+    text = text.replace(/[[\]]/g, '');
+  }
+
+  return text.replace(
+    new RegExp(`${PLACEHOLDER_PREFIX}(\\d+)${PLACEHOLDER_SUFFIX}`, 'g'),
+    (_, i) => codeSegments[Number(i)],
+  );
+}

src/channels/telegram-pairing.test.ts

@@ -0,0 +1,248 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+vi.mock('../log.js', () => ({ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() } }));
+
+import {
+  createPairing,
+  tryConsume,
+  getStatus,
+  getPairing,
+  waitForPairing,
+  extractCode,
+  extractAddressedText,
+  _setStorePathForTest,
+  _resetForTest,
+} from './telegram-pairing.js';
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tg-pair-'));
+  _setStorePathForTest(path.join(tmpDir, 'pairings.json'));
+});
+
+afterEach(() => {
+  _resetForTest();
+  _setStorePathForTest(null);
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('extractAddressedText', () => {
+  it('strips @botname prefix', () => {
+    expect(extractAddressedText('@nanobot 1234', 'nanobot')).toBe('1234');
+  });
+  it('is case-insensitive', () => {
+    expect(extractAddressedText('@NanoBot hello', 'nanobot')).toBe('hello');
+  });
+  it('returns null when not addressed', () => {
+    expect(extractAddressedText('hello 1234', 'nanobot')).toBeNull();
+  });
+  it('returns null when address is mid-text', () => {
+    expect(extractAddressedText('hi @nanobot 1234', 'nanobot')).toBeNull();
+  });
+});
+
+describe('extractCode', () => {
+  it('accepts a bare 4-digit code', () => {
+    expect(extractCode('0349', 'nanobot')).toBe('0349');
+  });
+  it('accepts 4-digit code after @botname', () => {
+    expect(extractCode('@nanobot 0042', 'nanobot')).toBe('0042');
+  });
+  it('rejects non-4-digit numbers', () => {
+    expect(extractCode('@nanobot 12345', 'nanobot')).toBeNull();
+    expect(extractCode('@nanobot 12', 'nanobot')).toBeNull();
+    expect(extractCode('12345', 'nanobot')).toBeNull();
+  });
+  it('rejects loose matches with surrounding text', () => {
+    expect(extractCode('my pin is 0349', 'nanobot')).toBeNull();
+    expect(extractCode('0349 thanks', 'nanobot')).toBeNull();
+  });
+});
+
+describe('createPairing', () => {
+  it('generates a 4-digit code', async () => {
+    const r = await createPairing('main');
+    expect(r.code).toMatch(/^\d{4}$/);
+    expect(r.status).toBe('pending');
+  });
+
+  it('does not collide with active codes', async () => {
+    const codes = new Set<string>();
+    for (let i = 0; i < 20; i++) {
+      const r = await createPairing('main');
+      expect(codes.has(r.code)).toBe(false);
+      codes.add(r.code);
+    }
+  });
+});
+
+describe('tryConsume', () => {
+  it('matches and marks consumed', async () => {
+    const r = await createPairing('main');
+    const consumed = await tryConsume({
+      text: `@nanobot ${r.code}`,
+      botUsername: 'nanobot',
+      platformId: 'telegram:123',
+      isGroup: false,
+      adminUserId: 'u1',
+    });
+    expect(consumed).not.toBeNull();
+    expect(consumed!.status).toBe('consumed');
+    expect(consumed!.consumed?.platformId).toBe('telegram:123');
+    expect(consumed!.consumed?.adminUserId).toBe('u1');
+    expect(getStatus(r.code)).toBe('consumed');
+  });
+
+  it('returns null on no match (silent drop)', async () => {
+    await createPairing('main');
+    const out = await tryConsume({
+      text: '@nanobot 9999',
+      botUsername: 'nanobot',
+      platformId: 'x',
+      isGroup: false,
+    });
+    expect(out).toBeNull();
+  });
+
+  it('matches a bare code without @botname addressing', async () => {
+    const r = await createPairing('main');
+    const out = await tryConsume({
+      text: r.code,
+      botUsername: 'nanobot',
+      platformId: 'x',
+      isGroup: false,
+    });
+    expect(out).not.toBeNull();
+    expect(out!.status).toBe('consumed');
+  });
+
+  it('cannot be consumed twice', async () => {
+    const r = await createPairing('main');
+    await tryConsume({ text: `@b ${r.code}`, botUsername: 'b', platformId: 'p', isGroup: false });
+    const second = await tryConsume({ text: `@b ${r.code}`, botUsername: 'b', platformId: 'p', isGroup: false });
+    expect(second).toBeNull();
+  });
+
+  it('cannot consume an invalidated pairing', async () => {
+    const r = await createPairing('main');
+    // Invalidate by sending a wrong code
+    await tryConsume({ text: '9999', botUsername: 'b', platformId: 'p', isGroup: false });
+    const out = await tryConsume({ text: `@b ${r.code}`, botUsername: 'b', platformId: 'p', isGroup: false });
+    expect(out).toBeNull();
+    expect(getStatus(r.code)).toBe('invalidated');
+  });
+});
+
+describe('getStatus', () => {
+  it('returns unknown for missing codes', () => {
+    expect(getStatus('0000')).toBe('unknown');
+  });
+});
+
+describe('waitForPairing', () => {
+  it('resolves when consumed', async () => {
+    const r = await createPairing('main');
+    const p = waitForPairing(r.code, { pollMs: 50 });
+    setTimeout(() => {
+      tryConsume({ text: `@b ${r.code}`, botUsername: 'b', platformId: 'tg:1', isGroup: true, name: 'Group' });
+    }, 100);
+    const consumed = await p;
+    expect(consumed.status).toBe('consumed');
+    expect(consumed.consumed?.name).toBe('Group');
+  });
+
+  it('rejects on invalidation', async () => {
+    const r = await createPairing('main');
+    const waiter = waitForPairing(r.code, { pollMs: 30 });
+    setTimeout(() => {
+      tryConsume({ text: '0000', botUsername: 'b', platformId: 'tg:1', isGroup: false });
+    }, 60);
+    await expect(waiter).rejects.toThrow(/invalidated/);
+  });
+});
+
+describe('replace-by-default', () => {
+  it('supersedes an existing pending pairing with the same intent', async () => {
+    const first = await createPairing('main');
+    const second = await createPairing('main');
+    expect(getStatus(first.code)).toBe('invalidated');
+    expect(getStatus(second.code)).toBe('pending');
+  });
+
+  it('does not supersede pairings with a different intent', async () => {
+    const a = await createPairing({ kind: 'wire-to', folder: 'work' });
+    const b = await createPairing({ kind: 'wire-to', folder: 'side' });
+    expect(getStatus(a.code)).toBe('pending');
+    expect(getStatus(b.code)).toBe('pending');
+  });
+
+  it('causes waitForPairing on the old code to reject as invalidated', async () => {
+    const first = await createPairing('main');
+    const waiter = waitForPairing(first.code, { pollMs: 30 });
+    await new Promise((r) => setTimeout(r, 50));
+    await createPairing('main');
+    await expect(waiter).rejects.toThrow(/invalidated/);
+  });
+});
+
+describe('attempt tracking', () => {
+  it('fires onAttempt for a wrong code, invalidates the pairing, and rejects the waiter', async () => {
+    const r = await createPairing('main');
+    const attempts: string[] = [];
+    const waiter = waitForPairing(r.code, {
+      pollMs: 30,
+      onAttempt: (a) => attempts.push(a.candidate),
+    });
+    setTimeout(() => {
+      tryConsume({ text: '9999', botUsername: 'b', platformId: 'tg:1', isGroup: false });
+    }, 60);
+    await expect(waiter).rejects.toThrow(/invalidated by wrong code \(9999\)/);
+    expect(attempts).toEqual(['9999']);
+    expect(getStatus(r.code)).toBe('invalidated');
+  });
+
+  it('a correct code consumes without firing onAttempt', async () => {
+    const r = await createPairing('main');
+    const attempts: string[] = [];
+    const waiter = waitForPairing(r.code, {
+      pollMs: 30,
+      onAttempt: (a) => attempts.push(a.candidate),
+    });
+    setTimeout(() => {
+      tryConsume({ text: r.code, botUsername: 'b', platformId: 'tg:1', isGroup: false });
+    }, 60);
+    const consumed = await waiter;
+    expect(consumed.status).toBe('consumed');
+    expect(attempts).toEqual([]);
+  });
+
+  it('ignores non-code messages and keeps the pairing pending', async () => {
+    const r = await createPairing('main');
+    await tryConsume({ text: 'hello there', botUsername: 'b', platformId: 'p', isGroup: false });
+    const after = getPairing(r.code);
+    expect(after?.status).toBe('pending');
+    expect(after?.attempts ?? []).toHaveLength(0);
+  });
+
+  it('a second code attempt after invalidation does not match', async () => {
+    const r = await createPairing('main');
+    await tryConsume({ text: '9999', botUsername: 'b', platformId: 'p', isGroup: false });
+    const retry = await tryConsume({ text: r.code, botUsername: 'b', platformId: 'p', isGroup: false });
+    expect(retry).toBeNull();
+  });
+});
+
+describe('intent passthrough', () => {
+  it('preserves wire-to and new-agent intents', async () => {
+    const a = await createPairing({ kind: 'wire-to', folder: 'work' });
+    const b = await createPairing({ kind: 'new-agent', folder: 'side' });
+    const ca = await tryConsume({ text: `@b ${a.code}`, botUsername: 'b', platformId: 'p1', isGroup: true });
+    const cb = await tryConsume({ text: `@b ${b.code}`, botUsername: 'b', platformId: 'p2', isGroup: true });
+    expect(ca!.intent).toEqual({ kind: 'wire-to', folder: 'work' });
+    expect(cb!.intent).toEqual({ kind: 'new-agent', folder: 'side' });
+  });
+});

src/channels/telegram-pairing.ts

@@ -0,0 +1,339 @@
+/**
+ * Telegram pairing — proves the operator owns the chat they're registering.
+ *
+ * BotFather hands out tokens with no user binding, so anyone who guesses the
+ * bot's username can DM it. Pairing closes that gap: setup creates a one-time
+ * 4-digit code and the operator echoes it back from the chat they want to
+ * register. The message must be exactly the 4 digits (optionally prefixed by
+ * `@botname ` for groups with privacy ON) — arbitrary messages that happen to
+ * contain a 4-digit number do NOT match. The inbound interceptor in
+ * telegram.ts matches the code, records the chat, upserts the paired user,
+ * and (if no owner exists yet) promotes them to owner — all before the
+ * message ever reaches the router.
+ *
+ * Storage is a JSON file at data/telegram-pairings.json — single-process,
+ * read-modify-write under an in-process mutex.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { DATA_DIR } from '../config.js';
+import { log } from '../log.js';
+
+export type PairingIntent = 'main' | { kind: 'wire-to'; folder: string } | { kind: 'new-agent'; folder: string };
+export type PairingStatus = 'pending' | 'consumed' | 'invalidated' | 'unknown';
+
+export interface ConsumedDetails {
+  platformId: string;
+  isGroup: boolean;
+  name: string | null;
+  adminUserId: string | null;
+  consumedAt: string;
+}
+
+export interface PairingAttempt {
+  candidate: string;
+  platformId: string;
+  at: string;
+  matched: boolean;
+}
+
+export interface PairingRecord {
+  code: string;
+  intent: PairingIntent;
+  createdAt: string;
+  status: Exclude<PairingStatus, 'unknown'>;
+  consumed?: ConsumedDetails;
+  /** Recent pairing attempts observed while this record was pending. Capped. */
+  attempts?: PairingAttempt[];
+}
+
+const MAX_ATTEMPTS_PER_RECORD = 10;
+
+function intentEquals(a: PairingIntent, b: PairingIntent): boolean {
+  if (a === 'main' || b === 'main') return a === b;
+  return a.kind === b.kind && a.folder === b.folder;
+}
+
+interface Store {
+  pairings: PairingRecord[];
+}
+
+/** Pairing codes do not expire — they are consumed on match or invalidated by wrong guesses. */
+const FILE_NAME = 'telegram-pairings.json';
+
+let storePathOverride: string | null = null;
+export function _setStorePathForTest(p: string | null): void {
+  storePathOverride = p;
+}
+
+function storePath(): string {
+  return storePathOverride ?? path.join(DATA_DIR, FILE_NAME);
+}
+
+let mutex: Promise<unknown> = Promise.resolve();
+function withLock<T>(fn: () => Promise<T> | T): Promise<T> {
+  const next = mutex.then(() => fn());
+  mutex = next.catch(() => {});
+  return next;
+}
+
+function readStore(): Store {
+  try {
+    const raw = fs.readFileSync(storePath(), 'utf8');
+    const parsed = JSON.parse(raw) as Store;
+    if (!Array.isArray(parsed.pairings)) return { pairings: [] };
+    return parsed;
+  } catch {
+    return { pairings: [] };
+  }
+}
+
+function writeStore(store: Store): void {
+  const p = storePath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(store, null, 2));
+  fs.renameSync(tmp, p);
+}
+
+/** Clean up old consumed/invalidated records (keep last 50). */
+function sweep(store: Store): boolean {
+  if (store.pairings.length <= 50) return false;
+  store.pairings = store.pairings.slice(-50);
+  return true;
+}
+
+function generateCode(active: Set<string>): string {
+  // 4-digit numeric, zero-padded. 10k space, fine for one-at-a-time intents.
+  for (let i = 0; i < 50; i++) {
+    const code = Math.floor(Math.random() * 10000)
+      .toString()
+      .padStart(4, '0');
+    if (!active.has(code)) return code;
+  }
+  throw new Error('Could not allocate a free pairing code (too many active).');
+}
+
+export async function createPairing(intent: PairingIntent): Promise<PairingRecord> {
+  return withLock(() => {
+    const store = readStore();
+    sweep(store);
+    // Replace-by-default: a new pairing for an intent supersedes any existing
+    // pending pairing for the same intent. Old waitForPairing calls observe
+    // `invalidated` and exit on their own.
+    for (const r of store.pairings) {
+      if (r.status === 'pending' && intentEquals(r.intent, intent)) {
+        r.status = 'invalidated';
+        log.info('Pairing superseded by new request', { code: r.code, intent });
+      }
+    }
+    const active = new Set(store.pairings.filter((r) => r.status === 'pending').map((r) => r.code));
+    const record: PairingRecord = {
+      code: generateCode(active),
+      intent,
+      createdAt: new Date().toISOString(),
+      status: 'pending',
+    };
+    store.pairings.push(record);
+    writeStore(store);
+    log.info('Pairing created', { code: record.code, intent });
+    return record;
+  });
+}
+
+export interface ConsumeInput {
+  text: string;
+  botUsername: string;
+  platformId: string;
+  isGroup: boolean;
+  name?: string | null;
+  adminUserId?: string | null;
+}
+
+/** Strip leading @botname and return the trimmed remainder, or null if not addressed. */
+export function extractAddressedText(text: string, botUsername: string): string | null {
+  const trimmed = text.trim();
+  const re = new RegExp(`^@${botUsername.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\b`, 'i');
+  const m = trimmed.match(re);
+  if (!m) return null;
+  return trimmed.slice(m[0].length).trim();
+}
+
+/**
+ * Extract a pairing code from an inbound message. The message must be exactly
+ * 4 digits (optionally prefixed by `@botname `) — loose matches like
+ * "my pin is 1234" are rejected to avoid false positives from chatter.
+ */
+export function extractCode(text: string, botUsername: string): string | null {
+  const addressed = extractAddressedText(text, botUsername);
+  const candidate = (addressed !== null ? addressed : text).trim();
+  const m = candidate.match(/^(\d{4})$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Try to match an inbound message against a pending pairing. On match,
+ * marks the pairing consumed atomically and returns the record. Returns
+ * null on no match or expiry (silent drop).
+ */
+export async function tryConsume(input: ConsumeInput): Promise<PairingRecord | null> {
+  const code = extractCode(input.text, input.botUsername);
+  if (!code) return null;
+  return withLock(() => {
+    const store = readStore();
+    const now = Date.now();
+    sweep(store);
+    const record = store.pairings.find((r) => r.code === code && r.status === 'pending');
+    if (!record) {
+      // Miss: record the attempt on every currently-pending record so each
+      // waitForPairing caller can surface it as user feedback.
+      const attempt: PairingAttempt = {
+        candidate: code,
+        platformId: input.platformId,
+        at: new Date(now).toISOString(),
+        matched: false,
+      };
+      let recorded = false;
+      for (const r of store.pairings) {
+        if (r.status !== 'pending') continue;
+        r.attempts = [...(r.attempts ?? []), attempt].slice(-MAX_ATTEMPTS_PER_RECORD);
+        // One attempt per code. A wrong guess invalidates the pairing
+        // immediately — pair-telegram observes the `invalidated` signal and
+        // auto-issues a fresh code (up to a retry cap).
+        r.status = 'invalidated';
+        recorded = true;
+      }
+      writeStore(store);
+      if (recorded) {
+        log.info('Pairing invalidated by wrong attempt', { candidate: code, platformId: input.platformId });
+      }
+      return null;
+    }
+    record.status = 'consumed';
+    record.consumed = {
+      platformId: input.platformId,
+      isGroup: input.isGroup,
+      name: input.name ?? null,
+      adminUserId: input.adminUserId ?? null,
+      consumedAt: new Date(now).toISOString(),
+    };
+    record.attempts = [
+      ...(record.attempts ?? []),
+      { candidate: code, platformId: input.platformId, at: new Date(now).toISOString(), matched: true },
+    ].slice(-MAX_ATTEMPTS_PER_RECORD);
+    writeStore(store);
+    log.info('Pairing consumed', { code, platformId: input.platformId, intent: record.intent });
+    return record;
+  });
+}
+
+export function getStatus(code: string): PairingStatus {
+  const store = readStore();
+  sweep(store);
+  const r = store.pairings.find((p) => p.code === code);
+  if (!r) return 'unknown';
+  return r.status;
+}
+
+export function getPairing(code: string): PairingRecord | null {
+  const store = readStore();
+  sweep(store);
+  return store.pairings.find((p) => p.code === code) ?? null;
+}
+
+export interface WaitForPairingOptions {
+  /** Polling interval as a fallback when fs.watch misses an event. */
+  pollMs?: number;
+  /** Fires once per new attempt recorded against this pairing (misses only). */
+  onAttempt?: (attempt: PairingAttempt) => void;
+}
+
+/**
+ * Resolve when the pairing is consumed; reject when it is invalidated
+ * (wrong code guess). Waits indefinitely — codes do not expire.
+ * Uses fs.watch as the primary signal with a slow poll fallback.
+ */
+export async function waitForPairing(code: string, opts: WaitForPairingOptions = {}): Promise<PairingRecord> {
+  const pollMs = opts.pollMs ?? 1000;
+  const initial = getPairing(code);
+  if (!initial) throw new Error(`Unknown pairing code: ${code}`);
+
+  return new Promise<PairingRecord>((resolve, reject) => {
+    let watcher: fs.FSWatcher | null = null;
+    let interval: NodeJS.Timeout | null = null;
+    let settled = false;
+
+    const cleanup = () => {
+      settled = true;
+      if (watcher)
+        try {
+          watcher.close();
+        } catch {
+          /* ignore */
+        }
+      if (interval) clearInterval(interval);
+    };
+
+    let seenAttempts = 0;
+    const check = () => {
+      if (settled) return;
+      const r = getPairing(code);
+      if (!r) {
+        cleanup();
+        reject(new Error(`Pairing ${code} disappeared`));
+        return;
+      }
+      // Surface any new miss attempts since the last tick. Only fire for
+      // misses — matches are signaled by `status === 'consumed'` below.
+      if (opts.onAttempt && r.attempts) {
+        for (let i = seenAttempts; i < r.attempts.length; i++) {
+          const a = r.attempts[i];
+          if (!a.matched) {
+            try {
+              opts.onAttempt(a);
+            } catch {
+              /* ignore */
+            }
+          }
+        }
+        seenAttempts = r.attempts.length;
+      }
+      if (r.status === 'consumed') {
+        cleanup();
+        resolve(r);
+        return;
+      }
+      if (r.status === 'invalidated') {
+        cleanup();
+        const lastMiss = r.attempts
+          ?.slice()
+          .reverse()
+          .find((a) => !a.matched);
+        reject(new Error(`Pairing ${code} invalidated by wrong code${lastMiss ? ` (${lastMiss.candidate})` : ''}`));
+        return;
+      }
+    };
+
+    try {
+      const dir = path.dirname(storePath());
+      fs.mkdirSync(dir, { recursive: true });
+      watcher = fs.watch(dir, (_event, fname) => {
+        if (!fname || fname.toString().startsWith(path.basename(storePath()))) check();
+      });
+    } catch {
+      // fs.watch unsupported — poll-only is fine
+    }
+    interval = setInterval(check, pollMs);
+    check();
+  });
+}
+
+/** Test helper — wipe the store. */
+export function _resetForTest(): void {
+  try {
+    fs.unlinkSync(storePath());
+  } catch {
+    // ignore
+  }
+}

src/channels/telegram-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the telegram channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs telegram.ts's
+ * top-level `registerChannelAdapter('telegram', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './telegram.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and telegram.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/telegram`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * telegram is a Chat SDK channel: telegram.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('telegram channel registration', () => {
+  it('registers telegram via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('telegram');
+  });
+});

src/channels/telegram.ts

@@ -0,0 +1,245 @@
+/**
+ * Telegram channel adapter (v2) — uses Chat SDK bridge, with a pairing
+ * interceptor wrapped around onInbound to verify chat ownership before
+ * registration. See telegram-pairing.ts for the why.
+ */
+import { createTelegramAdapter } from '@chat-adapter/telegram';
+
+import { readEnvFile } from '../env.js';
+import { log } from '../log.js';
+import { createMessagingGroup, getMessagingGroupByPlatform, updateMessagingGroup } from '../db/messaging-groups.js';
+import { grantRole, hasAnyOwner } from '../modules/permissions/db/user-roles.js';
+import { upsertUser } from '../modules/permissions/db/users.js';
+import { createChatSdkBridge, type ReplyContext } from './chat-sdk-bridge.js';
+import { sanitizeTelegramLegacyMarkdown } from './telegram-markdown-sanitize.js';
+import { registerChannelAdapter } from './channel-registry.js';
+import type { ChannelAdapter, ChannelSetup, InboundMessage } from './adapter.js';
+import { tryConsume } from './telegram-pairing.js';
+
+/**
+ * Retry a one-shot operation that can fail on transient network errors at
+ * cold-start (DNS hiccups, brief upstream outages). Exponential backoff capped
+ * at 5 attempts — if the network is truly down we surface it instead of
+ * hanging the service indefinitely.
+ */
+async function withRetry<T>(fn: () => Promise<T>, label: string, maxAttempts = 5): Promise<T> {
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt === maxAttempts) break;
+      const delay = Math.min(16000, 1000 * 2 ** (attempt - 1));
+      log.warn('Telegram setup failed, retrying', { label, attempt, delayMs: delay, err });
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+  throw lastErr;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractReplyContext(raw: Record<string, any>): ReplyContext | null {
+  if (!raw.reply_to_message) return null;
+  const reply = raw.reply_to_message;
+  return {
+    text: reply.text || reply.caption || '',
+    sender: reply.from?.first_name || reply.from?.username || 'Unknown',
+  };
+}
+
+/** Look up the bot username via Telegram getMe. Cached after first call. */
+async function fetchBotUsername(token: string): Promise<string | null> {
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${token}/getMe`);
+    const json = (await res.json()) as { ok: boolean; result?: { username?: string } };
+    return json.ok ? (json.result?.username ?? null) : null;
+  } catch (err) {
+    log.warn('Telegram getMe failed', { err });
+    return null;
+  }
+}
+
+function isGroupPlatformId(platformId: string): boolean {
+  // platformId is "telegram:<chatId>". Negative chat IDs are groups/channels.
+  const id = platformId.split(':').pop() ?? '';
+  return id.startsWith('-');
+}
+
+interface InboundFields {
+  text: string;
+  authorUserId: string | null;
+}
+
+function readInboundFields(message: InboundMessage): InboundFields {
+  if (message.kind !== 'chat-sdk' || !message.content || typeof message.content !== 'object') {
+    return { text: '', authorUserId: null };
+  }
+  const c = message.content as { text?: string; author?: { userId?: string } };
+  return { text: c.text ?? '', authorUserId: c.author?.userId ?? null };
+}
+
+/**
+ * Build an onInbound interceptor that consumes pairing codes before they
+ * reach the router. On match: records the chat + its paired user, promotes
+ * the user to owner if the instance has no owner yet, and short-circuits.
+ * On miss: forwards to the host.
+ */
+/**
+ * Send a one-shot confirmation back to the paired chat. Best-effort — failures
+ * are logged but never propagated, so a Telegram outage can't undo a successful
+ * pairing or trigger the interceptor's fail-open path.
+ */
+async function sendPairingConfirmation(token: string, platformId: string): Promise<void> {
+  const chatId = platformId.split(':').slice(1).join(':');
+  if (!chatId) return;
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        chat_id: chatId,
+        text: 'Pairing success! Head back to the NanoClaw installer to finish setup.',
+      }),
+    });
+    if (!res.ok) {
+      log.warn('Telegram pairing confirmation non-OK', { status: res.status });
+    }
+  } catch (err) {
+    log.warn('Telegram pairing confirmation failed', { err });
+  }
+}
+
+function createPairingInterceptor(
+  botUsernamePromise: Promise<string | null>,
+  hostOnInbound: ChannelSetup['onInbound'],
+  token: string,
+): ChannelSetup['onInbound'] {
+  return async (platformId, threadId, message) => {
+    try {
+      const botUsername = await botUsernamePromise;
+      if (!botUsername) {
+        hostOnInbound(platformId, threadId, message);
+        return;
+      }
+      const { text, authorUserId } = readInboundFields(message);
+      if (!text) {
+        hostOnInbound(platformId, threadId, message);
+        return;
+      }
+      const consumed = await tryConsume({
+        text,
+        botUsername,
+        platformId,
+        isGroup: isGroupPlatformId(platformId),
+        adminUserId: authorUserId,
+      });
+      if (!consumed) {
+        hostOnInbound(platformId, threadId, message);
+        return;
+      }
+      // Pairing matched — record the chat and short-circuit so the
+      // code-bearing message never reaches an agent. Privilege is now a
+      // property of the paired user, not the chat: upsert the user, and if
+      // this instance has no owner yet, promote them to owner.
+      const existing = getMessagingGroupByPlatform('telegram', platformId);
+      if (existing) {
+        updateMessagingGroup(existing.id, {
+          is_group: consumed.consumed!.isGroup ? 1 : 0,
+        });
+      } else {
+        createMessagingGroup({
+          id: `mg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          channel_type: 'telegram',
+          platform_id: platformId,
+          name: consumed.consumed!.name,
+          is_group: consumed.consumed!.isGroup ? 1 : 0,
+          unknown_sender_policy: 'strict',
+          created_at: new Date().toISOString(),
+        });
+      }
+
+      const pairedUserId = `telegram:${consumed.consumed!.adminUserId}`;
+      upsertUser({
+        id: pairedUserId,
+        kind: 'telegram',
+        display_name: null,
+        created_at: new Date().toISOString(),
+      });
+
+      let promotedToOwner = false;
+      if (!hasAnyOwner()) {
+        grantRole({
+          user_id: pairedUserId,
+          role: 'owner',
+          agent_group_id: null,
+          granted_by: null,
+          granted_at: new Date().toISOString(),
+        });
+        promotedToOwner = true;
+      }
+
+      log.info('Telegram pairing accepted — chat registered', {
+        platformId,
+        pairedUser: pairedUserId,
+        promotedToOwner,
+        intent: consumed.intent,
+      });
+
+      await sendPairingConfirmation(token, platformId);
+    } catch (err) {
+      log.error('Telegram pairing interceptor error', { err });
+      // Fail open: pass through so a pairing bug doesn't break normal traffic.
+      hostOnInbound(platformId, threadId, message);
+    }
+  };
+}
+
+registerChannelAdapter('telegram', {
+  factory: () => {
+    const env = readEnvFile(['TELEGRAM_BOT_TOKEN']);
+    if (!env.TELEGRAM_BOT_TOKEN) return null;
+    const token = env.TELEGRAM_BOT_TOKEN;
+    const telegramAdapter = createTelegramAdapter({
+      botToken: token,
+      mode: 'polling',
+    });
+    const bridge = createChatSdkBridge({
+      adapter: telegramAdapter,
+      concurrency: 'concurrent',
+      extractReplyContext,
+      supportsThreads: false,
+      transformOutboundText: sanitizeTelegramLegacyMarkdown,
+      maxTextLength: 4000,
+    });
+
+    const botUsernamePromise = fetchBotUsername(token);
+
+    const wrapped: ChannelAdapter = {
+      ...bridge,
+      resolveChannelName: async (platformId: string) => {
+        const chatId = platformId.split(':').slice(1).join(':');
+        if (!chatId) return null;
+        try {
+          const res = await fetch(`https://api.telegram.org/bot${token}/getChat`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ chat_id: chatId }),
+          });
+          const data = (await res.json()) as { ok?: boolean; result?: { title?: string } };
+          return data.ok ? (data.result?.title ?? null) : null;
+        } catch {
+          return null;
+        }
+      },
+      async setup(hostConfig: ChannelSetup) {
+        const intercepted: ChannelSetup = {
+          ...hostConfig,
+          onInbound: createPairingInterceptor(botUsernamePromise, hostConfig.onInbound, token),
+        };
+        return withRetry(() => bridge.setup(intercepted), 'bridge.setup');
+      },
+    };
+    return wrapped;
+  },
+});

src/channels/webex-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the webex channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs webex.ts's
+ * top-level `registerChannelAdapter('webex', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './webex.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and webex.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@bitbasti/chat-adapter-webex`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * webex is a Chat SDK channel: webex.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('webex channel registration', () => {
+  it('registers webex via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('webex');
+  });
+});

src/channels/webex.ts

@@ -0,0 +1,21 @@
+/**
+ * Webex channel adapter (v2) — uses Chat SDK bridge.
+ * Self-registers on import.
+ */
+import { createWebexAdapter } from '@bitbasti/chat-adapter-webex';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('webex', {
+  factory: () => {
+    const env = readEnvFile(['WEBEX_BOT_TOKEN', 'WEBEX_WEBHOOK_SECRET']);
+    if (!env.WEBEX_BOT_TOKEN) return null;
+    const webexAdapter = createWebexAdapter({
+      botToken: env.WEBEX_BOT_TOKEN,
+      webhookSecret: env.WEBEX_WEBHOOK_SECRET,
+    });
+    return createChatSdkBridge({ adapter: webexAdapter, concurrency: 'concurrent', supportsThreads: true });
+  },
+});

src/channels/wechat-registration.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Integration test for the wechat channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs wechat.ts's
+ * top-level `registerChannelAdapter('wechat', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './wechat.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * wechat is a native adapter (no Chat SDK bridge). Importing the barrel is safe:
+ * registration is a pure top-level call and wechat.ts opens connections / spawns
+ * subprocesses only inside setup() (run at host startup), never at import. It does
+ * require the adapter package (`wechat-ilink-client`) to be installed, which holds in a composed
+ * install: the skill's `pnpm install` step runs before this test — so this test also
+ * implicitly guards that dependency (an unmocked import throws if the package is missing).
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('wechat channel registration', () => {
+  it('registers wechat via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('wechat');
+  });
+});

src/channels/wechat.ts

@@ -0,0 +1,221 @@
+/**
+ * WeChat channel adapter — uses Tencent's official iLink Bot API.
+ *
+ * Unlike puppet-based libraries (wechaty/PadLocal) this uses the first-party
+ * Tencent API. No ban risk. Free. Works with any personal WeChat account.
+ *
+ * Flow:
+ *   1. Factory gated on WECHAT_ENABLED=true in .env.
+ *   2. On setup, load saved auth if present; otherwise run QR login.
+ *      The QR URL is written to data/wechat/qr.txt and logged.
+ *   3. Long-poll for messages via WeChatClient, cursor persisted between
+ *      restarts so no messages are dropped.
+ *   4. Outbound via sendText — context_token auto-cached by the client.
+ *
+ * Self-registers on import.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { WeChatClient, MessageType, type WeixinMessage } from 'wechat-ilink-client';
+
+import { readEnvFile } from '../env.js';
+import { DATA_DIR } from '../config.js';
+import { log } from '../log.js';
+import { registerChannelAdapter } from './channel-registry.js';
+import type { ChannelAdapter, ChannelSetup, InboundMessage, OutboundMessage } from './adapter.js';
+
+const DATA_SUBDIR = path.join(DATA_DIR, 'wechat');
+const AUTH_FILE = path.join(DATA_SUBDIR, 'auth.json');
+const SYNC_BUF_FILE = path.join(DATA_SUBDIR, 'sync-buf.txt');
+const QR_FILE = path.join(DATA_SUBDIR, 'qr.txt');
+
+interface SavedAuth {
+  botToken: string;
+  accountId: string;
+  baseUrl?: string;
+  /** The WeChat user_id of whoever scanned the QR — i.e. the operator. */
+  operatorUserId?: string;
+}
+
+function loadAuth(): SavedAuth | null {
+  try {
+    return JSON.parse(fs.readFileSync(AUTH_FILE, 'utf8')) as SavedAuth;
+  } catch {
+    return null;
+  }
+}
+
+function saveAuth(auth: SavedAuth): void {
+  fs.mkdirSync(DATA_SUBDIR, { recursive: true });
+  fs.writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2));
+}
+
+function loadSyncBuf(): string | undefined {
+  try {
+    return fs.readFileSync(SYNC_BUF_FILE, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+function saveSyncBuf(buf: string): void {
+  fs.mkdirSync(DATA_SUBDIR, { recursive: true });
+  fs.writeFileSync(SYNC_BUF_FILE, buf);
+}
+
+function writeQr(url: string): void {
+  fs.mkdirSync(DATA_SUBDIR, { recursive: true });
+  fs.writeFileSync(QR_FILE, url);
+}
+
+function messageText(msg: OutboundMessage): string {
+  if (typeof msg.content === 'string') return msg.content;
+  const c = msg.content as Record<string, unknown>;
+  return (c.text as string) || (c.markdown as string) || JSON.stringify(msg.content);
+}
+
+registerChannelAdapter('wechat', {
+  factory: () => {
+    const env = readEnvFile(['WECHAT_ENABLED']);
+    if (env.WECHAT_ENABLED !== 'true') return null;
+
+    let client: WeChatClient | null = null;
+    let setupConfig: ChannelSetup;
+    let connected = false;
+    let accountId: string | undefined;
+
+    async function ensureLoggedIn(): Promise<WeChatClient> {
+      const saved = loadAuth();
+      if (saved) {
+        const c = new WeChatClient({
+          token: saved.botToken,
+          baseUrl: saved.baseUrl,
+          accountId: saved.accountId,
+        });
+        accountId = saved.accountId;
+        log.info('WeChat: resumed from saved auth', { accountId });
+        return c;
+      }
+
+      const c = new WeChatClient();
+      const result = await c.login({
+        onQRCode: (url) => {
+          writeQr(url);
+          log.info('WeChat QR ready — open this URL in a browser and scan with the WeChat app', { url });
+        },
+      });
+      if (!result.connected || !result.botToken || !result.accountId) {
+        throw new Error(`WeChat login failed: ${result.message}`);
+      }
+      saveAuth({
+        botToken: result.botToken,
+        accountId: result.accountId,
+        baseUrl: result.baseUrl,
+        operatorUserId: result.userId,
+      });
+      accountId = result.accountId;
+      log.info('WeChat: login complete', { accountId, operatorUserId: result.userId });
+      return c;
+    }
+
+    function onMessage(msg: WeixinMessage): void {
+      if (msg.message_type !== MessageType.USER) return;
+
+      const isGroup = !!msg.group_id;
+      const platformIdRaw = isGroup ? msg.group_id! : msg.from_user_id!;
+      const platformId = `wechat:${platformIdRaw}`;
+      const senderId = `wechat:${msg.from_user_id ?? 'unknown'}`;
+      const text = WeChatClient.extractText(msg);
+
+      log.info('WeChat inbound', {
+        platformId,
+        senderId,
+        isGroup,
+        hint: 'if not wired yet, run: pnpm exec tsx .claude/skills/add-wechat/scripts/wire-dm.ts',
+      });
+
+      setupConfig.onMetadata(platformId, undefined, isGroup);
+
+      const inbound: InboundMessage = {
+        id: String(msg.message_id ?? msg.seq ?? Date.now()),
+        kind: 'chat',
+        content: {
+          text,
+          senderId,
+          sender: msg.from_user_id,
+          senderName: msg.from_user_id,
+          isGroup,
+        },
+        timestamp: new Date(msg.create_time_ms ?? Date.now()).toISOString(),
+      };
+
+      setupConfig.onInbound(platformId, null, inbound);
+    }
+
+    const adapter: ChannelAdapter = {
+      name: 'wechat',
+      channelType: 'wechat',
+      supportsThreads: false,
+
+      async setup(config: ChannelSetup) {
+        setupConfig = config;
+
+        client = await ensureLoggedIn();
+
+        client.on('message', (msg) => {
+          try {
+            onMessage(msg);
+          } catch (err) {
+            log.warn('WeChat: onMessage error', { err });
+          }
+        });
+        client.on('error', (err) => log.warn('WeChat: poll error', { err }));
+        client.on('sessionExpired', () => {
+          log.error('WeChat: session expired — delete data/wechat/auth.json and restart to re-scan');
+          connected = false;
+        });
+
+        client
+          .start({
+            loadSyncBuf,
+            saveSyncBuf,
+          })
+          .catch((err) => log.error('WeChat: monitor loop crashed', { err }));
+
+        connected = true;
+        log.info('WeChat adapter ready', { accountId });
+      },
+
+      async teardown() {
+        connected = false;
+        client?.stop();
+        client = null;
+      },
+
+      isConnected() {
+        return connected;
+      },
+
+      async deliver(
+        platformId: string,
+        _threadId: string | null,
+        message: OutboundMessage,
+      ): Promise<string | undefined> {
+        if (!client) return undefined;
+        const to = platformId.replace(/^wechat:/, '');
+        const text = messageText(message);
+        if (!text) return undefined;
+        try {
+          const msgId = await client.sendText(to, text);
+          return msgId;
+        } catch (err) {
+          log.error('WeChat deliver failed', { platformId, err });
+          return undefined;
+        }
+      },
+    };
+
+    return adapter;
+  },
+});

src/channels/whatsapp-cloud-registration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration test for the whatsapp-cloud channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs whatsapp-cloud.ts's
+ * top-level `registerChannelAdapter('whatsapp-cloud', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './whatsapp-cloud.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * Importing the barrel is safe: registration is a pure top-level call, and whatsapp-cloud.ts
+ * builds the SDK adapter / bridge only inside its factory (invoked at host startup),
+ * never at import. It does require the adapter package (`@chat-adapter/whatsapp`) to be installed,
+ * which holds in a composed install: the skill's `pnpm install` step runs before this
+ * test — so this test also implicitly guards that dependency (an unmocked import throws
+ * if the package is missing).
+ *
+ * whatsapp-cloud is a Chat SDK channel: whatsapp-cloud.ts also consumes a load-bearing *core* API —
+ * `createChatSdkBridge(...)` from ./chat-sdk-bridge.js. That core-consumption is a
+ * typed call, so the build/typecheck leg (`pnpm run build`) guards it against upstream
+ * drift, not this test. Every Chat SDK channel follows this same shape.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('whatsapp-cloud channel registration', () => {
+  it('registers whatsapp-cloud via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('whatsapp-cloud');
+  });
+});

src/channels/whatsapp-cloud.ts

@@ -0,0 +1,29 @@
+/**
+ * WhatsApp Cloud API channel adapter (v2) — uses Chat SDK bridge.
+ * Uses the official Meta WhatsApp Business Cloud API (not Baileys).
+ * Self-registers on import.
+ */
+import { createWhatsAppAdapter } from '@chat-adapter/whatsapp';
+
+import { readEnvFile } from '../env.js';
+import { createChatSdkBridge } from './chat-sdk-bridge.js';
+import { registerChannelAdapter } from './channel-registry.js';
+
+registerChannelAdapter('whatsapp-cloud', {
+  factory: () => {
+    const env = readEnvFile([
+      'WHATSAPP_ACCESS_TOKEN',
+      'WHATSAPP_PHONE_NUMBER_ID',
+      'WHATSAPP_APP_SECRET',
+      'WHATSAPP_VERIFY_TOKEN',
+    ]);
+    if (!env.WHATSAPP_ACCESS_TOKEN) return null;
+    const whatsappAdapter = createWhatsAppAdapter({
+      accessToken: env.WHATSAPP_ACCESS_TOKEN,
+      phoneNumberId: env.WHATSAPP_PHONE_NUMBER_ID,
+      appSecret: env.WHATSAPP_APP_SECRET,
+      verifyToken: env.WHATSAPP_VERIFY_TOKEN,
+    });
+    return createChatSdkBridge({ adapter: whatsappAdapter, concurrency: 'concurrent', supportsThreads: false });
+  },
+});

src/channels/whatsapp-registration.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Integration test for the whatsapp channel's single reach-in: the self-registration
+ * import in the `src/channels/index.ts` barrel. Importing the barrel runs whatsapp.ts's
+ * top-level `registerChannelAdapter('whatsapp', …)`; without the import the channel is
+ * silently absent.
+ *
+ * Behavior, not structural: it imports the real barrel and asserts the registry
+ * actually contains the channel. This reflects what happens at host boot — if the
+ * `import './whatsapp.js';` line is deleted, or the barrel fails to evaluate for any
+ * reason (so the channel genuinely would not register), this goes red. A structural
+ * check of the import line would falsely pass in that second case.
+ *
+ * whatsapp is a native adapter (no Chat SDK bridge). Importing the barrel is safe:
+ * registration is a pure top-level call and whatsapp.ts opens connections / spawns
+ * subprocesses only inside setup() (run at host startup), never at import. It does
+ * require the adapter package (`@whiskeysockets/baileys`) to be installed, which holds in a composed
+ * install: the skill's `pnpm install` step runs before this test — so this test also
+ * implicitly guards that dependency (an unmocked import throws if the package is missing).
+ */
+import { describe, it, expect } from 'vitest';
+
+import { getRegisteredChannelNames } from './channel-registry.js';
+import './index.js'; // the real barrel — triggers every channel's self-registration
+
+describe('whatsapp channel registration', () => {
+  it('registers whatsapp via the channel barrel', () => {
+    expect(getRegisteredChannelNames()).toContain('whatsapp');
+  });
+});

src/channels/whatsapp.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Regression coverage for #2560 — group @-mentions of the bot must set
+ * `InboundMessage.isMention`. Before the fix, the inbound construction
+ * site hard-coded `isMention: !isGroup ? true : undefined`, which dropped
+ * every group mention on the floor and prevented the router from waking
+ * the agent on a mention-only trigger.
+ *
+ * The detection logic lives in the exported pure helper `isBotMentionedInGroup`;
+ * the inbound site calls it with `normalized`, `botPhoneJid`, `botLidUser`.
+ * `isMention` is then computed as:
+ *
+ *   isMention: !isGroup ? true : botMentionedInGroup ? true : undefined
+ *
+ * Both the helper and the call-site ternary are covered below so a future
+ * refactor that breaks either part fails this suite.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { computeIsMention, isBotMentionedInGroup, parseWhatsAppMentions } from './whatsapp.js';
+
+const BOT_PHONE_JID = '15550009999@s.whatsapp.net';
+const BOT_LID_USER = '987654321';
+
+describe('isBotMentionedInGroup (#2560)', () => {
+  it('detects the bot phone JID in extendedTextMessage.contextInfo.mentionedJid', () => {
+    const normalized = {
+      extendedTextMessage: {
+        text: 'hey @15550009999 take a look',
+        contextInfo: { mentionedJid: [BOT_PHONE_JID] },
+      },
+    };
+    expect(isBotMentionedInGroup(normalized, BOT_PHONE_JID, BOT_LID_USER)).toBe(true);
+  });
+
+  it('returns false when the bot is not in mentionedJid', () => {
+    const normalized = {
+      extendedTextMessage: {
+        text: 'hey @15551112222 take a look',
+        contextInfo: { mentionedJid: ['15551112222@s.whatsapp.net'] },
+      },
+    };
+    expect(isBotMentionedInGroup(normalized, BOT_PHONE_JID, BOT_LID_USER)).toBe(false);
+  });
+
+  it('detects an LID-only mention when no phone JID is in the list', () => {
+    // Modern WhatsApp clients increasingly emit the LID even when the
+    // human typed a phone-number mention; the phone JID may not appear.
+    const normalized = {
+      extendedTextMessage: {
+        contextInfo: { mentionedJid: [`${BOT_LID_USER}@lid`] },
+      },
+    };
+    expect(isBotMentionedInGroup(normalized, BOT_PHONE_JID, BOT_LID_USER)).toBe(true);
+  });
+
+  it('detects a mention in an image caption', () => {
+    const normalized = {
+      imageMessage: {
+        caption: 'check this @15550009999',
+        contextInfo: { mentionedJid: [BOT_PHONE_JID] },
+      },
+    };
+    expect(isBotMentionedInGroup(normalized, BOT_PHONE_JID, BOT_LID_USER)).toBe(true);
+  });
+
+  it('returns false on an empty / missing mentionedJid array', () => {
+    expect(isBotMentionedInGroup({}, BOT_PHONE_JID, BOT_LID_USER)).toBe(false);
+    expect(
+      isBotMentionedInGroup(
+        { extendedTextMessage: { contextInfo: { mentionedJid: [] } } },
+        BOT_PHONE_JID,
+        BOT_LID_USER,
+      ),
+    ).toBe(false);
+  });
+
+  it('returns false when neither bot identifier is known', () => {
+    const normalized = {
+      extendedTextMessage: {
+        contextInfo: { mentionedJid: [BOT_PHONE_JID, `${BOT_LID_USER}@lid`] },
+      },
+    };
+    expect(isBotMentionedInGroup(normalized, undefined, undefined)).toBe(false);
+  });
+});
+
+describe('InboundMessage.isMention semantics (#2560)', () => {
+  it('is undefined for a group message with no bot mention', () => {
+    expect(computeIsMention(true, false)).toBeUndefined();
+  });
+
+  it('is true for a group message where the bot is mentioned', () => {
+    expect(computeIsMention(true, true)).toBe(true);
+  });
+
+  it('is true for a DM regardless of mention state', () => {
+    // DMs are unconditionally mentions — the helper isn't consulted there.
+    expect(computeIsMention(false, false)).toBe(true);
+    expect(computeIsMention(false, true)).toBe(true);
+  });
+});
+
+describe('parseWhatsAppMentions', () => {
+  it('returns empty mentions for plain text', () => {
+    const { text, mentions } = parseWhatsAppMentions('hello there');
+    expect(text).toBe('hello there');
+    expect(mentions).toEqual([]);
+  });
+
+  it('extracts a single @<digits> mention into a JID', () => {
+    const { text, mentions } = parseWhatsAppMentions('hey @15551234567 you around?');
+    expect(text).toBe('hey @15551234567 you around?');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net']);
+  });
+
+  it('strips a leading + so the literal text matches the JID digits', () => {
+    const { text, mentions } = parseWhatsAppMentions('ping @+15551234567 please');
+    expect(text).toBe('ping @15551234567 please');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net']);
+  });
+
+  it('matches a mention at the start of the string', () => {
+    const { text, mentions } = parseWhatsAppMentions('@15551234567 hi');
+    expect(text).toBe('@15551234567 hi');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net']);
+  });
+
+  it('extracts multiple distinct mentions', () => {
+    const { text, mentions } = parseWhatsAppMentions('cc @15551234567 and @17775556666');
+    expect(text).toBe('cc @15551234567 and @17775556666');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net', '17775556666@s.whatsapp.net']);
+  });
+
+  it('deduplicates repeated mentions of the same number', () => {
+    const { mentions } = parseWhatsAppMentions('@15551234567 ping @15551234567 again');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net']);
+  });
+
+  it('does not tag email-like patterns', () => {
+    const { text, mentions } = parseWhatsAppMentions('write to test@1234567890.com');
+    expect(text).toBe('write to test@1234567890.com');
+    expect(mentions).toEqual([]);
+  });
+
+  it('does not tag sequences shorter than 5 digits', () => {
+    const { text, mentions } = parseWhatsAppMentions('see issue @123 for details');
+    expect(text).toBe('see issue @123 for details');
+    expect(mentions).toEqual([]);
+  });
+
+  it('handles punctuation directly after the digits', () => {
+    const { text, mentions } = parseWhatsAppMentions('thanks @15551234567!');
+    expect(text).toBe('thanks @15551234567!');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net']);
+  });
+
+  it('handles parenthesized mentions', () => {
+    const { text, mentions } = parseWhatsAppMentions('(@15551234567) wrote this');
+    expect(text).toBe('(@15551234567) wrote this');
+    expect(mentions).toEqual(['15551234567@s.whatsapp.net']);
+  });
+});

src/channels/whatsapp.ts

@@ -0,0 +1,932 @@
+/**
+ * WhatsApp channel adapter (v2) — native Baileys v7 implementation.
+ *
+ * Implements ChannelAdapter directly (no Chat SDK bridge) using
+ * @whiskeysockets/baileys 7.0.0-rc.9 (pinned — last release, unmaintained).
+ * Ports proven v1 infrastructure: getMessage fallback, outgoing queue,
+ * group metadata cache, LID mapping, reconnection with backoff.
+ *
+ * LID handling: Baileys v7 provides participantAlt / remoteJidAlt on every
+ * inbound message via extractAddressingContext, plus a real
+ * signalRepository.lidMapping.getPNForLID API. The adapter always resolves
+ * to phone JID (@s.whatsapp.net) before emitting to the router.
+ *
+ * Auth credentials persist in store/auth/. On first run:
+ * - If WHATSAPP_PHONE_NUMBER is set → pairing code (printed to log)
+ * - Otherwise → QR code (printed to log)
+ * Subsequent restarts reuse the saved session automatically.
+ */
+import fs from 'fs';
+import path from 'path';
+// Named import (not default) — pino's .d.ts under NodeNext resolution
+// exports `{ pino as default, pino }`, but the namespace/function merge at
+// `declare namespace pino` + `declare function pino` makes the default
+// resolve to `typeof pino` (the namespace type), which isn't callable.
+// The named export resolves to the callable function.
+import { pino } from 'pino';
+
+import {
+  makeWASocket,
+  proto,
+  Browsers,
+  DisconnectReason,
+  fetchLatestWaWebVersion,
+  downloadMediaMessage,
+  makeCacheableSignalKeyStore,
+  normalizeMessageContent,
+  useMultiFileAuthState,
+} from '@whiskeysockets/baileys';
+import type { GroupMetadata, WAMessageKey, WAMessage, WASocket } from '@whiskeysockets/baileys';
+
+import { isSafeAttachmentName } from '../attachment-safety.js';
+import { ASSISTANT_HAS_OWN_NUMBER, ASSISTANT_NAME, DATA_DIR } from '../config.js';
+import { readEnvFile } from '../env.js';
+import { log } from '../log.js';
+import { registerChannelAdapter } from './channel-registry.js';
+import { normalizeOptions, type NormalizedOption } from './ask-question.js';
+import type { ChannelAdapter, ChannelSetup, ConversationInfo, InboundMessage, OutboundMessage } from './adapter.js';
+
+const baileysLogger = pino({ level: 'silent' });
+
+/**
+ * Fetch the latest WhatsApp Web version. Baileys' built-in
+ * fetchLatestWaWebVersion scrapes sw.js which is aggressively
+ * rate-limited (429). When it fails, Baileys falls back to a
+ * hardcoded version that goes stale within weeks — WhatsApp
+ * rejects connections with an expired buildHash (405 at Noise
+ * layer). This fetches from wppconnect's version tracker as a
+ * more reliable source, with Baileys' own fetch as fallback.
+ */
+async function resolveWaWebVersion(): Promise<[number, number, number]> {
+  // 1. Try wppconnect version tracker (HTML scrape — no JSON API)
+  try {
+    const res = await fetch('https://wppconnect.io/whatsapp-versions/', {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.ok) {
+      const html = await res.text();
+      const match = html.match(/2\.3000\.(\d+)/);
+      if (match) {
+        const version: [number, number, number] = [2, 3000, Number(match[1])];
+        log.info('Fetched WA Web version from wppconnect', { version });
+        return version;
+      }
+    }
+  } catch {
+    // Fall through to Baileys' own fetch
+  }
+
+  // 2. Try Baileys' built-in fetch (scrapes sw.js — often 429'd)
+  try {
+    const { version } = await fetchLatestWaWebVersion({});
+    if (version) {
+      log.info('Fetched WA Web version from Baileys', { version });
+      return version as [number, number, number];
+    }
+  } catch {
+    // Fall through
+  }
+
+  throw new Error(
+    'Could not fetch current WhatsApp Web version from any source. ' +
+      'Baileys hardcodes a stale version that WhatsApp rejects (405). ' +
+      'Check network connectivity to wppconnect.io and web.whatsapp.com.',
+  );
+}
+
+const AUTH_DIR = path.join(process.cwd(), 'store', 'auth');
+const GROUP_SYNC_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+const GROUP_METADATA_CACHE_TTL_MS = 60_000; // 1 min for outbound sends
+const SENT_MESSAGE_CACHE_MAX = 256;
+const RECONNECT_DELAY_MS = 5000;
+const PENDING_QUESTIONS_MAX = 64;
+
+/** Normalize an option label to a slash command: "Approve" → "/approve" */
+function optionToCommand(option: string): string {
+  return '/' + option.toLowerCase().replace(/\s+/g, '-');
+}
+
+// --- Markdown → WhatsApp formatting ---
+
+interface TextSegment {
+  content: string;
+  isProtected: boolean;
+}
+
+/** Split text into code-block-protected and unprotected regions. */
+function splitProtectedRegions(text: string): TextSegment[] {
+  const segments: TextSegment[] = [];
+  const codeBlockRegex = /```[\s\S]*?```|`[^`\n]+`/g;
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = codeBlockRegex.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      segments.push({ content: text.slice(lastIndex, match.index), isProtected: false });
+    }
+    segments.push({ content: match[0], isProtected: true });
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < text.length) {
+    segments.push({ content: text.slice(lastIndex), isProtected: false });
+  }
+
+  return segments;
+}
+
+/** Apply WhatsApp-native formatting to an unprotected text segment. */
+function transformForWhatsApp(text: string): string {
+  // Order matters: italic before bold to avoid **bold** → *bold* → _bold_
+  // 1. Italic: *text* (not **) → _text_
+  text = text.replace(/(?<!\*)\*(?=[^\s*])([^*\n]+?)(?<=[^\s*])\*(?!\*)/g, '_$1_');
+  // 2. Bold: **text** → *text*
+  text = text.replace(/\*\*(?=[^\s*])([^*]+?)(?<=[^\s*])\*\*/g, '*$1*');
+  // 3. Headings: ## Title → *Title*
+  text = text.replace(/^#{1,6}\s+(.+)$/gm, '*$1*');
+  // 4. Links: [text](url) → text (url)
+  text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1 ($2)');
+  // 5. Horizontal rules: --- / *** / ___ → stripped
+  text = text.replace(/^(-{3,}|\*{3,}|_{3,})$/gm, '');
+  return text;
+}
+
+// WhatsApp tags `@<phone-digits>` (5–15 digit local part — covers short test
+// numbers up to ITU E.164 max). A leading `+` is accepted but stripped so
+// the literal in text matches the digits in the JID — WhatsApp clients
+// scan the rendered text for `@<digits>` and cross-reference it with the
+// contextInfo.mentionedJid list to draw the bold/clickable tag.
+const MENTION_RE = /(^|[^\w@+])@\+?(\d{5,15})(?!\d)/g;
+
+/** Extract `@<digits>` mentions from text and normalize them. */
+export function parseWhatsAppMentions(text: string): { text: string; mentions: string[] } {
+  const mentions = new Set<string>();
+  const out = text.replace(MENTION_RE, (_full, lead: string, digits: string) => {
+    mentions.add(`${digits}@s.whatsapp.net`);
+    return `${lead}@${digits}`;
+  });
+  return { text: out, mentions: [...mentions] };
+}
+
+/**
+ * Convert Claude's markdown to WhatsApp-native formatting and extract any
+ * `@<phone>` mentions. Code-block regions are passed through untouched so
+ * phone-like sequences inside code aren't tagged.
+ */
+function formatWhatsApp(text: string): { text: string; mentions: string[] } {
+  const segments = splitProtectedRegions(text);
+  const mentions = new Set<string>();
+  const out = segments
+    .map(({ content, isProtected }) => {
+      if (isProtected) return content;
+      const transformed = transformForWhatsApp(content);
+      const { text: withMentions, mentions: found } = parseWhatsAppMentions(transformed);
+      for (const m of found) mentions.add(m);
+      return withMentions;
+    })
+    .join('');
+  return { text: out, mentions: [...mentions] };
+}
+
+/**
+ * Subset of a normalized Baileys message content carrying the message
+ * types that can host a `contextInfo.mentionedJid` array. Kept as a
+ * structural type so the helper (and its tests) don't pull in the full
+ * `proto.IMessage` shape just to construct fixtures.
+ */
+type MentionContextSource = {
+  extendedTextMessage?: { contextInfo?: { mentionedJid?: string[] | null } | null } | null;
+  imageMessage?: { contextInfo?: { mentionedJid?: string[] | null } | null } | null;
+  videoMessage?: { contextInfo?: { mentionedJid?: string[] | null } | null } | null;
+  documentMessage?: { contextInfo?: { mentionedJid?: string[] | null } | null } | null;
+};
+
+/**
+ * Detect an explicit @-mention of the bot in a WhatsApp group message.
+ * WhatsApp carries mentions in `contextInfo.mentionedJid` on the text +
+ * caption-bearing message types. Matches against both the bot's phone
+ * JID and LID — most modern clients emit the LID even when the human
+ * typed a phone-number mention.
+ *
+ * Exported for unit testing. The inbound construction site calls this
+ * to set `InboundMessage.isMention` for group messages (#2560). DMs are
+ * unconditionally mentions and don't go through this helper.
+ */
+export function isBotMentionedInGroup(
+  normalized: MentionContextSource,
+  botPhoneJid: string | undefined,
+  botLidUser: string | undefined,
+): boolean {
+  if (!botPhoneJid && !botLidUser) return false;
+  const mentionedJids: string[] = [
+    ...(normalized.extendedTextMessage?.contextInfo?.mentionedJid ?? []),
+    ...(normalized.imageMessage?.contextInfo?.mentionedJid ?? []),
+    ...(normalized.videoMessage?.contextInfo?.mentionedJid ?? []),
+    ...(normalized.documentMessage?.contextInfo?.mentionedJid ?? []),
+  ];
+  const botLidJid = botLidUser ? `${botLidUser}@lid` : undefined;
+  return mentionedJids.some((jid) => {
+    if (!jid) return false;
+    const bare = jid.split(':')[0];
+    return bare === botPhoneJid || bare === botLidJid;
+  });
+}
+
+/**
+ * Compute `InboundMessage.isMention` for a WhatsApp message:
+ *   - DMs are always mentions (router auto-engages on the bot's behalf).
+ *   - Group messages are mentions only when the bot is explicitly tagged.
+ *
+ * Returns `true | undefined` rather than `true | false` because the
+ * `InboundMessage` field is `isMention?: boolean` and downstream code
+ * treats `undefined` differently than an explicit `false` (#2560).
+ */
+export function computeIsMention(isGroup: boolean, botMentionedInGroup: boolean): true | undefined {
+  if (!isGroup) return true;
+  return botMentionedInGroup ? true : undefined;
+}
+
+/** Map file extension to Baileys media message type. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildMediaMessage(data: Buffer, filename: string, ext: string, caption?: string): any {
+  const imageExts = ['.jpg', '.jpeg', '.png', '.gif', '.webp'];
+  const videoExts = ['.mp4', '.mov', '.avi', '.mkv'];
+  const audioExts = ['.mp3', '.ogg', '.m4a', '.wav', '.aac', '.opus'];
+
+  if (imageExts.includes(ext)) {
+    return { image: data, caption, mimetype: `image/${ext.slice(1) === 'jpg' ? 'jpeg' : ext.slice(1)}` };
+  }
+  if (videoExts.includes(ext)) {
+    return { video: data, caption, mimetype: `video/${ext.slice(1)}` };
+  }
+  if (audioExts.includes(ext)) {
+    return { audio: data, mimetype: `audio/${ext.slice(1) === 'mp3' ? 'mpeg' : ext.slice(1)}` };
+  }
+  // Default: send as document
+  return { document: data, fileName: filename, caption, mimetype: 'application/octet-stream' };
+}
+
+registerChannelAdapter('whatsapp', {
+  factory: () => {
+    const env = readEnvFile(['WHATSAPP_PHONE_NUMBER', 'WHATSAPP_ENABLED']);
+    const phoneNumber = env.WHATSAPP_PHONE_NUMBER;
+    const authDir = AUTH_DIR;
+
+    // Skip if no existing auth, no phone number for pairing, and not explicitly enabled (QR mode)
+    const hasAuth = fs.existsSync(path.join(authDir, 'creds.json'));
+    if (!hasAuth && !phoneNumber && !env.WHATSAPP_ENABLED) return null;
+
+    fs.mkdirSync(authDir, { recursive: true });
+
+    // State
+    let sock: WASocket;
+    let connected = false;
+    let shuttingDown = false;
+    let setupConfig: ChannelSetup;
+
+    // LID → phone JID mapping (WhatsApp's new ID system)
+    const lidToPhoneMap: Record<string, string> = {};
+    let botLidUser: string | undefined;
+    let botPhoneJid: string | undefined;
+
+    // Outgoing queue for messages sent while disconnected
+    const outgoingQueue: Array<{ jid: string; text: string; mentions?: string[] }> = [];
+    let flushing = false;
+
+    // Sent message cache for retry/re-encrypt requests
+    const sentMessageCache = new Map<string, any>();
+
+    // Group metadata cache with TTL
+    const groupMetadataCache = new Map<string, { metadata: GroupMetadata; expiresAt: number }>();
+
+    // Pending questions: chatJid → { questionId, options }
+    // User replies with /approve, /reject, etc. to answer
+    const pendingQuestions = new Map<
+      string,
+      {
+        questionId: string;
+        options: NormalizedOption[];
+      }
+    >();
+
+    // Group sync tracking
+    let lastGroupSync = 0;
+    let groupSyncTimerStarted = false;
+
+    // First-connect promise
+    let resolveFirstOpen: (() => void) | undefined;
+    let rejectFirstOpen: ((err: Error) => void) | undefined;
+
+    // Pairing code file for the setup skill to poll
+    const pairingCodeFile = path.join(process.cwd(), 'store', 'pairing-code.txt');
+
+    // --- Helpers ---
+
+    function setLidPhoneMapping(lidUser: string, phoneJid: string): void {
+      if (lidToPhoneMap[lidUser] === phoneJid) return;
+      lidToPhoneMap[lidUser] = phoneJid;
+      // Cached group metadata depends on participant IDs — invalidate
+      groupMetadataCache.clear();
+    }
+
+    async function translateJid(jid: string, altJid?: string): Promise<string> {
+      if (!jid.endsWith('@lid')) return jid;
+      const lidUser = jid.split('@')[0].split(':')[0];
+
+      // 1. Check local cache
+      const cached = lidToPhoneMap[lidUser];
+      if (cached) return cached;
+
+      // 2. Use the alt JID from extractAddressingContext (v7 provides this
+      //    on every inbound message as remoteJidAlt / participantAlt)
+      if (altJid && !altJid.endsWith('@lid')) {
+        const phoneJid = altJid.includes('@') ? altJid : `${altJid}@s.whatsapp.net`;
+        setLidPhoneMapping(lidUser, phoneJid);
+        log.info('Translated LID via alt JID', { lidJid: jid, phoneJid });
+        return phoneJid;
+      }
+
+      // 3. Query Baileys v7 LID mapping store
+      try {
+        const pn = await sock.signalRepository.lidMapping.getPNForLID(jid);
+        if (pn) {
+          const phoneJid = `${pn.split('@')[0].split(':')[0]}@s.whatsapp.net`;
+          setLidPhoneMapping(lidUser, phoneJid);
+          log.info('Translated LID via signal repository', { lidJid: jid, phoneJid });
+          return phoneJid;
+        }
+      } catch (err) {
+        log.debug('Failed to resolve LID via signalRepository', { jid, err });
+      }
+
+      return jid;
+    }
+
+    async function getNormalizedGroupMetadata(jid: string): Promise<GroupMetadata | undefined> {
+      if (!jid.endsWith('@g.us')) return undefined;
+
+      const cached = groupMetadataCache.get(jid);
+      if (cached && cached.expiresAt > Date.now()) return cached.metadata;
+
+      const metadata = await sock.groupMetadata(jid);
+      const participants = await Promise.all(
+        metadata.participants.map(async (p) => ({
+          ...p,
+          id: await translateJid(p.id),
+        })),
+      );
+      const normalized = { ...metadata, participants };
+      groupMetadataCache.set(jid, {
+        metadata: normalized,
+        expiresAt: Date.now() + GROUP_METADATA_CACHE_TTL_MS,
+      });
+      return normalized;
+    }
+
+    async function syncGroupMetadata(force = false): Promise<void> {
+      if (!force && lastGroupSync && Date.now() - lastGroupSync < GROUP_SYNC_INTERVAL_MS) {
+        return;
+      }
+      try {
+        log.info('Syncing group metadata from WhatsApp...');
+        const groups = await sock.groupFetchAllParticipating();
+        let count = 0;
+        for (const [jid, metadata] of Object.entries(groups)) {
+          if (metadata.subject) {
+            setupConfig.onMetadata(jid, metadata.subject, true);
+            count++;
+          }
+        }
+        lastGroupSync = Date.now();
+        log.info('Group metadata synced', { count });
+      } catch (err) {
+        log.error('Failed to sync group metadata', { err });
+      }
+    }
+
+    async function flushOutgoingQueue(): Promise<void> {
+      if (flushing || outgoingQueue.length === 0) return;
+      flushing = true;
+      try {
+        log.info('Flushing outgoing message queue', { count: outgoingQueue.length });
+        while (outgoingQueue.length > 0) {
+          const item = outgoingQueue.shift()!;
+          const payload: { text: string; mentions?: string[] } = { text: item.text };
+          if (item.mentions && item.mentions.length > 0) payload.mentions = item.mentions;
+          const sent = await sock.sendMessage(item.jid, payload);
+          if (sent?.key?.id && sent.message) {
+            sentMessageCache.set(sent.key.id, sent.message);
+          }
+        }
+      } finally {
+        flushing = false;
+      }
+    }
+
+    /** Download media from an inbound message, save to /workspace/attachments/. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async function downloadInboundMedia(
+      msg: WAMessage,
+      normalized: any,
+    ): Promise<Array<{ type: string; name: string; localPath: string }>> {
+      const mediaTypes: Array<{ key: string; type: string; ext: string }> = [
+        { key: 'imageMessage', type: 'image', ext: '.jpg' },
+        { key: 'videoMessage', type: 'video', ext: '.mp4' },
+        { key: 'audioMessage', type: 'audio', ext: '.ogg' },
+        { key: 'documentMessage', type: 'document', ext: '' },
+      ];
+      const results: Array<{ type: string; name: string; localPath: string }> = [];
+      for (const { key, type, ext } of mediaTypes) {
+        if (!normalized[key]) continue;
+        try {
+          const buffer = await downloadMediaMessage(msg, 'buffer', {});
+          // documentMessage.fileName is attacker-controlled and rides through
+          // WhatsApp's E2E channel — Meta can't sanitize it server-side. Without
+          // this guard, a `..`-laden fileName escapes attachDir on path.join.
+          const rawFilename = normalized[key].fileName;
+          const fallback = `${type}-${Date.now()}${ext}`;
+          const filename = isSafeAttachmentName(rawFilename) ? rawFilename : fallback;
+          if (rawFilename && filename !== rawFilename) {
+            log.warn('Refused unsafe attachment filename — would escape attachments dir', {
+              rawFilename,
+              replacement: filename,
+            });
+          }
+          const attachDir = path.join(DATA_DIR, 'attachments');
+          fs.mkdirSync(attachDir, { recursive: true });
+          const filePath = path.join(attachDir, filename);
+          fs.writeFileSync(filePath, buffer);
+          results.push({ type, name: filename, localPath: `attachments/${filename}` });
+          log.info('Media downloaded', { type, filename });
+        } catch (err) {
+          log.warn('Failed to download media', { type, err });
+        }
+      }
+      return results;
+    }
+
+    async function sendRawMessage(jid: string, text: string, mentions?: string[]): Promise<string | undefined> {
+      if (!connected) {
+        outgoingQueue.push({ jid, text, mentions });
+        log.info('WA disconnected, message queued', { jid, queueSize: outgoingQueue.length });
+        return;
+      }
+      try {
+        const payload: { text: string; mentions?: string[] } = { text };
+        if (mentions && mentions.length > 0) payload.mentions = mentions;
+        const sent = await sock.sendMessage(jid, payload);
+        if (sent?.key?.id && sent.message) {
+          sentMessageCache.set(sent.key.id, sent.message);
+          if (sentMessageCache.size > SENT_MESSAGE_CACHE_MAX) {
+            const oldest = sentMessageCache.keys().next().value!;
+            sentMessageCache.delete(oldest);
+          }
+        }
+        return sent?.key?.id ?? undefined;
+      } catch (err) {
+        outgoingQueue.push({ jid, text, mentions });
+        log.warn('Failed to send, message queued', { jid, err, queueSize: outgoingQueue.length });
+        return undefined;
+      }
+    }
+
+    // --- Socket creation ---
+
+    async function connectSocket(): Promise<void> {
+      const { state, saveCreds } = await useMultiFileAuthState(authDir);
+
+      const version = await resolveWaWebVersion();
+
+      sock = makeWASocket({
+        version,
+        auth: {
+          creds: state.creds,
+          keys: makeCacheableSignalKeyStore(state.keys, baileysLogger),
+        },
+        printQRInTerminal: false,
+        logger: baileysLogger,
+        browser: Browsers.macOS('Chrome'),
+        cachedGroupMetadata: async (jid: string) => getNormalizedGroupMetadata(jid),
+        getMessage: async (key: WAMessageKey) => {
+          // Check in-memory cache first (recently sent messages)
+          const cached = sentMessageCache.get(key.id || '');
+          if (cached) return cached;
+          // Return empty message to prevent indefinite "waiting for this message"
+          return proto.Message.create({});
+        },
+      });
+
+      // Request pairing code only when there's no paired account yet.
+      //
+      // We can't use `state.creds.registered` here: Baileys 7.x doesn't
+      // reliably flip that flag back to `true` after the post-pair stream
+      // restart (statusCode 515). An already-paired socket would then see
+      // `registered=false` and request a *new* pairing code 3s after the
+      // restart, which the WhatsApp server rejects with 401 and the adapter
+      // wipes the auth directory — re-pair from scratch every restart.
+      //
+      // `state.creds.me` is set as part of the QR / pairing-code handshake
+      // and is the authoritative "this socket has an account" signal.
+      if (phoneNumber && !state.creds.me) {
+        setTimeout(async () => {
+          try {
+            const code = await sock.requestPairingCode(phoneNumber);
+            log.info(`WhatsApp pairing code: ${code}`);
+            log.info('Enter in WhatsApp > Linked Devices > Link with phone number');
+            fs.writeFileSync(pairingCodeFile, code, 'utf-8');
+          } catch (err) {
+            log.error('Failed to request pairing code', { err });
+          }
+        }, 3000);
+      }
+
+      sock.ev.on('connection.update', (update) => {
+        const { connection, lastDisconnect, qr } = update;
+
+        if (qr && !phoneNumber) {
+          // QR code auth — print to terminal
+          (async () => {
+            try {
+              const QRCode = await import('qrcode');
+              const qrText = await QRCode.toString(qr, { type: 'terminal' });
+              log.info('WhatsApp QR code — scan with WhatsApp > Linked Devices:\n' + qrText);
+            } catch {
+              log.info('WhatsApp QR code (raw)', { qr });
+            }
+          })();
+        }
+
+        if (connection === 'close') {
+          connected = false;
+          const reason = (lastDisconnect?.error as { output?: { statusCode?: number } })?.output?.statusCode;
+          // Don't auto-reconnect during shutdown — a parallel connectSocket()
+          // initializes useMultiFileAuthState which can truncate creds.json
+          // mid-write when the process exits, leaving a 0-byte creds file
+          // and forcing a fresh QR pairing on next start.
+          const shouldReconnect = !shuttingDown && reason !== DisconnectReason.loggedOut;
+
+          log.info('WhatsApp connection closed', { reason, shouldReconnect, shuttingDown });
+
+          if (shouldReconnect) {
+            log.info('Reconnecting...');
+            connectSocket().catch((err) => {
+              log.error('Failed to reconnect, retrying in 5s', { err });
+              setTimeout(() => {
+                connectSocket().catch((err2) => {
+                  log.error('Reconnection retry failed', { err: err2 });
+                });
+              }, RECONNECT_DELAY_MS);
+            });
+          } else if (reason === DisconnectReason.loggedOut) {
+            // Server-side logout (account unlinked, 401, etc.). Clear auth so
+            // the next start prompts for a fresh pair — stale creds would
+            // 401 again and risk WhatsApp's "can't link new devices now"
+            // cooldown.
+            log.info('WhatsApp logged out');
+            try {
+              fs.rmSync(authDir, { recursive: true, force: true });
+              fs.mkdirSync(authDir, { recursive: true });
+              log.info('WhatsApp auth cleared — set WHATSAPP_ENABLED=true and restart to re-link');
+            } catch (err) {
+              log.error('Failed to clear WhatsApp auth after logout', { err });
+            }
+            if (rejectFirstOpen) {
+              rejectFirstOpen(new Error('WhatsApp logged out'));
+              rejectFirstOpen = undefined;
+              resolveFirstOpen = undefined;
+            }
+          } else {
+            // Clean shutdown (shuttingDown=true) or a non-loggedOut disconnect
+            // that won't auto-reconnect. KEEP AUTH — the next process boot
+            // must be able to restore the session. Wiping here turned every
+            // `systemctl restart` into a forced re-pair, which is catastrophic
+            // when the bot phone is not in reach.
+            log.info('WhatsApp adapter stopped (auth preserved)');
+            if (rejectFirstOpen) {
+              rejectFirstOpen(new Error('WhatsApp adapter shutdown'));
+              rejectFirstOpen = undefined;
+              resolveFirstOpen = undefined;
+            }
+          }
+        } else if (connection === 'open') {
+          connected = true;
+          log.info('Connected to WhatsApp');
+
+          // Clean up pairing code file after successful connection
+          try {
+            if (fs.existsSync(pairingCodeFile)) fs.unlinkSync(pairingCodeFile);
+          } catch {
+            /* ignore */
+          }
+
+          // Announce availability for presence updates
+          sock.sendPresenceUpdate('available').catch((err) => {
+            log.warn('Failed to send presence update', { err });
+          });
+
+          // Build LID → phone mapping from auth state
+          if (sock.user) {
+            const phoneUser = sock.user.id.split(':')[0];
+            const lidUser = sock.user.lid?.split(':')[0];
+            botPhoneJid = `${phoneUser}@s.whatsapp.net`;
+            if (lidUser && phoneUser) {
+              setLidPhoneMapping(lidUser, botPhoneJid);
+              botLidUser = lidUser;
+            }
+          }
+
+          // Flush queued messages
+          flushOutgoingQueue().catch((err) => log.error('Failed to flush outgoing queue', { err }));
+
+          // Group sync
+          syncGroupMetadata().catch((err) => log.error('Initial group sync failed', { err }));
+          if (!groupSyncTimerStarted) {
+            groupSyncTimerStarted = true;
+            setInterval(() => {
+              syncGroupMetadata().catch((err) => log.error('Periodic group sync failed', { err }));
+            }, GROUP_SYNC_INTERVAL_MS);
+          }
+
+          // Signal first open
+          if (resolveFirstOpen) {
+            resolveFirstOpen();
+            resolveFirstOpen = undefined;
+            rejectFirstOpen = undefined;
+          }
+        }
+      });
+
+      sock.ev.on('creds.update', saveCreds);
+
+      // LID ↔ phone mapping updates (v7 replaces chats.phoneNumberShare)
+      sock.ev.on('lid-mapping.update', ({ lid, pn }) => {
+        const lidUser = lid?.split('@')[0].split(':')[0];
+        if (lidUser && pn) {
+          const phoneJid = pn.includes('@') ? pn : `${pn}@s.whatsapp.net`;
+          setLidPhoneMapping(lidUser, phoneJid);
+        }
+      });
+
+      // Inbound messages
+      sock.ev.on('messages.upsert', async ({ messages }) => {
+        for (const msg of messages) {
+          try {
+            if (!msg.message) continue;
+            const normalized = normalizeMessageContent(msg.message);
+            if (!normalized) continue;
+            const rawJid = msg.key.remoteJid;
+            if (!rawJid || rawJid === 'status@broadcast') continue;
+
+            // Translate LID → phone JID using v7's alt JID from extractAddressingContext
+            const chatJid = await translateJid(rawJid, msg.key.remoteJidAlt);
+
+            const timestamp = new Date(Number(msg.messageTimestamp) * 1000).toISOString();
+            const isGroup = chatJid.endsWith('@g.us');
+
+            // Notify metadata for group discovery
+            setupConfig.onMetadata(chatJid, undefined, isGroup);
+
+            let content =
+              normalized.conversation ||
+              normalized.extendedTextMessage?.text ||
+              normalized.imageMessage?.caption ||
+              normalized.videoMessage?.caption ||
+              '';
+
+            // Normalize bot LID mention → assistant name for trigger matching
+            if (botLidUser && content.includes(`@${botLidUser}`)) {
+              content = content.replace(`@${botLidUser}`, `@${ASSISTANT_NAME}`);
+            }
+
+            // Download media attachments (images, video, audio, documents)
+            const attachments = await downloadInboundMedia(msg, normalized);
+
+            // Skip empty protocol messages (no text and no attachments)
+            if (!content && attachments.length === 0) continue;
+
+            // Resolve sender: in groups, participant may be LID — use participantAlt
+            const rawSender = msg.key.participant || msg.key.remoteJid || '';
+            const sender = rawSender.endsWith('@lid')
+              ? await translateJid(rawSender, msg.key.participantAlt)
+              : rawSender;
+            const senderName = msg.pushName || sender.split('@')[0];
+            const fromMe = msg.key.fromMe || false;
+            // Filter bot's own messages to prevent echo loops.
+            // In self-chat (user messaging their own number), all messages have
+            // fromMe=true — use sentMessageCache to distinguish bot echoes from
+            // user-typed messages. For all other chats, the blanket fromMe
+            // filter is correct since the user's phone messages shouldn't wake
+            // the agent in third-party conversations.
+            if (fromMe) {
+              const isSelfChat = botPhoneJid && chatJid === botPhoneJid;
+              if (!isSelfChat) continue;
+              if (sentMessageCache.has(msg.key.id || '')) continue;
+            }
+
+            const isBotMessage = ASSISTANT_HAS_OWN_NUMBER ? false : content.startsWith(`${ASSISTANT_NAME}:`);
+
+            // Check if this reply answers a pending question via slash command
+            const pending = pendingQuestions.get(chatJid);
+            if (pending && content.startsWith('/')) {
+              const cmd = content.trim().toLowerCase();
+              const matched = pending.options.find((o) => optionToCommand(o.label) === cmd);
+              if (matched) {
+                const voterName = msg.pushName || sender.split('@')[0];
+                setupConfig.onAction(pending.questionId, matched.value, sender);
+                pendingQuestions.delete(chatJid);
+                await sendRawMessage(chatJid, `${matched.selectedLabel} by ${voterName}`);
+                log.info('Question answered', {
+                  questionId: pending.questionId,
+                  value: matched.value,
+                  voterName,
+                });
+                continue; // Don't forward this reply to the agent
+              }
+            }
+
+            // Detect explicit @-mentions of the bot in groups. Detail in
+            // isBotMentionedInGroup(); short version is contextInfo.mentionedJid
+            // on text + caption-bearing messages, matched against the bot's
+            // phone JID and LID (#2560).
+            const botMentionedInGroup = isGroup && isBotMentionedInGroup(normalized, botPhoneJid, botLidUser);
+
+            const inbound: InboundMessage = {
+              id: msg.key.id || `wa-${Date.now()}`,
+              kind: 'chat',
+              // DMs are addressed to the bot by definition. Mark them as
+              // platform-confirmed mentions so the router auto-creates an
+              // approval-required messaging_group when the chat is unknown,
+              // instead of silently dropping. In groups, only an explicit
+              // @-mention counts.
+              isMention: computeIsMention(isGroup, botMentionedInGroup),
+              isGroup,
+              content: {
+                text: content,
+                sender,
+                senderName,
+                ...(attachments.length > 0 && { attachments }),
+                fromMe,
+                isBotMessage,
+                isGroup,
+                chatJid,
+              },
+              timestamp,
+            };
+
+            // WhatsApp doesn't use threads — threadId is null
+            setupConfig.onInbound(chatJid, null, inbound);
+          } catch (err) {
+            log.error('Error processing incoming WhatsApp message', {
+              err,
+              remoteJid: msg.key?.remoteJid,
+            });
+          }
+        }
+      });
+    }
+
+    // --- ChannelAdapter implementation ---
+
+    const adapter: ChannelAdapter = {
+      name: 'whatsapp',
+      channelType: 'whatsapp',
+      supportsThreads: false,
+
+      async setup(hostConfig: ChannelSetup) {
+        setupConfig = hostConfig;
+
+        // Connect and wait for first open
+        await new Promise<void>((resolve, reject) => {
+          resolveFirstOpen = resolve;
+          rejectFirstOpen = reject;
+          connectSocket().catch(reject);
+        });
+
+        log.info('WhatsApp adapter initialized');
+      },
+
+      async deliver(
+        platformId: string,
+        _threadId: string | null,
+        message: OutboundMessage,
+      ): Promise<string | undefined> {
+        const content = message.content as Record<string, unknown>;
+
+        // Ask question → text with slash command replies
+        if (content.type === 'ask_question' && content.questionId && content.options) {
+          const questionId = content.questionId as string;
+          const title = content.title as string;
+          const question = content.question as string;
+          if (!title) {
+            log.error('ask_question missing required title — skipping delivery', { questionId });
+            return;
+          }
+          const options: NormalizedOption[] = normalizeOptions(content.options as never);
+
+          const optionLines = options.map((o) => `  ${optionToCommand(o.label)}`).join('\n');
+          const text = `*${title}*\n\n${question}\n\nReply with:\n${optionLines}`;
+          const msgId = await sendRawMessage(platformId, text);
+          if (msgId) {
+            pendingQuestions.set(platformId, { questionId, options });
+            if (pendingQuestions.size > PENDING_QUESTIONS_MAX) {
+              const oldest = pendingQuestions.keys().next().value!;
+              pendingQuestions.delete(oldest);
+            }
+          }
+          return msgId;
+        }
+
+        // Reaction → emoji on a message
+        if (content.operation === 'reaction' && content.messageId && content.emoji) {
+          try {
+            await sock.sendMessage(platformId, {
+              react: {
+                text: content.emoji as string,
+                key: { remoteJid: platformId, id: content.messageId as string, fromMe: false },
+              },
+            });
+          } catch (err) {
+            log.debug('Failed to send reaction', { platformId, err });
+          }
+          return;
+        }
+
+        // Normal message (with optional file attachments)
+        const text = (content.markdown as string) || (content.text as string);
+        const hasFiles = message.files && message.files.length > 0;
+
+        if (!text && !hasFiles) return;
+
+        // Send file attachments (first file gets the caption, rest are captionless)
+        if (hasFiles) {
+          let captionUsed = false;
+          for (const file of message.files!) {
+            try {
+              const ext = path.extname(file.filename).toLowerCase();
+              let caption: string | undefined;
+              let captionMentions: string[] | undefined;
+              if (!captionUsed && text) {
+                const formatted = formatWhatsApp(text);
+                caption = formatted.text;
+                captionMentions = formatted.mentions.length > 0 ? formatted.mentions : undefined;
+              }
+              const mediaMsg = buildMediaMessage(file.data, file.filename, ext, caption);
+              if (captionMentions) mediaMsg.mentions = captionMentions;
+              const sent = await sock.sendMessage(platformId, mediaMsg);
+              if (sent?.key?.id && sent.message) {
+                sentMessageCache.set(sent.key.id, sent.message);
+              }
+              if (caption) captionUsed = true;
+            } catch (err) {
+              log.error('Failed to send file', { platformId, filename: file.filename, err });
+            }
+          }
+          if (captionUsed) return; // Text was sent as caption
+        }
+
+        if (text) {
+          const { text: formatted, mentions } = formatWhatsApp(text);
+          const prefixed = ASSISTANT_HAS_OWN_NUMBER ? formatted : `${ASSISTANT_NAME}: ${formatted}`;
+          return sendRawMessage(platformId, prefixed, mentions);
+        }
+      },
+
+      async setTyping(platformId: string) {
+        try {
+          await sock.sendPresenceUpdate('composing', platformId);
+        } catch (err) {
+          log.debug('Failed to update typing status', { jid: platformId, err });
+        }
+      },
+
+      async teardown() {
+        shuttingDown = true;
+        connected = false;
+        sock?.end(undefined);
+        log.info('WhatsApp adapter shut down');
+      },
+
+      isConnected() {
+        return connected;
+      },
+
+      async syncConversations(): Promise<ConversationInfo[]> {
+        try {
+          const groups = await sock.groupFetchAllParticipating();
+          return Object.entries(groups)
+            .filter(([, m]) => m.subject)
+            .map(([jid, m]) => ({
+              platformId: jid,
+              name: m.subject,
+              isGroup: true,
+            }));
+        } catch (err) {
+          log.error('Failed to sync WhatsApp conversations', { err });
+          return [];
+        }
+      },
+    };
+
+    return adapter;
+  },
+});

src/platform-id.ts

@@ -9,15 +9,17 @@
  * will later emit as event.platformId, or router lookups miss and messages
  * get silently dropped.
  *
- * Native adapters (Signal, WhatsApp, iMessage) use their own ID formats and
- * send them as-is — no channel prefix. WhatsApp/iMessage emit JIDs/emails
- * containing '@'. Signal emits raw phone numbers ('+15551234567') for DMs
- * and 'group:<id>' for group chats. Prefixing any of these would cause a
- * mismatch with what the adapter later emits.
+ * Native adapters (Signal, WhatsApp, iMessage, DeltaChat) use their own ID
+ * formats and send them as-is — no channel prefix. WhatsApp/iMessage emit
+ * JIDs/emails containing '@'. Signal emits raw phone numbers ('+15551234567')
+ * for DMs and 'group:<id>' for group chats. DeltaChat emits numeric chat IDs
+ * ('12'). Prefixing any of these would cause a mismatch with what the adapter
+ * later emits.
  */
 export function namespacedPlatformId(channel: string, raw: string): string {
   if (raw.startsWith(`${channel}:`)) return raw;
   if (raw.includes('@')) return raw;
   if (raw.startsWith('+') || raw.startsWith('group:')) return raw;
+  if (channel === 'deltachat') return raw;
   return `${channel}:${raw}`;
 }

src/providers/codex-agents-md.test.ts

@@ -1,112 +0,0 @@
-/**
- * The 32KB Codex project-doc cap must DEGRADE, never throw: composeGroupAgentsMd
- * runs inside the provider contribution at every spawn, and a throw there rides
- * wakeContainer's transient-retry contract — host-sweep respawns every 60s
- * forever and the group goes silently dark (a permanent condition disguised as
- * a transient one). Oversized docs drop their largest optional instruction
- * sections, keep the core contract, and say so in the doc.
- */
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-vi.mock('../config.js', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('../config.js')>()),
-  DATA_DIR: '/tmp/nanoclaw-agents-md-test/data',
-}));
-
-import { composeGroupAgentsMd, CODEX_PROJECT_DOC_MAX_BYTES } from './codex-agents-md.js';
-import { closeDb, createAgentGroup, initTestDb, runMigrations } from '../db/index.js';
-import { ensureContainerConfig, updateContainerConfigJson } from '../db/container-configs.js';
-import type { AgentGroup } from '../types.js';
-
-const TEST_ROOT = '/tmp/nanoclaw-agents-md-test';
-
-function group(folder: string): AgentGroup {
-  return {
-    id: `ag-${folder}`,
-    name: folder,
-    folder,
-    agent_provider: null,
-    created_at: new Date().toISOString(),
-  } as AgentGroup;
-}
-
-describe('composeGroupAgentsMd cap handling', () => {
-  beforeEach(() => {
-    if (fs.existsSync(TEST_ROOT)) fs.rmSync(TEST_ROOT, { recursive: true });
-    fs.mkdirSync(path.join(TEST_ROOT, 'data'), { recursive: true });
-    const db = initTestDb();
-    runMigrations(db);
-  });
-
-  afterEach(() => {
-    closeDb();
-    if (fs.existsSync(TEST_ROOT)) fs.rmSync(TEST_ROOT, { recursive: true });
-  });
-
-  it('writes the doc untouched when under the cap', () => {
-    const g = group('small');
-    createAgentGroup(g);
-    ensureContainerConfig(g.id);
-    const groupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-'));
-    try {
-      composeGroupAgentsMd(g, groupDir);
-      const doc = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
-      expect(doc).not.toContain('Omitted for size');
-      // Agent-authored skills must be told their persistent home — without
-      // this, authored skills land on ephemeral container paths and vanish.
-      expect(doc).toContain('/workspace/agent/skills');
-      expect(Buffer.byteLength(doc, 'utf-8')).toBeLessThanOrEqual(CODEX_PROJECT_DOC_MAX_BYTES);
-    } finally {
-      fs.rmSync(groupDir, { recursive: true, force: true });
-    }
-  });
-
-  it('inlines the memory index so recall does not depend on a file read', () => {
-    const g = group('with-memory');
-    createAgentGroup(g);
-    ensureContainerConfig(g.id);
-    const groupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-'));
-    try {
-      fs.mkdirSync(path.join(groupDir, 'memory'), { recursive: true });
-      fs.writeFileSync(
-        path.join(groupDir, 'memory', 'index.md'),
-        '# Memory Index\n- [People](memories/people/) - notes about people and their preferences\n',
-      );
-
-      composeGroupAgentsMd(g, groupDir);
-
-      const doc = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
-      expect(doc).toContain('Current memory index');
-      expect(doc).toContain('notes about people and their preferences');
-    } finally {
-      fs.rmSync(groupDir, { recursive: true, force: true });
-    }
-  });
-
-  it('degrades instead of throwing when MCP instructions push the doc over the cap', () => {
-    const g = group('oversized');
-    createAgentGroup(g);
-    ensureContainerConfig(g.id);
-    updateContainerConfigJson(g.id, 'mcp_servers', {
-      bloated: { command: 'x', instructions: 'y'.repeat(CODEX_PROJECT_DOC_MAX_BYTES + 1024) },
-      lean: { command: 'x', instructions: 'short and useful' },
-    });
-    const groupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-md-'));
-    try {
-      composeGroupAgentsMd(g, groupDir); // must not throw
-
-      const doc = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
-      expect(Buffer.byteLength(doc, 'utf-8')).toBeLessThanOrEqual(CODEX_PROJECT_DOC_MAX_BYTES);
-      // Largest optional section dropped, named in the doc; the rest survive.
-      expect(doc).toContain('Omitted for size');
-      expect(doc).toContain('MCP Server: bloated');
-      expect(doc).toContain('short and useful');
-      expect(doc).toContain('Memory System');
-    } finally {
-      fs.rmSync(groupDir, { recursive: true, force: true });
-    }
-  });
-});

src/providers/codex-agents-md.ts

@@ -1,188 +0,0 @@
-/**
- * AGENTS.md composition for codex agent groups — codex-owned payload code.
- *
- * AGENTS.md is Codex's project doc (its CLAUDE.md equivalent). Composed fresh
- * on every spawn by the codex provider contribution (see ./codex.ts) from:
- *   - the shared base (`container/AGENTS.md`)
- *   - a pointer to the runner-scaffolded memory system (created container-side
- *     at boot via the `usesMemoryScaffold` capability — nothing is written here)
- *   - a pointer to codex-native skills under `.agents/skills`
- *   - each enabled NanoClaw module's `*.instructions.md` fragment
- *   - MCP server `instructions` from container.json
- *
- * Codex hard-caps project-doc loading (`project_doc_max_bytes`, mirrored in
- * the container provider's config.toml writer) — compose fails loudly rather
- * than letting Codex truncate silently.
- */
-import fs from 'fs';
-import path from 'path';
-
-import type { McpServerConfig } from '../container-config.js';
-import { getContainerConfig } from '../db/container-configs.js';
-import { log } from '../log.js';
-import type { AgentGroup } from '../types.js';
-
-export const CODEX_PROJECT_DOC_MAX_BYTES = 32 * 1024;
-export const CODEX_PROJECT_DOC_WARN_BYTES = 28 * 1024;
-
-const HEADER = '<!-- Composed at spawn. Do not edit. Edit memory/system/definition.md for memory behavior. -->';
-const MCP_TOOLS_HOST_SUBPATH = path.join('container', 'agent-runner', 'src', 'mcp-tools');
-
-const MEMORY_POINTER = [
-  'Editable memory-system definition: `/workspace/agent/memory/system/definition.md`.',
-  'Top memory index: `/workspace/agent/memory/index.md`.',
-  'Read the definition and index, then use memories, data, and conversation archives when relevant.',
-  'Stored user preferences are binding: before your first reply in a session, check the index below and read any memory file relevant to the user or the request, and apply it without being asked.',
-  'Do not use `AGENTS.local.md` or `AGENTS.override.md` for memory.',
-].join('\n\n');
-
-/**
- * Inline the group's current memory index into the composed doc. Recall must
- * not depend on the model choosing to read a file before its first reply —
- * with the map already in the system prompt, applying a stored preference is
- * one hop (read the relevant memory file), not three. The index is small
- * (hundreds of bytes); the 32KB fit logic above bounds the worst case.
- */
-function memoryIndexInline(groupDir: string): string {
-  const indexPath = path.join(groupDir, 'memory', 'index.md');
-  if (!fs.existsSync(indexPath)) return '';
-  const content = fs.readFileSync(indexPath, 'utf-8').trim();
-  if (!content) return '';
-  return ['Current memory index (paths relative to `/workspace/agent/memory/`):', content].join('\n\n');
-}
-
-const NATIVE_RUNTIME_SKILLS_POINTER = [
-  'Selected NanoClaw runtime skills are available as Codex-native skills at `/workspace/agent/.agents/skills`.',
-  'Each skill directory contains a `SKILL.md` with its trigger description plus any supporting files, and points to the read-only shared skill source under `/app/skills`.',
-  'Use skill discovery to load these skills only when their descriptions match the task. Full skill instructions live in the skill directories, not in `AGENTS.md`.',
-  'Skills YOU author or install yourself go in `/workspace/agent/skills/<name>/SKILL.md` — persistent, provider-neutral (they load under any agent provider this group runs on), and yours to write and update over time. They are linked into `$CODEX_HOME/skills` automatically at boot. Never write skills anywhere else: paths outside your workspace and `$CODEX_HOME` are ephemeral.',
-].join('\n\n');
-
-interface AgentsMdSection {
-  name: string;
-  content: string;
-}
-
-export function composeGroupAgentsMd(group: AgentGroup, groupDir: string): void {
-  if (!fs.existsSync(groupDir)) fs.mkdirSync(groupDir, { recursive: true });
-
-  const configRow = getContainerConfig(group.id);
-  const mcpServers: Record<string, McpServerConfig> = configRow
-    ? (JSON.parse(configRow.mcp_servers) as Record<string, McpServerConfig>)
-    : {};
-
-  const sections: AgentsMdSection[] = [{ name: 'header', content: HEADER }];
-  const pushSection = (name: string, ...content: string[]): void => {
-    const body = content
-      .map((part) => part.trim())
-      .filter(Boolean)
-      .join('\n\n');
-    if (body) sections.push({ name, content: `# ${name}\n\n${body}` });
-  };
-
-  const sharedBase = path.join(process.cwd(), 'container', 'AGENTS.md');
-  if (fs.existsSync(sharedBase)) {
-    pushSection('NanoClaw Runtime Contract', fs.readFileSync(sharedBase, 'utf-8'));
-  }
-
-  pushSection('Memory System', MEMORY_POINTER, memoryIndexInline(groupDir));
-  pushSection('Native Runtime Skills', NATIVE_RUNTIME_SKILLS_POINTER);
-
-  const cliDisabled = configRow?.cli_scope === 'disabled';
-  const mcpToolsHostDir = path.join(process.cwd(), MCP_TOOLS_HOST_SUBPATH);
-  if (fs.existsSync(mcpToolsHostDir)) {
-    for (const entry of fs.readdirSync(mcpToolsHostDir).sort()) {
-      const match = entry.match(/^(.+)\.instructions\.md$/);
-      if (!match) continue;
-      const moduleName = match[1];
-      if (moduleName === 'cli' && cliDisabled) continue;
-      pushSection(`NanoClaw Module: ${moduleName}`, fs.readFileSync(path.join(mcpToolsHostDir, entry), 'utf-8'));
-    }
-  }
-
-  for (const [name, mcp] of Object.entries(mcpServers)) {
-    if (mcp.instructions) {
-      pushSection(`MCP Server: ${name}`, mcp.instructions);
-    }
-  }
-
-  const content = fitAgentsMdToCap(group, sections);
-  writeAtomic(path.join(groupDir, 'AGENTS.md'), content);
-}
-
-function renderAgentsMd(sections: AgentsMdSection[]): string {
-  return (
-    sections
-      .map((section) => section.content.trim())
-      .filter(Boolean)
-      .join('\n\n') + '\n'
-  );
-}
-
-/**
- * Fit the doc under Codex's 32KB project-doc cap by DEGRADING, never
- * throwing: a per-spawn throw rides wakeContainer's transient-retry contract
- * — host-sweep respawns every 60s forever and the group goes silently dark.
- * Instead, drop the largest optional instruction sections (per-module and
- * per-MCP-server) until the doc fits, log what was dropped at error level,
- * and tell the agent in the doc itself. The core contract (header, runtime
- * contract, memory, skills pointer) is never dropped.
- */
-function fitAgentsMdToCap(group: AgentGroup, sections: AgentsMdSection[]): string {
-  const sectionBytes = (): { section: string; bytes: number }[] =>
-    sections.map((section) => ({ section: section.name, bytes: Buffer.byteLength(section.content, 'utf-8') }));
-
-  const isDroppable = (s: AgentsMdSection): boolean =>
-    s.name.startsWith('MCP Server: ') || s.name.startsWith('NanoClaw Module: ');
-
-  const dropped: string[] = [];
-  const render = (): string => {
-    const parts = [...sections];
-    if (dropped.length > 0) {
-      parts.push({
-        name: 'omitted',
-        content:
-          `# Omitted for size\n\nThese instruction sections were omitted to fit Codex's project-doc cap: ` +
-          `${dropped.join(', ')}. Their tools still work; consult each tool's own description.`,
-      });
-    }
-    return renderAgentsMd(parts);
-  };
-
-  let content = render();
-  while (Buffer.byteLength(content, 'utf-8') > CODEX_PROJECT_DOC_MAX_BYTES) {
-    const candidates = sections
-      .filter(isDroppable)
-      .sort((a, b) => Buffer.byteLength(b.content, 'utf-8') - Buffer.byteLength(a.content, 'utf-8'));
-    if (candidates.length === 0) break; // only core left — write oversized rather than brick the group
-    sections.splice(sections.indexOf(candidates[0]), 1);
-    dropped.push(candidates[0].name);
-    content = render();
-  }
-
-  const bytes = Buffer.byteLength(content, 'utf-8');
-  if (dropped.length > 0) {
-    log.error('AGENTS.md exceeded Codex project-doc cap — dropped largest instruction sections', {
-      group: group.name,
-      bytes,
-      maxBytes: CODEX_PROJECT_DOC_MAX_BYTES,
-      dropped,
-      sections: sectionBytes(),
-    });
-  } else if (bytes >= CODEX_PROJECT_DOC_WARN_BYTES) {
-    log.warn('AGENTS.md is near Codex project-doc cap', {
-      group: group.name,
-      bytes,
-      warnBytes: CODEX_PROJECT_DOC_WARN_BYTES,
-      maxBytes: CODEX_PROJECT_DOC_MAX_BYTES,
-      sections: sectionBytes(),
-    });
-  }
-  return content;
-}
-
-function writeAtomic(filePath: string, content: string): void {
-  const tmp = `${filePath}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, content);
-  fs.renameSync(tmp, filePath);
-}

src/providers/codex-host-contribution.test.ts

@@ -1,98 +0,0 @@
-/**
- * In-process seam test for the codex HOST contribution's runtime consumption
- * of core (the "consumes core" leg the skill guidelines require): drive the
- * REAL registered contribution — via the real barrel and registry, never by
- * importing codex.ts's internals — against a real test DB and a temp
- * GROUPS_DIR/DATA_DIR, then hand its result to the real buildMounts.
- *
- * This is what catches core drift that typecheck can't: the
- * DATA_DIR/v2-sessions/<id>/.codex-shared session layout, the
- * getAgentGroup/getContainerConfig reads, the mcp_servers JSON shape consumed
- * by composeGroupAgentsMd, and the mount set buildMounts assembles for a
- * surfaces-providing provider. (codex-registration.test.ts only guards that
- * the name is registered; provider-surfaces.test.ts drives a FAKE provider to
- * test the seam itself.)
- */
-import fs from 'fs';
-import path from 'path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-const TEST_ROOT = '/tmp/nanoclaw-codex-host-contribution-test';
-const DATA_DIR = path.join(TEST_ROOT, 'data');
-const GROUPS_DIR = path.join(TEST_ROOT, 'groups');
-
-vi.mock('../config.js', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('../config.js')>()),
-  DATA_DIR: '/tmp/nanoclaw-codex-host-contribution-test/data',
-  GROUPS_DIR: '/tmp/nanoclaw-codex-host-contribution-test/groups',
-}));
-
-import { buildMounts } from '../container-runner.js';
-import { closeDb, createAgentGroup, initTestDb, runMigrations } from '../db/index.js';
-import { ensureContainerConfig, updateContainerConfigJson } from '../db/container-configs.js';
-import { getProviderContainerConfig } from './provider-container-registry.js';
-import './index.js'; // the real host provider barrel
-import type { ContainerConfig } from '../container-config.js';
-import type { AgentGroup, Session } from '../types.js';
-
-function group(id: string, folder: string): AgentGroup {
-  return { id, name: folder, folder, agent_provider: null, created_at: new Date().toISOString() } as AgentGroup;
-}
-
-describe('codex host contribution against real core', () => {
-  beforeEach(() => {
-    fs.rmSync(TEST_ROOT, { recursive: true, force: true });
-    fs.mkdirSync(DATA_DIR, { recursive: true });
-    fs.mkdirSync(GROUPS_DIR, { recursive: true });
-    runMigrations(initTestDb());
-  });
-
-  afterEach(() => {
-    closeDb();
-    fs.rmSync(TEST_ROOT, { recursive: true, force: true });
-  });
-
-  it('creates the per-group state dir, composes AGENTS.md from the real config row, and mounts both', () => {
-    const ag = group('ag-codex', 'codex-group');
-    createAgentGroup(ag);
-    ensureContainerConfig(ag.id);
-    updateContainerConfigJson(ag.id, 'mcp_servers', {
-      tooling: { command: 'x', instructions: 'use the tooling server for builds' },
-    });
-    const groupDir = path.join(GROUPS_DIR, ag.folder);
-
-    const contributionFn = getProviderContainerConfig('codex');
-    expect(contributionFn).toBeDefined();
-    const contribution = contributionFn!({
-      sessionDir: path.join(DATA_DIR, 'v2-sessions', ag.id, 'session-1'),
-      agentGroupId: ag.id,
-      groupDir,
-      selectedSkills: [],
-      hostEnv: process.env,
-    });
-
-    // Per-group codex state dir exists and is mounted RW at ~/.codex.
-    const codexShared = path.join(DATA_DIR, 'v2-sessions', ag.id, '.codex-shared');
-    expect(fs.existsSync(codexShared)).toBe(true);
-    // OneCLI's auth-stub mountpoint is pre-created — on macOS Docker can't
-    // create a missing file mountpoint inside a virtiofs dir mount (exit 125
-    // on first spawn). Red here = the pre-create line was dropped.
-    expect(fs.existsSync(path.join(codexShared, 'auth.json'))).toBe(true);
-    const codexMount = contribution.mounts?.find((m) => m.containerPath === '/home/node/.codex');
-    expect(codexMount).toMatchObject({ hostPath: codexShared, readonly: false });
-
-    // AGENTS.md composed from the real DB row — MCP instructions included.
-    const agentsMd = fs.readFileSync(path.join(groupDir, 'AGENTS.md'), 'utf-8');
-    expect(agentsMd).toContain('MCP Server: tooling');
-    expect(agentsMd).toContain('use the tooling server for builds');
-
-    // The full mount set: codex surfaces in, default claude surfaces out.
-    const session = { id: 'session-1', agent_group_id: ag.id } as Session;
-    const config: ContainerConfig = { mcpServers: {}, packages: { apt: [], npm: [] }, additionalMounts: [], skills: [] };
-    const mounts = buildMounts(ag, session, config, 'codex', contribution);
-    const containerPaths = mounts.map((m) => m.containerPath);
-    expect(containerPaths).toContain('/home/node/.codex');
-    expect(containerPaths.some((p) => p.endsWith('AGENTS.md'))).toBe(true);
-    expect(containerPaths).not.toContain('/home/node/.claude');
-  });
-});