Merge upstream/main (templates) into feat/global-provider-default

Resolution: main replaced the generic `groups create` with a custom
handler (--template branch), removing the generic-create path our
afterCreate hook attached to. Re-seat the instance-default stamp as a
direct ensureContainerConfig(group.id) call in the bare-row handler,
and drop the now-userless afterCreate hook from crud.ts. Template
creation already calls ensureContainerConfig and inherits the default
through the chokepoint unchanged.

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

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

@@ -135,7 +135,22 @@ ncl groups restart --id <group-id>
 
 Switching is an operator action — run it from the host. Memory does NOT carry over automatically — each provider keeps its own store; run `/migrate-memory` to carry it across. See [docs/provider-migration.md](../../docs/provider-migration.md) for the carry-over table and rollback.
 
-There is no install-wide default provider. Setup's provider picker sets codex on the first agent it creates; creation itself is provider-agnostic (no `--provider` flag — provider is a DB property). Any group switches afterward via `ncl groups config update --provider` as above.
+### Default new groups to codex (optional)
+
+New groups are created on the **instance default** (`DEFAULT_AGENT_PROVIDER` in `.env`, or `claude` when unset). Installing this skill wires codex in but does NOT change that default — "installed" is not "authenticated", so the default stays claude until you opt in explicitly.
+
+After install, ask the operator before flipping it:
+
+> "Codex is installed. Default new agent groups to codex? Existing groups keep their current provider."
+
+On yes — set it, then restart the host so it takes effect:
+
+```bash
+pnpm exec tsx setup/index.ts --step set-env -- --key DEFAULT_AGENT_PROVIDER --value codex
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw   # macOS; Linux: systemctl --user restart nanoclaw
+```
+
+This affects only groups created afterward. Per-group `ncl groups config update --provider` still overrides the default in either direction. Creation itself stays provider-agnostic (no `--provider` flag — provider is a DB property stamped from the instance default at creation).
 
 ## Troubleshooting
 

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

@@ -46,7 +46,7 @@ import './discord.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/discord@4.27.0
+pnpm install @chat-adapter/discord@4.29.0
 ```
 
 ### 5. Build and validate

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

@@ -46,7 +46,7 @@ import './gchat.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/gchat@4.27.0
+pnpm install @chat-adapter/gchat@4.29.0
 ```
 
 ### 5. Build and validate

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

@@ -50,7 +50,7 @@ import './github.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/github@4.27.0
+pnpm install @chat-adapter/github@4.29.0
 ```
 
 ### 5. Build and validate

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

@@ -59,7 +59,7 @@ import './linear.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/linear@4.27.0
+pnpm install @chat-adapter/linear@4.29.0
 ```
 
 ### 5. Build and validate

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

@@ -46,7 +46,7 @@ import './slack.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/slack@4.27.0
+pnpm install @chat-adapter/slack@4.29.0
 ```
 
 ### 5. Build and validate

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

@@ -46,7 +46,7 @@ import './teams.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/teams@4.27.0
+pnpm install @chat-adapter/teams@4.29.0
 ```
 
 ### 5. Build and validate

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

@@ -60,7 +60,7 @@ In `setup/index.ts`, add this entry to the `STEPS` map (right after the `registe
 ### 5. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/telegram@4.27.0
+pnpm install @chat-adapter/telegram@4.29.0
 ```
 
 ### 6. Build and validate

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

@@ -46,7 +46,7 @@ import './whatsapp-cloud.js';
 ### 4. Install the adapter package (pinned)
 
 ```bash
-pnpm install @chat-adapter/whatsapp@4.27.0
+pnpm install @chat-adapter/whatsapp@4.29.0
 ```
 
 ### 5. Build and validate

.claude/skills/init-first-agent/SKILL.md

@@ -82,7 +82,7 @@ npx tsx scripts/init-first-agent.ts \
   --agent-name "${AGENT_NAME}"
 ```
 
-Add `--provider <name>` when the user picked a non-default provider (there is no install-wide default — the choice is explicit per group). Add `--welcome "System instruction: ..."` to override the default welcome prompt.
+The new group is created on the instance default provider (`DEFAULT_AGENT_PROVIDER` in `.env`, or `claude` when unset). To put it on a different provider, switch after creation with `ncl groups config update --id <group-id> --provider <name>`. Add `--welcome "System instruction: ..."` to override the default welcome prompt.
 
 The script:
 1. Upserts the `users` row and grants `owner` role if no owner exists.

.claude/skills/learn/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: learn
+description: "Distill a reusable skill from anything — a directory, a URL, pasted notes, or what you just did together — or refine an existing skill with new learnings. Use when the user says '/learn', 'learn this', 'turn this into a skill', 'capture this workflow', 'make a skill from <source>', or 'improve/update the <name> skill'. Produces or updates a .claude/skills/<name>/SKILL.md authored to NanoClaw's skill guidelines. (This CREATES or REFINES a skill from a source; it does not install existing skills from a registry.)"
+---
+
+# Learn — Distill a Skill from Anything
+
+Turn a source — a directory, a URL, pasted notes, or the work just done in this conversation — into a clean, reusable NanoClaw skill. The output is a new `.claude/skills/<name>/SKILL.md` (plus optional `scripts/`, `references/`, `templates/`) authored to the project's skill guidelines.
+
+This skill is **instruction-only**: it uses the tools you already have (`Read`, `Grep`, `Glob`, `WebFetch`, `Write`) — there is no separate distillation engine and no reach-ins into core code.
+
+## When to use
+
+Invoke when the user wants to *capture* a workflow as a reusable skill:
+
+- `/learn <path>` — read a project/dir and build a skill for working with it
+- `/learn <url>` — read docs / an API page and build a usage skill
+- `/learn what we just did` — distill the current conversation's workflow
+- `/learn` + pasted notes — turn notes into a structured skill
+
+If the user instead wants to *find and install* an existing community skill, that is a different task — this skill **creates** new skills, it does not import them.
+
+## Workflow
+
+### 1. Identify the source — and whether this is a new skill or a refine
+- A **path** → read the code/files.
+- A **URL** → fetch and read the page.
+- **"what we just did" / "this"** → use the current conversation as the source.
+- **Pasted text** → use it directly.
+
+Then check `.claude/skills/` for an existing skill that already covers this topic (the user may name it, e.g. *"update the wow-on-steam-deck skill"*, or the subject may obviously match one). **If one exists, this is a REFINE, not a fresh create** — go to step 4's "Refining" branch.
+
+If it is ambiguous what the skill should *do*, ask one clarifying question before proceeding.
+
+### 2. Gather the material
+- **Path:** `Glob` the structure, `Read` the key files, `Grep` for the important entry points. Read enough to understand the *repeatable procedure*, not every line.
+- **URL:** `WebFetch` the page; pull out the concrete commands/steps, not the prose.
+- **Conversation:** re-read what was actually done — the commands, the gotchas, the decisions — and keep the parts that generalize.
+
+### 3. Distill — find the reusable procedure
+Strip the one-off specifics; keep the *repeatable* shape. A good skill answers: *"Next time someone needs to do X, what are the exact steps, files, commands, and gotchas?"* Capture:
+
+- the trigger / when-to-use,
+- the step-by-step procedure (commands, file paths, decision points),
+- the non-obvious **gotchas** that were hit — usually the most valuable part,
+- any scripts or templates worth shipping alongside.
+
+### 4. Author the SKILL.md
+
+**Refining an existing skill?** First `Read` the current `.claude/skills/<name>/SKILL.md`, then *update it in place* — do not blindly overwrite:
+- Keep what is still correct; weave the new learnings into the right sections.
+- **Dedupe** — don't append a near-duplicate step or a second gotcha that says the same thing.
+- Correct anything the new source proves stale (a changed path, command, or flag).
+- Preserve the existing `name`/folder and overall structure; the diff should read as a focused improvement, not a rewrite.
+
+**New skill?** Write `.claude/skills/<kebab-name>/SKILL.md`.
+
+**Frontmatter (required):**
+
+```yaml
+---
+name: <kebab-case, matches the folder>
+description: "<what it does + when to use it + likely trigger phrases>"
+---
+```
+
+`description` is what the agent reads to decide relevance — make it concrete and include the phrases a user would actually say.
+
+**Body:** open with one paragraph on what the skill does, then a `## When to use` section and a `## Workflow` of numbered steps (the actual procedure). Use tables for command/file references, and add a short examples or troubleshooting section when the gotchas warrant it.
+
+**House authoring rules (from `docs/skill-guidelines.md`):**
+
+- **Additive, minimal reach-ins** — prefer adding files; make the *smallest possible* edit to existing code, and only via single-line calls into skill-owned functions.
+- **Instruction-only when possible** — if Claude can do it by following prose plus existing tools, ship no code. These are the easiest skills to maintain and to merge.
+- If apply leaves anything behind, ship a **`REMOVE.md`** that fully reverses every change (no soft-disabled/commented-out removals).
+- If the skill adds an integration point in core code, add a **test that goes red if the wiring is deleted or drifts**.
+- Anti-patterns to avoid: separate `VERIFY.md` files, incomplete cleanup, raw SQL against core DBs, branch merges (use additive fetch), hand-maintained duplicate copies.
+
+### 5. Place and verify
+- Write into `.claude/skills/<name>/`; confirm the folder name matches the `name` frontmatter and the YAML parses.
+- If feasible, dry-run the procedure the skill describes to confirm it is correct.
+- Tell the user the skill exists and how to invoke it (`/<name>`).
+
+## Example
+
+`/learn what we just did` after a multi-step setup:
+
+1. Re-read the conversation's commands and gotchas.
+2. Distill the repeatable procedure.
+3. Write `.claude/skills/<topic>-setup/SKILL.md` with the steps, file paths, and the gotchas hit along the way.
+4. Report: *"Created `/<topic>-setup` — invoke it next time to repeat this."*
+
+## Notes
+
+- Keep skills **focused** — one capability per skill (mirrors the project's "one change per PR" rule).
+- The most valuable content is the **gotchas**, not the happy path.
+- This skill is prose and safe to re-run — use it again to refine an existing skill.

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

@@ -67,7 +67,7 @@ pnpm exec tsx setup/index.ts --step register -- \
 
 The `register` step creates the agent group (reusing it if the folder already exists), the messaging group, and the wiring row. `createMessagingGroupAgent` auto-creates the companion `agent_destinations` row so the agent can address the channel by name.
 
-When creating a NEW agent group on a non-default provider, append `--provider <name>` (e.g. `--provider codex`) — there is no install-wide default; existing groups switch via `ncl groups config update --provider` instead.
+New agent groups are created on the instance default provider (`DEFAULT_AGENT_PROVIDER` in `.env`, or `claude` when unset). To run a group on a different provider, switch it after creation with `ncl groups config update --provider <name>` (e.g. `codex`).
 
 For separate agents, also ask for a folder name and optionally a different assistant name.
 

.claude/skills/update-nanoclaw/SKILL.md

@@ -233,7 +233,7 @@ Parse the diff output for lines that contain `[BREAKING]` anywhere in the line.
 ```
 
 If no `[BREAKING]` lines are found:
-- Skip this step silently. Proceed to Step 7 (skill updates check).
+- Skip this step silently. Proceed to Step 7.
 
 If one or more `[BREAKING]` lines are found:
 - Display a warning header to the user: "This update includes breaking changes that may require action:"
@@ -244,32 +244,42 @@ If one or more `[BREAKING]` lines are found:
   - "Skip — I'll handle these manually"
 - Set `multiSelect: true` so the user can pick multiple skills if there are several breaking changes.
 - For each skill the user selects, invoke it using the Skill tool.
-- After all selected skills complete (or if user chose Skip), proceed to Step 7 (skill updates check).
+- After all selected skills complete (or if user chose Skip), proceed to Step 7.
 
-# Step 7: Check for skill and channel/provider updates
+# Step 7: Skill updates (part of updating NanoClaw)
 
-## 7a: Skill branches
-Check if skills are distributed as branches in this repo:
-- `git branch -r --list 'upstream/skill/*'`
+Updating your installed skills is **part of** updating NanoClaw, not an optional
+extra. Channel and provider code ships on long-lived branches (`channels`,
+`providers`) that the host merge above doesn't touch — so stopping here leaves
+that code on whatever version you installed, which is how an important upstream
+fix gets silently left behind. The default is to continue into `/update-skills`,
+which re-applies your installed channels/providers to pull their latest code.
 
-If any `upstream/skill/*` branches exist:
-- Use AskUserQuestion to ask: "Upstream has skill branches. Would you like to check for skill updates?"
-  - Option 1: "Yes, check for updates" (description: "Runs /update-skills to check for and apply skill branch updates")
-  - Option 2: "No, skip" (description: "You can run /update-skills later any time")
-- If user selects yes, invoke `/update-skills` using the Skill tool.
+Detect whether anything is installed: read `src/channels/index.ts` and
+`src/providers/index.ts`, collecting `import './<name>.js';` lines (excluding
+`cli`).
 
-## 7b: Channel and provider updates
-Detect installed channels by reading `src/channels/index.ts` and collecting all `import './<name>.js';` lines (excluding `cli`). For providers, check `src/providers/index.ts` the same way.
+- If nothing is installed: skip silently and proceed to Step 7.9.
+- If one or more are installed: continue into skill updates.
 
-If any channels/providers are installed AND `upstream/channels` or `upstream/providers` branches exist:
-- List the installed channels/providers.
-- Use AskUserQuestion to ask: "Would you like to update your installed channels/providers? Re-running `/add-<name>` is safe — it only updates code files, credentials and wiring are untouched."
-  - One option per installed channel/provider (e.g., "Update Slack (/add-slack)")
-  - "Skip — I'll update them later"
-  - Set `multiSelect: true`
-- For each selected option, invoke the corresponding `/add-<channel>` or `/add-<provider>` skill.
+**Hand-off — default in, minimal opt-out.** Use AskUserQuestion (single-select).
+Name the installed skills in the question so the choice is concrete:
+- Question: "Skill updates are part of this NanoClaw update — your installed
+  channels/providers (<list the detected ones>) ride separate branches the host
+  update didn't touch. Continue into `/update-skills` to bring them up to date?"
+- Option 1 (Recommended): "Continue into skill updates" — description: "Runs
+  `/update-skills`, which re-applies your installed channels/providers to pull
+  their latest upstream code. You pick which ones there."
+- Option 2: "Skip — I'll run `/update-skills` myself later" — description: "Your
+  installed skill code stays as-is and may be behind upstream."
 
-If no channels/providers are installed, skip silently.
+Keep it to these two options — the per-skill selection lives inside
+`/update-skills`, not here.
+
+- On "Continue": invoke `/update-skills` using the Skill tool. (If the re-apply
+  touches container code, `/update-skills` rebuilds the agent image itself — see
+  its Step 4 — so nothing container-related is owed back here.)
+- On "Skip": note that `/update-skills` can be run anytime, then proceed.
 
 Proceed to Step 7.9.
 

.claude/skills/update-skills/SKILL.md

@@ -85,6 +85,7 @@ For each selected skill (process one at a time):
 After all selected skills are re-applied:
 - `pnpm run build`
 - `pnpm test` (do not fail the flow if tests are not configured)
+- If the re-apply changed any files under `container/` (`git diff --name-only -- container/` is non-empty), rebuild the agent image so new sessions pick up the new code: `./container/build.sh`. Skill code that lives in the container (e.g. a provider's runtime) keeps running the old image until this is done — the rebuild is what makes the fix live, not the file copy. If nothing under `container/` changed (e.g. only a channel adapter was re-applied), skip it.
 
 Each channel/provider skill copies in its own registration test; those run as part of `pnpm test` and assert the barrel still registers the adapter against the freshly fetched code.
 

CHANGELOG.md

@@ -4,11 +4,13 @@ All notable changes to NanoClaw will be documented in this file.
 
 ## [Unreleased]
 
+- **Optional per-container resource caps.** `CONTAINER_CPU_LIMIT` and `CONTAINER_MEMORY_LIMIT` pass through to `docker run` as `--cpus` / `--memory` (`container-runner.ts`). Both empty by default — no flag added, spawn args byte-identical to today — so existing installs are unaffected. Set them to cap an agent container's CPU/memory so one agent can't monopolize the host (e.g. `CONTAINER_CPU_LIMIT=2`, `CONTAINER_MEMORY_LIMIT=8g`). Swap is intentionally not managed here: `--memory` is a hard cap on a swapless host.
+- [BREAKING] **Chat SDK pinned to `4.29.0` (was `4.26.0` via `^4.24.0`).** `chat` and the `@chat-adapter/*` channel adapters are version-locked — the adapter's `ChatInstance` must match the bridge's, so a mismatched pair fails to typecheck at `createChatSdkBridge(...)`. `chat` is therefore pinned exactly, and the channel-adapter install pins move with it — the `/add-<channel>` SKILL.md steps and `setup/*.sh` scripts on `main`, plus the adapter code on the `channels` branch. Core installs with no channel (only `cli`) are unaffected. **Migration:** if any channel is installed (Slack, Discord, Telegram, Teams, …), re-run its `/add-<channel>` skill to pull the matching `4.29.0` adapter.
 - **Budget/billing-exhausted LLM turns now reach the user instead of being silently dropped.** When a turn ends in a non-retryable provider error (e.g. an Anthropic `403 billing_error`) with no `<message>` wrapping, the agent-runner delivers the provider's notice to the originating channel and stops re-nudging the failing gateway. `providers/claude.ts` now surfaces the SDK's `is_error` flag (and the error subtype's `errors[]` text); `poll-loop.ts` delivers that text and skips the re-wrap retry. Fixes the case where a spend-limit notice produced silence plus a turn-after-turn retry loop.
 - [BREAKING] **`@onecli-sh/sdk` 0.5.0 -> 2.2.1 — requires a OneCLI server with the `/v1` API** (older servers 404 every SDK call). The sanctioned gateway and CLI versions are pinned in `versions.json`. **The gateway is a separate component — updating NanoClaw does not upgrade it for you:** `/update-nanoclaw` upgrades it when the pin moves, otherwise upgrade manually. **Migration:** [docs/onecli-upgrades.md](docs/onecli-upgrades.md).
 - **New agent provider: Codex (OpenAI) — run `/add-codex`.** Full runtime via `codex app-server` (planning, MCP tools, server-side history, resume). Trunk ships the seams and the skill; the payload installs from the `providers` branch (the skill, the setup picker, or `--step provider-auth codex`). Auth is vault-only — no credential ever enters a container.
 - **Setup can now select, install, and authenticate a non-default agent provider.** A provider registry feeds the setup picker, an installer pulls the provider's payload from its branch, a vault auth walkthrough runs (`--step provider-auth`), and the picked provider is set on the first agent (a DB property) before its first spawn. Default (Claude) installs are unaffected — picking Claude changes nothing.
-- **Provider choice is explicit per group — no install-wide default.** Provider is a DB property set via `ncl groups config update --provider` + restart; creation is provider-agnostic.
+- **New groups inherit an instance-wide default provider.** `DEFAULT_AGENT_PROVIDER` in `.env` (default `claude`) sets which provider newly created agent groups get at creation; provider stays a per-group DB property, overridable via `ncl groups config update --provider` + restart. Existing groups are untouched — no migration, no retroactive flips.
 - **Memory migrates via `/migrate-memory`, never at runtime.** Each provider keeps its own store; fresh groups on a surfaces-owning provider see no stale `CLAUDE.*` files. See [docs/provider-migration.md](docs/provider-migration.md).
 - **Per-exchange archiving is provider-owned** — the `onExchangeComplete` hook; the markdown writer ships with the codex payload.
 - **Container boot failures now say why** — the last stderr lines are logged at `warn` on a non-zero exit instead of a silent crash loop.

CLAUDE.md

@@ -280,6 +280,7 @@ This project uses pnpm with `minimumReleaseAge: 4320` (3 days) in `pnpm-workspac
 | [docs/customizing.md](docs/customizing.md) | Short intro to customizing via skills |
 | [docs/skills-model.md](docs/skills-model.md) | The skills model in full: recipes, tests, upgrades, migrations |
 | [docs/skill-guidelines.md](docs/skill-guidelines.md) | Authoritative checklist for writing a skill |
+| [docs/templates.md](docs/templates.md) | Agent templates: what they are, stamping via `ncl groups create --template` + the setup wizard, the OneCLI/MCP-credential model, supported providers, and how to contribute one |
 
 ## Container Build Cache
 

CONTRIBUTING.md

@@ -125,6 +125,10 @@ Instructions here...
 - Put code in separate files, not inline in the markdown
 - See the [skills standard](https://code.claude.com/docs/en/skills) for all available frontmatter fields
 
+## Templates
+
+Agent templates (reusable bundles of instructions + MCP servers + skills) ship in the separate [`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates) repo, not this one. Contribute them there via PR (its README has the anatomy and checklist). For how templates load and the OneCLI credential model, see [docs/templates.md](docs/templates.md).
+
 ## Testing
 
 Test your contribution on a fresh clone before submitting. For skills, run the skill end-to-end and verify it works.

README.md

@@ -82,6 +82,7 @@ See [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md) for what's different an
 - **Web access** — search and fetch content from the web
 - **Container isolation** — agents are sandboxed in Docker (macOS/Linux/WSL2), with optional [Docker Sandboxes](docs/docker-sandboxes.md) micro-VM isolation or Apple Container as a macOS-native opt-in
 - **Credential security** — agents never hold raw API keys. Outbound requests route through [OneCLI's Agent Vault](https://github.com/onecli/onecli), which injects credentials at request time and enforces per-agent policies and rate limits.
+- **Agent templates**: stamp a ready-to-run agent (instructions + MCP tools + skills, no secrets) from a reusable bundle, via the setup wizard or `ncl groups create --template <ref>`. Load from the [public library](https://github.com/nanocoai/nanoclaw-templates), a local folder, or any git repo. See [docs/templates.md](docs/templates.md).
 
 ## Usage
 

container/agent-runner/bun.lock

@@ -5,8 +5,8 @@
     "": {
       "name": "nanoclaw-agent-runner",
       "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.3.170",
-        "@anthropic-ai/sdk": "^0.100.0",
+        "@anthropic-ai/claude-agent-sdk": "^0.3.197",
+        "@anthropic-ai/sdk": "^0.108.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "cron-parser": "^5.0.0",
         "zod": "^4.0.0",
@@ -19,25 +19,25 @@
     },
   },
   "packages": {
-    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.3.170", "", { "optionalDependencies": { "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.170", "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.170", "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.170", "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.170", "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.170", "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.170", "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.170", "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.170" }, "peerDependencies": { "@anthropic-ai/sdk": ">=0.93.0", "@modelcontextprotocol/sdk": "^1.29.0", "zod": "^4.0.0" } }, "sha512-pAvhfk+iTodXZ6RF18Kz7BEUWFjL7EcR3tKuhUNdPpE1NAYCR3mSHGbafi72JsrNwKEDIs7FU31z3fqhwy8QzA=="],
+    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.3.197", "", { "optionalDependencies": { "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.197", "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.197", "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.197", "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.197", "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.197", "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.197", "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.197", "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.197" }, "peerDependencies": { "@anthropic-ai/sdk": ">=0.93.0", "@modelcontextprotocol/sdk": "^1.29.0", "zod": "^4.0.0" } }, "sha512-XNIi8W1tb+QfMkcK+5kepOC6BsxG8wtupd72H+pIPzIJypVQhHy7FoX+KBMtTRYwtl+5dsjKyABhjWXebeUilw=="],
 
-    "@anthropic-ai/claude-agent-sdk-darwin-arm64": ["@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.170", "", { "os": "darwin", "cpu": "arm64" }, "sha512-rwfgArIa5WI0QPNqFsRBgvtSI0mrtpynUm0oK6+l6/KX4hcgnYGEzciZR1bOeD9/7sSZlTdIgt+T9alKeZmXcg=="],
+    "@anthropic-ai/claude-agent-sdk-darwin-arm64": ["@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.197", "", { "os": "darwin", "cpu": "arm64" }, "sha512-jC6WvH5Hr6APTfbMjo4nC6LlyMMqbpCMwiHXIw7/AsQXIHQhZ+cRRMesQlV6UFI1l3O53gLZHzsG9cXwfrPHKw=="],
 
-    "@anthropic-ai/claude-agent-sdk-darwin-x64": ["@anthropic-ai/claude-agent-sdk-darwin-x64@0.3.170", "", { "os": "darwin", "cpu": "x64" }, "sha512-0e58h8UQMtsQxLGIv9r4foxfBFWKZ7NeDtoplLhuD7EwQonehomw1sBXCch77t/IfUS+q5vQ5zv+fOGmap5nLQ=="],
+    "@anthropic-ai/claude-agent-sdk-darwin-x64": ["@anthropic-ai/claude-agent-sdk-darwin-x64@0.3.197", "", { "os": "darwin", "cpu": "x64" }, "sha512-ZQNvGkMrTyatBlHTIQ4w2i2aLBuvq355UP/FDLnVXIH8l23RsL1x/0w9P+dqB7EmY9OZi/cPxSrpskpo+dZWLA=="],
 
-    "@anthropic-ai/claude-agent-sdk-linux-arm64": ["@anthropic-ai/claude-agent-sdk-linux-arm64@0.3.170", "", { "os": "linux", "cpu": "arm64" }, "sha512-gLbaFqcGppFJQd4DLNV4IXoeahejT/p2/M8bSSvRDbla9GOsBr1AxV5XLRyBn1e7xFGozZIAIQr3+1chp7NJgQ=="],
+    "@anthropic-ai/claude-agent-sdk-linux-arm64": ["@anthropic-ai/claude-agent-sdk-linux-arm64@0.3.197", "", { "os": "linux", "cpu": "arm64" }, "sha512-pWhQgCtAft4EGM4Zn24HRad1a/k2u6oA+2uM/KCdjehfKtooDiHfMNd1yzXY/n9AEBWP0RHB2Vz3mJ30X2pVAg=="],
 
-    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": ["@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.3.170", "", { "os": "linux", "cpu": "arm64" }, "sha512-SRYfQcsXlOq+CD/FqkQBTSHbaD++w73GnnO+NUV9adLYrca3kfetRwWT1iguY1cNS0l34dCR3rlzCPq78vg1Jg=="],
+    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": ["@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.3.197", "", { "os": "linux", "cpu": "arm64" }, "sha512-VuIGXsLGK/aqSQ0tTBqqPVNzjefWS5SWnK8mlYyQitT4s5UDzHXJm0UZBTGxRtlcS0e2+QAHKwbGBCq1ZKSXjg=="],
 
-    "@anthropic-ai/claude-agent-sdk-linux-x64": ["@anthropic-ai/claude-agent-sdk-linux-x64@0.3.170", "", { "os": "linux", "cpu": "x64" }, "sha512-Xl/m7TaSC3T5IDBdHrZQ9fCQYyDmPELN34CL+MoyPIf7uSmuZnjE9fUOqDh2Rv26JxWssi1M6X+BBvVuKd6Cpg=="],
+    "@anthropic-ai/claude-agent-sdk-linux-x64": ["@anthropic-ai/claude-agent-sdk-linux-x64@0.3.197", "", { "os": "linux", "cpu": "x64" }, "sha512-AUccrbdcv4Hy/GteP/gYLjG/zDP+fe2BFtDMctEfRFVz40DazYDcOyW1+nIgSTQtxf5jSTAVVf3cNuXB2CZwlw=="],
 
-    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": ["@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.3.170", "", { "os": "linux", "cpu": "x64" }, "sha512-m4+I0qBEk7cxRKS+pL+eoWXbXTFOAo83fQ0tQvap4z/mDMm06IWJtEPoYTaMBwsp32GJWLkHWKbZSBCHZnp2DQ=="],
+    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": ["@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.3.197", "", { "os": "linux", "cpu": "x64" }, "sha512-3Tuy7XhD4UIKE4A4RPmKJcbL7Q/3dcB1hEWQt2lKP7c/DlixeEv+tRzvpnFZKhFX2hy0tkBk3QjkozSAacMC/w=="],
 
-    "@anthropic-ai/claude-agent-sdk-win32-arm64": ["@anthropic-ai/claude-agent-sdk-win32-arm64@0.3.170", "", { "os": "win32", "cpu": "arm64" }, "sha512-IG+8isJNNJKbnnhO7m+PGhfVCg+XoQ/MDxGde5eigFI0WsEfitjuWSWwx82bT9ghxI1aa6qNvI+UPgPcZuo5Fg=="],
+    "@anthropic-ai/claude-agent-sdk-win32-arm64": ["@anthropic-ai/claude-agent-sdk-win32-arm64@0.3.197", "", { "os": "win32", "cpu": "arm64" }, "sha512-Wx8uiAKBenDuL8lWQmrqnX5ppljaH5unQ9cKiCz2/9Kgf09dgnrwbX8n/FhndCZR8PmYw539eWwYVrSVc/bl6w=="],
 
-    "@anthropic-ai/claude-agent-sdk-win32-x64": ["@anthropic-ai/claude-agent-sdk-win32-x64@0.3.170", "", { "os": "win32", "cpu": "x64" }, "sha512-7cuqSKbHVItPGVwRbd3A0BEJwcNtc7Fhoh6qHN4C6yrmjSrvdYYx3MLvq/VI768/RoG7mAMDxb+j7WfEfoP9BA=="],
+    "@anthropic-ai/claude-agent-sdk-win32-x64": ["@anthropic-ai/claude-agent-sdk-win32-x64@0.3.197", "", { "os": "win32", "cpu": "x64" }, "sha512-ZXJO/VvR3SI4G0gwthWeFXWdHB5RXPu3rtfGRcKZ/YgtDeW17rQ+LZIJTk2ywzbLb8EvlghR5JPgn293hC179Q=="],
 
-    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.100.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-cAm3aXm6qAiHIvHxyIIGd6tVmsD2gDqlc2h0R20ijNUzGgVnIN822bit4mKbF6CkuV7qIrLQIPoAepHEpanrQQ=="],
+    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.108.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-XBnl7Nszpbzg0aLnOCmdBi0bOU5goAsQ/L+NPNiuUPowDj8Mbzx0vlIIc1M79BjIvmw5nUM5G3jbrCBStT/0fQ=="],
 
     "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
 

container/agent-runner/package.json

@@ -9,8 +9,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.170",
-    "@anthropic-ai/sdk": "^0.100.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.197",
+    "@anthropic-ai/sdk": "^0.108.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cron-parser": "^5.0.0",
     "zod": "^4.0.0"

container/cli-tools.json

@@ -1,5 +1,5 @@
 [
   { "name": "vercel", "version": "52.2.1" },
   { "name": "agent-browser", "version": "0.27.1", "onlyBuilt": true },
-  { "name": "@anthropic-ai/claude-code", "version": "2.1.170", "onlyBuilt": true }
+  { "name": "@anthropic-ai/claude-code", "version": "2.1.197", "onlyBuilt": true }
 ]

docs/SPEC.md

@@ -341,6 +341,12 @@ export const CONTAINER_IMAGE = process.env.CONTAINER_IMAGE || 'nanoclaw-agent:la
 export const CONTAINER_TIMEOUT = parseInt(process.env.CONTAINER_TIMEOUT || '1800000', 10); // 30min default
 export const IDLE_TIMEOUT = parseInt(process.env.IDLE_TIMEOUT || '1800000', 10); // 30min — keep container alive after last result
 export const MAX_CONCURRENT_CONTAINERS = Math.max(1, parseInt(process.env.MAX_CONCURRENT_CONTAINERS || '5', 10) || 5);
+// Per-container resource caps → `docker run --cpus/--memory`. Empty default =
+// no flag = unbounded (today's behavior). Opt in to bound a fleet sharing one
+// host: CONTAINER_CPU_LIMIT=2, CONTAINER_MEMORY_LIMIT=8g. Swap is a host concern
+// (run the host swapless to make --memory a hard cap); not managed here.
+export const CONTAINER_CPU_LIMIT = process.env.CONTAINER_CPU_LIMIT || '';
+export const CONTAINER_MEMORY_LIMIT = process.env.CONTAINER_MEMORY_LIMIT || '';
 
 export const TRIGGER_PATTERN = new RegExp(`^@${ASSISTANT_NAME}\\b`, 'i');
 ```

docs/templates.md

@@ -0,0 +1,177 @@
+# Agent Templates
+
+A **template** is a reusable folder you stamp into a working agent group: it
+carries the agent's standing instructions, its MCP tool servers, and its skills,
+but **no secrets and no provider**. Point `ncl` (or the setup wizard) at one and
+you get a configured agent in seconds; you choose the runtime/provider
+separately.
+
+Templates are purely additive: no DB migration, no new dependency. **At runtime,
+templates are resolved only from a local directory**: `templates/` at the
+project root by default (committed but shipped empty), or whatever
+`NANOCLAW_TEMPLATES_DIR` points at (a local path only). The setup wizard can also
+discover templates from the public registry
+([`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates))
+and copy a chosen one into your local `templates/` before stamping.
+
+## Using a template
+
+**During install.** `bash nanoclaw.sh` opens the setup wizard. Choose **Template
+setup**, then either **NanoClaw template library** (clones the public registry,
+copies the template you pick into your local `templates/`) or **Local templates**
+(lists what's already in `templates/`). The normal auth step then picks the
+runtime, and the wizard stamps and wires your first agent.
+
+**Anytime, via the CLI:**
+
+```bash
+ncl groups create --template sales/sdr --name "SDR Agent"
+```
+
+This stamps the group but does **not** wire it to a channel. Run
+`/manage-channels` (or `ncl wirings create`) afterward, exactly as for a
+hand-built group.
+
+### The template ref
+
+`--template <ref>` is a path **relative to the local templates directory**
+(`templates/` by default, or `NANOCLAW_TEMPLATES_DIR`). Refs are multi-segment,
+e.g. `sales/sdr` → `templates/sales/sdr`.
+
+For safety the ref must stay inside the templates directory: absolute paths, a
+leading `~`, and `../` escapes are rejected. There is no `--source`, no git URL,
+and no remote fetch at `ncl` time. Populate `templates/` first (by hand, or via
+the setup wizard's library option), then stamp.
+
+`NANOCLAW_TEMPLATES_DIR` may point the library at another **local** directory; it
+is never a URL and never changes at runtime.
+
+## What's in a template
+
+The full authoring reference lives in the
+[templates repo README](https://github.com/nanocoai/nanoclaw-templates#anatomy-of-a-template).
+The short version: only `context/instructions.md` is required; everything else
+is optional and defaults sensibly:
+
+```
+<template>/
+├── context/
+│   ├── instructions.md        # REQUIRED: the agent's standing persona; marks the folder as a template
+│   └── additional_context/    # optional: extra .md files, referenced from instructions.md by relative path
+│       └── *.md
+├── .mcp.json             # optional: MCP servers (command + args), NO secrets
+├── skills/<name>/        # optional: one folder per skill (SKILL.md + any references/), copied whole
+└── README.md             # recommended: per-template docs
+```
+
+| Path | Loaded as | Required |
+|------|-----------|----------|
+| `context/instructions.md` | The agent's persona, prepended to its `CLAUDE.md`/`AGENTS.md` every spawn (system-prompt tier, any provider) | **Yes** |
+| `context/**/*.md` (others) | Extra context, copied into the agent's workspace with the same layout relative to `instructions.md` | No |
+| `.mcp.json` → `mcpServers` | MCP tool servers (written verbatim to container config) | No |
+| `skills/<name>/` | A skill, auto-triggered by its `description` | No |
+
+Notes:
+
+- **No provider, model, effort, or packages in a template.** Those are set on
+  the agent later via `ncl groups config update`. The runtime defaults to the
+  install's configured provider.
+- **Keep `instructions.md` focused (under ~200 lines).** It's always in the
+  agent's prompt, and some providers cap that doc (Codex ~32 KB), so an over-long
+  persona gets truncated. Put bulk material in `skills/` or extra context files instead.
+- Skills are copied into the agent's own skills overlay, keyed to that group,
+  never shared across groups.
+
+### Referencing extra context files
+
+Extra `.md` files under `context/` (by convention in an `additional_context/`
+subfolder) are copied into the agent's workspace preserving their position
+relative to `instructions.md` — a template file at
+`context/additional_context/pricing.md` is readable by the agent as
+`additional_context/pricing.md`, the same relative path you'd use from
+`instructions.md` itself. Nothing is injected automatically: the agent only
+reads an extra file if `instructions.md` points to it, so reference every file
+you ship.
+
+```markdown
+Pricing rules live in `additional_context/pricing.md`. Read it before quoting a price.
+```
+
+Context files are copied when you stamp, so files added to the template later
+won't reach an already-created agent. Re-stamp the same name to update it.
+
+## MCP servers and credentials
+
+**Templates declare MCP servers, not secrets.** `.mcp.json` carries `command` +
+`args` only:
+
+```json
+{
+  "mcpServers": {
+    "hubspot": { "command": "npx", "args": ["-y", "@hubspot/mcp-server"] },
+    "exa":     { "command": "npx", "args": ["-y", "exa-mcp-server"] }
+  }
+}
+```
+
+Credentials are held by the **credentials proxy** and injected into outbound
+HTTPS calls at the proxy boundary, matched by API host, at request time. The key
+never sits in `.mcp.json`, the container env, or chat context. See
+[the credentials proxy section in CLAUDE.md](../CLAUDE.md#secrets--credentials--onecli)
+for the model.
+
+Two ways a credential gets connected:
+
+1. **Up front.** Register the secret with the credentials proxy (its web UI or
+   CLI), matched to the service's API host (e.g. `api.example.com`). Matching
+   credentials are injected automatically, so usually nothing else is needed.
+2. **On demand (the common path).** Don't set anything up first. The first time
+   the agent calls a service with no credential, the API returns **401/403** and
+   the agent replies with a prefilled connect link for that host. The user opens
+   it, pastes the key, and asks the agent to retry. The key lands in the
+   credentials proxy, which injects it on every later call.
+
+### MCP servers that require an env var to boot
+
+Some MCP servers refuse to start unless an env var is *present*, even though the
+real credential should come from the credentials proxy, not the env. Because `.mcp.json`'s `env`
+block passes through verbatim to the agent's container config, put a **placeholder
+value** there to satisfy the boot check:
+
+```json
+{
+  "mcpServers": {
+    "acme": {
+      "command": "npx",
+      "args": ["-y", "@acme/mcp-server"],
+      "env": { "ACME_API_KEY": "placeholder" }
+    }
+  }
+}
+```
+
+The server starts; its real outbound calls are still authenticated by the
+credentials proxy. **Never put a real key in `env`**: a placeholder only, and only when
+the server won't boot without one.
+
+### Approval-gating sensitive actions
+
+The credentials proxy can *hold* a credentialed outbound request and require a
+human to approve it before it leaves the proxy: enforcement the agent can't talk
+around. This is matched on the outbound HTTP request (host + method + path),
+configured on the credentials proxy, and answered by NanoClaw (it DMs an approver). The host side is
+already wired; see
+[the credentialed-approval flow in CLAUDE.md](../CLAUDE.md#requiring-approval-for-credential-use)
+and the [`sales/sdr` template README](https://github.com/nanocoai/nanoclaw-templates/blob/main/sales/sdr/README.md)
+for a worked example.
+
+## Contributing a template
+
+Templates ship in the separate
+[`nanocoai/nanoclaw-templates`](https://github.com/nanocoai/nanoclaw-templates)
+repo, not this one. To add one: fork that repo, drop a folder at
+`<category>/<template>/` with at least `context/instructions.md`, test it end to
+end (copy it under `templates/` and run
+`ncl groups create --template <category>/<template> --name Test`), confirm
+no secrets are committed, and open a PR. The repo's README has the full anatomy,
+category conventions, and checklist.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "nanoclaw",
-  "version": "2.1.18",
+  "version": "2.1.24",
   "description": "Personal Claude assistant. Lightweight, secure, customizable.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
@@ -32,7 +32,7 @@
     "@clack/prompts": "^1.2.0",
     "@onecli-sh/sdk": "2.2.1",
     "better-sqlite3": "11.10.0",
-    "chat": "^4.24.0",
+    "chat": "4.29.0",
     "cron-parser": "5.5.0",
     "kleur": "^4.1.5"
   },

pnpm-lock.yaml

@@ -21,8 +21,8 @@ importers:
         specifier: 11.10.0
         version: 11.10.0
       chat:
-        specifier: ^4.24.0
-        version: 4.26.0
+        specifier: 4.29.0
+        version: 4.29.0
       cron-parser:
         specifier: 5.5.0
         version: 5.5.0
@@ -609,8 +609,17 @@ packages:
   character-entities@2.0.2:
     resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
 
-  chat@4.26.0:
-    resolution: {integrity: sha512-QToDnIEGpyb8yQA6YLMHOSRK30YVk4RtsyFyuWFYyB2c4jQlyIrSWtwVK7qyvmvqzQp9uDwCdJRAhS8GtCHAGQ==}
+  chat@4.29.0:
+    resolution: {integrity: sha512-KdPfzaie5ivYytyRICTERg5xT+LeCbYefokvNAqTHe92eqkFaoTMXXkSitikxJVWhZIb2YoXF1b9UZHyzSzKzw==}
+    engines: {node: '>=20'}
+    peerDependencies:
+      ai: ^6.0.182
+      zod: ^3.0.0 || ^4.0.0
+    peerDependenciesMeta:
+      ai:
+        optional: true
+      zod:
+        optional: true
 
   chownr@1.1.4:
     resolution: {integrity: sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==}
@@ -1963,7 +1972,7 @@ snapshots:
 
   character-entities@2.0.2: {}
 
-  chat@4.26.0:
+  chat@4.29.0:
     dependencies:
       '@workflow/serde': 4.1.0-beta.2
       mdast-util-to-string: 4.0.0

repo-tokens/badge.svg

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

scripts/init-cli-agent.ts

@@ -21,7 +21,6 @@ import path from 'path';
 
 import { DATA_DIR } from '../src/config.js';
 import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
-import { updateContainerConfigScalars } from '../src/db/container-configs.js';
 import { initDb } from '../src/db/connection.js';
 import {
   createMessagingGroup,
@@ -124,11 +123,11 @@ async function main(): Promise<void> {
       `# ${args.agentName}\n\n` +
       `You are ${args.agentName}, a personal NanoClaw agent for ${args.displayName}. ` +
       'When the user first reaches out, introduce yourself briefly and invite them to chat. Keep replies concise.',
+    // The operator's setup pick (NANOCLAW_PICKED_PROVIDER) when set; otherwise
+    // undefined, so initGroupFilesystem falls back to the instance default and
+    // stamps it onto the fresh config row.
+    provider: pickedProvider,
   });
-  // Runtime provider lives on the config row, not the deprecated agent_provider.
-  if (pickedProvider && pickedProvider !== 'claude') {
-    updateContainerConfigScalars(ag.id, { provider: pickedProvider });
-  }
 
   // 3. CLI messaging group + wiring.
   let cliMg: MessagingGroup | undefined = getMessagingGroupByPlatform(CLI_CHANNEL, CLI_PLATFORM_ID);

scripts/init-first-agent.ts

@@ -205,15 +205,13 @@ async function main(): Promise<void> {
   } else {
     console.log(`Reusing agent group: ${ag.id} (${folder})`);
   }
-  // Ensure the config row exists; defer workspace scaffolding to the first
-  // spawn (group-init), where the DB-resolved provider decides the surface
-  // (Claude: CLAUDE.local.md; a surfaces-owning provider: the memory scaffold)
-  // — so a non-Claude group never gets stale CLAUDE.* files written here.
-  ensureContainerConfig(ag.id);
-  // Runtime provider lives on the config row, not the deprecated agent_provider.
-  if (pickedProvider && pickedProvider !== 'claude') {
-    updateContainerConfigScalars(ag.id, { provider: pickedProvider });
-  }
+  // Seed the config row, stamped with the effective provider: the operator's
+  // setup pick (NANOCLAW_PICKED_PROVIDER) when this runs inside a setup run,
+  // otherwise the persisted instance default. Workspace scaffolding is deferred
+  // to the first spawn (group-init), where the DB-resolved provider decides the
+  // surface (Claude: CLAUDE.local.md; a surfaces-owning provider: the memory
+  // scaffold). A reused group keeps its provider (INSERT OR IGNORE).
+  ensureContainerConfig(ag.id, pickedProvider);
   const groupDir = path.resolve(GROUPS_DIR, folder);
   fs.mkdirSync(groupDir, { recursive: true });
   fs.writeFileSync(

setup/add-discord.sh

@@ -15,7 +15,7 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$PROJECT_ROOT"
 
 # Keep in sync with .claude/skills/add-discord/SKILL.md.
-ADAPTER_VERSION="@chat-adapter/discord@4.26.0"
+ADAPTER_VERSION="@chat-adapter/discord@4.29.0"
 
 # Resolve which remote carries the channels branch — handles forks where
 # upstream lives on a different remote than `origin`.

setup/add-slack.sh

@@ -1,10 +1,11 @@
 #!/usr/bin/env bash
 #
-# Install the Slack adapter, persist SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET to
+# Install the Slack adapter, persist SLACK_BOT_TOKEN plus the mode-specific
+# secret (SLACK_APP_TOKEN for Socket Mode, SLACK_SIGNING_SECRET for webhook) to
 # .env + data/env/env, and restart the service. Non-interactive — the
 # operator-facing app creation walkthrough + credential paste live in
 # setup/channels/slack.ts. Credentials come in via env vars:
-# SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET.
+# SLACK_BOT_TOKEN, and SLACK_APP_TOKEN and/or SLACK_SIGNING_SECRET.
 #
 # Emits exactly one status block on stdout (ADD_SLACK) at the end. All chatty
 # progress messages go to stderr so setup:auto's raw-log capture sees the full
@@ -15,7 +16,7 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$PROJECT_ROOT"
 
 # Keep in sync with .claude/skills/add-slack/SKILL.md.
-ADAPTER_VERSION="@chat-adapter/slack@4.26.0"
+ADAPTER_VERSION="@chat-adapter/slack@4.29.0"
 
 # Resolve which remote carries the channels branch — handles forks where
 # upstream lives on a different remote than `origin`.
@@ -41,8 +42,10 @@ if [ -z "${SLACK_BOT_TOKEN:-}" ]; then
   emit_status failed "SLACK_BOT_TOKEN env var not set"
   exit 1
 fi
-if [ -z "${SLACK_SIGNING_SECRET:-}" ]; then
-  emit_status failed "SLACK_SIGNING_SECRET env var not set"
+# Socket Mode authenticates with SLACK_APP_TOKEN; webhook mode with
+# SLACK_SIGNING_SECRET. Require at least one.
+if [ -z "${SLACK_APP_TOKEN:-}" ] && [ -z "${SLACK_SIGNING_SECRET:-}" ]; then
+  emit_status failed "Set SLACK_APP_TOKEN (Socket Mode) or SLACK_SIGNING_SECRET (webhook)"
   exit 1
 fi
 
@@ -98,7 +101,12 @@ upsert_env() {
   fi
 }
 upsert_env SLACK_BOT_TOKEN "$SLACK_BOT_TOKEN"
-upsert_env SLACK_SIGNING_SECRET "$SLACK_SIGNING_SECRET"
+if [ -n "${SLACK_APP_TOKEN:-}" ]; then
+  upsert_env SLACK_APP_TOKEN "$SLACK_APP_TOKEN"
+fi
+if [ -n "${SLACK_SIGNING_SECRET:-}" ]; then
+  upsert_env SLACK_SIGNING_SECRET "$SLACK_SIGNING_SECRET"
+fi
 
 # Container reads from data/env/env (the host mounts it).
 mkdir -p data/env

setup/add-teams.sh

@@ -18,7 +18,7 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$PROJECT_ROOT"
 
 # Keep in sync with .claude/skills/add-teams/SKILL.md.
-ADAPTER_VERSION="@chat-adapter/teams@4.26.0"
+ADAPTER_VERSION="@chat-adapter/teams@4.29.0"
 
 # Resolve which remote carries the channels branch — handles forks where
 # upstream lives on a different remote than `origin`.

setup/add-telegram.sh

@@ -15,7 +15,7 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$PROJECT_ROOT"
 
 # Keep in sync with .claude/skills/add-telegram/SKILL.md.
-ADAPTER_VERSION="@chat-adapter/telegram@4.26.0"
+ADAPTER_VERSION="@chat-adapter/telegram@4.29.0"
 
 # Resolve which remote carries the channels branch — handles forks where
 # upstream lives on a different remote than `origin`.

setup/auto.ts

@@ -12,6 +12,8 @@
  *   NANOCLAW_AGENT_NAME    messaging-channel agent name (consumed by the
  *                          channel flow). The CLI scratch agent is always
  *                          "Terminal Agent".
+ *   NANOCLAW_AGENT_PROVIDER preselect the setup provider and skip the picker
+ *                          (for packaged flows). Example: claude.
  *   NANOCLAW_SKIP          comma-separated step names to skip
  *                          (environment|container|onecli|auth|mounts|
  *                           service|cli-agent|timezone|channel|
@@ -44,6 +46,7 @@ import './providers/index.js';
 import { brightSelect } from './lib/bright-select.js';
 import { offerClaudeOnFailure } from './lib/claude-handoff.js';
 import { setPickedProvider } from './lib/picked-provider.js';
+import { upsertEnvVar } from './set-env.js';
 import {
   applyToEnv,
   parseFlags,
@@ -63,6 +66,7 @@ import { ensureAnswer, fail, runQuietChild, runQuietStep, spawnQuiet } from './l
 import { emit as phEmit } from './lib/diagnostics.js';
 import { accentGreen, brandBody, brandBold, brandChip, dimWrap, fitToWidth, fmtDuration, note, wrapForGutter } from './lib/theme.js';
 import { isValidTimezone } from '../src/timezone.js';
+import { DEFAULT_AGENT_PROVIDER } from '../src/config.js';
 
 const CLI_AGENT_NAME = 'Terminal Agent';
 const RUN_START = Date.now();
@@ -373,6 +377,12 @@ async function main(): Promise<void> {
     } else {
       await runAuthStep();
     }
+    // Persist the pick as the instance-wide default so every future group
+    // (channel-approved, ncl-created) is created on this provider. Read from
+    // .env at host start; per-group `ncl groups config update --provider` wins.
+    // Only after install + auth succeeded — a failed setup must not leave new
+    // groups defaulting to an unauthenticated runtime.
+    upsertEnvVar('DEFAULT_AGENT_PROVIDER', agentProvider);
   }
 
   if (!skip.has('mounts')) {
@@ -816,14 +826,27 @@ async function askAgentProviderChoice(): Promise<string> {
     ...installed.map(({ value, label, hint }) => ({ value, label, hint })),
     ...available.map((prov) => ({ value: prov.value, label: prov.label, hint: `${prov.hint} — installs now` })),
   ];
-  // The pick installs and authenticates a runtime — it is not an
-  // install-wide default, so re-runs safely Enter-through on claude (its
-  // auth flow short-circuits when the secret already exists).
+  const preset = process.env.NANOCLAW_AGENT_PROVIDER?.trim().toLowerCase();
+  if (preset) {
+    if (!options.some((option) => option.value === preset)) {
+      throw new Error(`NANOCLAW_AGENT_PROVIDER=${preset} is not available in this NanoClaw install`);
+    }
+    setupLog.userInput('agent_provider', preset);
+    phEmit('agent_provider_chosen', { provider: preset, preset: true });
+    return preset;
+  }
+  // The pick is persisted as the instance default (DEFAULT_AGENT_PROVIDER), so
+  // pre-select the current default — a re-run Enter-through then preserves it
+  // instead of silently resetting it to claude. Fall back to claude if the
+  // persisted default isn't an offered option (e.g. its provider was removed).
+  const currentDefault = options.some((o) => o.value === DEFAULT_AGENT_PROVIDER)
+    ? DEFAULT_AGENT_PROVIDER
+    : 'claude';
   const choice = ensureAnswer(
     await brightSelect<string>({
       message: 'Which agent runtime should power your assistant?',
       options,
-      initialValue: 'claude',
+      initialValue: currentDefault,
     }),
   ) as string;
   setupLog.userInput('agent_provider', choice);

setup/channels/slack.ts

@@ -4,15 +4,18 @@
  * `runSlackChannel(displayName)` owns the full branch from creating a
  * Slack app through the welcome DM:
  *
- *   1. Walk through creating a Slack app (api.slack.com/apps) — scopes,
- *      event subscriptions, and signing secret
- *   2. Paste the bot token + signing secret (clack password prompts)
- *   3. Validate via auth.test → resolves workspace + bot identity
- *   4. Install the adapter (setup/add-slack.sh, non-interactive)
- *   5. Ask for the operator's Slack user ID
- *   6. conversations.open to get the DM channel ID
- *   7. Ask for the messaging-agent name (defaulting to "Nano")
- *   8. Wire the agent via scripts/init-first-agent.ts
+ *   1. Ask the delivery mode: Socket Mode (outbound WebSocket, no public
+ *      URL) or a public webhook
+ *   2. Walk through creating a Slack app (api.slack.com/apps) — scopes,
+ *      events, and the mode-specific credential (app-level token for
+ *      Socket Mode, signing secret for webhook)
+ *   3. Paste the bot token + that credential (clack password prompts)
+ *   4. Validate via auth.test → resolves workspace + bot identity
+ *   5. Install the adapter (setup/add-slack.sh, non-interactive)
+ *   6. Ask for the operator's Slack user ID
+ *   7. conversations.open to get the DM channel ID
+ *   8. Ask for the messaging-agent name (defaulting to "Nano")
+ *   9. Wire the agent via scripts/init-first-agent.ts
  *
  * The welcome DM is sent via outbound delivery (chat.postMessage), which
  * works without Event Subscriptions being configured. The user sees the
@@ -45,14 +48,26 @@ interface WorkspaceInfo {
   botUserId: string;
 }
 
+// Socket Mode (SLACK_APP_TOKEN, xapp-…) needs no public URL; webhook mode
+// (SLACK_SIGNING_SECRET) needs a public Request URL. The adapter picks the mode
+// purely from SLACK_APP_TOKEN's presence — this choice just decides which
+// credential to collect and which post-install guidance to show.
+type SlackMode = 'socket' | 'webhook';
+
 export async function runSlackChannel(displayName: string): Promise<ChannelFlowResult> {
-  const intro = await walkThroughAppCreation();
+  const mode = await askSlackMode();
+  const intro = await walkThroughAppCreation(mode);
   if (intro === 'back') return BACK_TO_CHANNEL_SELECTION;
 
   const token = await collectBotToken();
-  const signingSecret = await collectSigningSecret();
+  const appToken = mode === 'socket' ? await collectAppToken() : undefined;
+  const signingSecret = mode === 'webhook' ? await collectSigningSecret() : undefined;
   const info = await validateSlackToken(token);
 
+  const env: Record<string, string> = { SLACK_BOT_TOKEN: token };
+  if (appToken) env.SLACK_APP_TOKEN = appToken;
+  if (signingSecret) env.SLACK_SIGNING_SECRET = signingSecret;
+
   const install = await runQuietChild(
     'slack-install',
     'bash',
@@ -62,11 +77,9 @@ export async function runSlackChannel(displayName: string): Promise<ChannelFlowR
       done: 'Slack adapter installed.',
     },
     {
-      env: {
-        SLACK_BOT_TOKEN: token,
-        SLACK_SIGNING_SECRET: signingSecret,
-      },
+      env,
       extraFields: {
+        MODE: mode,
         BOT_NAME: info.botName,
         TEAM_NAME: info.teamName,
         TEAM_ID: info.teamId,
@@ -122,10 +135,45 @@ export async function runSlackChannel(displayName: string): Promise<ChannelFlowR
     );
   }
 
-  showPostInstallChecklist(info);
+  showPostInstallChecklist(info, mode);
 }
 
-async function walkThroughAppCreation(): Promise<'continue' | 'back'> {
+async function askSlackMode(): Promise<SlackMode> {
+  const choice = ensureAnswer(
+    await brightSelect<SlackMode>({
+      message: 'How should Slack deliver events to NanoClaw?',
+      initialValue: 'socket',
+      options: [
+        {
+          value: 'socket',
+          label: 'Socket Mode',
+          hint: 'no public URL — recommended for local or behind NAT',
+        },
+        {
+          value: 'webhook',
+          label: 'Public webhook',
+          hint: 'needs a public HTTPS Request URL',
+        },
+      ],
+    }),
+  );
+  setupLog.userInput('slack_mode', String(choice));
+  return choice;
+}
+
+async function walkThroughAppCreation(mode: SlackMode): Promise<'continue' | 'back'> {
+  const credSteps =
+    mode === 'socket'
+      ? [
+          '  4. Basic Information → App-Level Tokens → "Generate Token and',
+          '     Scopes" → add the connections:write scope → copy it (xapp-…)',
+          '  5. Socket Mode → toggle "Enable Socket Mode" on',
+          '  6. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-…)',
+        ]
+      : [
+          '  4. Basic Information → copy the "Signing Secret"',
+          '  5. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-…)',
+        ];
   // Bright-white ANSI overrides the surrounding brand-cyan from `note()`'s
   // per-line formatter so the URL stands out against the rest of the body.
   const linkBlock = isHeadless()
@@ -149,8 +197,7 @@ async function walkThroughAppCreation(): Promise<'continue' | 'back'> {
       '     • files:read, files:write',
       '  3. App Home → enable "Messages Tab" and "Allow users to send',
       '     slash commands and messages from the messages tab"',
-      '  4. Basic Information → copy the "Signing Secret"',
-      '  5. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-…)',
+      ...credSteps,
     ].join('\n'),
     'Create a Slack app',
   );
@@ -171,7 +218,10 @@ async function walkThroughAppCreation(): Promise<'continue' | 'back'> {
 
   ensureAnswer(
     await p.confirm({
-      message: 'Got your bot token and signing secret?',
+      message:
+        mode === 'socket'
+          ? 'Got your bot token and app-level token?'
+          : 'Got your bot token and signing secret?',
       initialValue: true,
     }),
   );
@@ -249,6 +299,40 @@ async function collectSigningSecret(): Promise<string> {
   return secret;
 }
 
+async function collectAppToken(): Promise<string> {
+  const existing = readEnvKey('SLACK_APP_TOKEN');
+  if (existing && existing.startsWith('xapp-') && existing.length >= 24) {
+    const reuse = ensureAnswer(await p.confirm({
+      message: `Found an existing Slack app-level token (${existing.slice(0, 10)}…). Use it?`,
+      initialValue: true,
+    }));
+    if (reuse) {
+      setupLog.userInput('slack_app_token', 'reused-existing');
+      return existing;
+    }
+  }
+
+  const answer = ensureAnswer(
+    await p.password({
+      message: 'Paste your Slack app-level token (Socket Mode)',
+      clearOnError: true,
+      validate: (v) => {
+        const t = (v ?? '').trim();
+        if (!t) return 'App-level token is required for Socket Mode';
+        if (!t.startsWith('xapp-')) return 'App-level tokens start with xapp-';
+        if (t.length < 24) return "That's shorter than a real Slack app-level token";
+        return undefined;
+      },
+    }),
+  );
+  const token = (answer as string).trim();
+  setupLog.userInput(
+    'slack_app_token',
+    `${token.slice(0, 10)}…${token.slice(-4)}`,
+  );
+  return token;
+}
+
 async function validateSlackToken(token: string): Promise<WorkspaceInfo> {
   const s = p.spinner();
   const start = Date.now();
@@ -416,7 +500,26 @@ async function resolveAgentName(): Promise<string> {
   return value;
 }
 
-function showPostInstallChecklist(info: WorkspaceInfo): void {
+function showPostInstallChecklist(info: WorkspaceInfo, mode: SlackMode): void {
+  if (mode === 'socket') {
+    note(
+      wrapForGutter(
+        [
+          `Your agent is wired to Slack and a welcome DM is on its way.`,
+          `Socket Mode is on — ${info.teamName} reaches NanoClaw over an outbound`,
+          `WebSocket, so there's no public URL to configure.`,
+          '',
+          '  • Just DM @' + info.botName + ' from Slack — replies flow straight away.',
+          '',
+          '  • Keep the NanoClaw host running to hold the socket open —',
+          '    Slack does not retry delivery while it is down.',
+        ].join('\n'),
+        6,
+      ),
+      'Finish setting up Slack',
+    );
+    return;
+  }
   note(
     wrapForGutter(
       [

setup/install-discord.sh

@@ -37,7 +37,7 @@ if ! grep -q "import './discord.js';" src/channels/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/discord@4.26.0
+pnpm install @chat-adapter/discord@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-gchat.sh

@@ -37,7 +37,7 @@ if ! grep -q "import './gchat.js';" src/channels/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/gchat@4.26.0
+pnpm install @chat-adapter/gchat@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-github.sh

@@ -37,7 +37,7 @@ if ! grep -q "import './github.js';" src/channels/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/github@4.26.0
+pnpm install @chat-adapter/github@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-linear.sh

@@ -86,7 +86,7 @@ if ! grep -q 'if (config.catchAll) {' src/channels/chat-sdk-bridge.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/linear@4.26.0
+pnpm install @chat-adapter/linear@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-slack.sh

@@ -37,7 +37,7 @@ if ! grep -q "import './slack.js';" src/channels/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/slack@4.26.0
+pnpm install @chat-adapter/slack@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-teams.sh

@@ -37,7 +37,7 @@ if ! grep -q "import './teams.js';" src/channels/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/teams@4.26.0
+pnpm install @chat-adapter/teams@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-telegram.sh

@@ -63,7 +63,7 @@ if ! grep -q "'pair-telegram':" setup/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/telegram@4.26.0
+pnpm install @chat-adapter/telegram@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/install-whatsapp-cloud.sh

@@ -37,7 +37,7 @@ if ! grep -q "import './whatsapp-cloud.js';" src/channels/index.ts; then
 fi
 
 echo "STEP: pnpm-install"
-pnpm install @chat-adapter/whatsapp@4.26.0
+pnpm install @chat-adapter/whatsapp@4.29.0
 
 echo "STEP: pnpm-build"
 pnpm run build

setup/lib/picked-provider.ts

@@ -1,16 +1,17 @@
 /**
- * The agent runtime the operator picked in THIS setup run.
+ * The agent runtime the operator picked in THIS setup run, carried to the
+ * group-creation child processes over the process boundary.
  *
- * There is no install-wide default provider and no `--provider` in the
- * creation contract — provider is a DB property of a group. Setup is the one
- * orchestrator that knows the operator's pick, so it stashes it here (set once
- * at the auth step). The group-creation scripts (`init-first-agent`,
- * `init-cli-agent`) run as **child processes**, so the pick is carried over the
- * process boundary via an environment variable they inherit; they apply it to
- * the group at creation, before the welcome wakes the container. This is the
- * only place the value lives — a setup-run-scoped global, NOT a persisted
- * install default. `undefined` / `'claude'` means the built-in default and no
- * provider write at all.
+ * There is no `--provider` flag in the creation contract — provider is a DB
+ * property of a group. Setup persists the pick two ways: as the install-wide
+ * default (`DEFAULT_AGENT_PROVIDER` in `.env`, see src/config.ts), which every
+ * future group inherits at creation via the `ensureContainerConfig` chokepoint;
+ * and here, in a setup-run-scoped env var, so the FIRST agent created in the
+ * same run (by `init-first-agent` / `init-cli-agent`, which run as child
+ * processes) is stamped with the pick before the welcome wakes the container —
+ * without waiting for the host to restart and reload `.env`. `undefined` /
+ * `'claude'` means no run-scoped pick; the creation scripts then fall back to
+ * the install-wide default.
  */
 const ENV_KEY = 'NANOCLAW_PICKED_PROVIDER';
 

setup/lib/setup-config.ts

@@ -123,6 +123,14 @@ export const CONFIG: Entry[] = [
     surface: 'flag',
     type: 'string',
   },
+  {
+    key: 'agentProvider',
+    envVar: 'NANOCLAW_AGENT_PROVIDER',
+    label: 'Agent provider',
+    help: 'Preselect the setup provider and skip the provider picker.',
+    surface: 'flag',
+    type: 'string',
+  },
   {
     key: 'assistMode',
     envVar: 'NANOCLAW_SETUP_ASSIST_MODE',

setup/migrate-v2/db.ts

@@ -43,7 +43,6 @@ interface V1Group {
   folder: string;
   trigger_pattern: string | null;
   requires_trigger: number | null;
-  is_main: number | null;
 }
 
 async function main(): Promise<void> {
@@ -65,7 +64,7 @@ async function main(): Promise<void> {
   // v1 schema varies — channel_name was a late addition. Query only the
   // columns we know exist in all v1 installs.
   const v1Groups = v1Db
-    .prepare('SELECT jid, name, folder, trigger_pattern, requires_trigger, is_main FROM registered_groups')
+    .prepare('SELECT jid, name, folder, trigger_pattern, requires_trigger FROM registered_groups')
     .all() as V1Group[];
   v1Db.close();
 

setup/peer-cleanup.test.ts

@@ -0,0 +1,138 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { getLaunchdLabel, getSystemdUnit } from '../src/install-slug.js';
+import { cleanupUnhealthyPeers } from './peer-cleanup.js';
+
+// The reaper deletes config files from ~/Library/LaunchAgents (or the systemd
+// user dir). We point HOME at a throwaway temp dir so real registrations are
+// never touched, and force os.platform() so the launchd/systemd branch runs
+// regardless of the host running the suite. The best-effort unload inside the
+// reaper (launchctl/systemctl) is swallowed when the binary is absent, so these
+// tests are deterministic on both macOS and Linux CI.
+
+function tempHome(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'peer-cleanup-'));
+}
+
+function writePlist(filePath: string, target: string): void {
+  fs.writeFileSync(
+    filePath,
+    `<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0"><dict>
+  <key>ProgramArguments</key>
+  <array><string>/usr/bin/node</string><string>${target}</string></array>
+</dict></plist>`,
+  );
+}
+
+function writeUnit(filePath: string, target: string): void {
+  fs.writeFileSync(filePath, `[Service]\nExecStart=/usr/bin/node ${target}\n`);
+}
+
+const created: string[] = [];
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const dir of created.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('cleanupUnhealthyPeers — dead launchd registrations', () => {
+  function setup(): { home: string; agentsDir: string; projectRoot: string } {
+    const home = tempHome();
+    created.push(home);
+    const agentsDir = path.join(home, 'Library', 'LaunchAgents');
+    fs.mkdirSync(agentsDir, { recursive: true });
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+    vi.spyOn(os, 'platform').mockReturnValue('darwin');
+    return { home, agentsDir, projectRoot: path.join(home, 'install') };
+  }
+
+  it('removes a plist whose target binary is gone', () => {
+    const { agentsDir, projectRoot } = setup();
+    const dead = path.join(agentsDir, 'com.nanoclaw-v2-dead.plist');
+    writePlist(dead, path.join(agentsDir, 'gone', 'dist', 'index.js'));
+
+    const result = cleanupUnhealthyPeers(projectRoot);
+
+    expect(fs.existsSync(dead)).toBe(false);
+    expect(result.removed.map((r) => r.label)).toContain('com.nanoclaw-v2-dead');
+  });
+
+  it('leaves a plist whose target still exists', () => {
+    const { agentsDir, projectRoot } = setup();
+    const liveTarget = path.join(agentsDir, 'live', 'dist', 'index.js');
+    fs.mkdirSync(path.dirname(liveTarget), { recursive: true });
+    fs.writeFileSync(liveTarget, '// host entry');
+    const live = path.join(agentsDir, 'com.nanoclaw-v2-live.plist');
+    writePlist(live, liveTarget);
+
+    const result = cleanupUnhealthyPeers(projectRoot);
+
+    expect(fs.existsSync(live)).toBe(true);
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it("never reaps this install's own plist, even with a missing target", () => {
+    const { agentsDir, projectRoot } = setup();
+    const ownLabel = getLaunchdLabel(projectRoot);
+    const own = path.join(agentsDir, `${ownLabel}.plist`);
+    writePlist(own, path.join(agentsDir, 'gone', 'dist', 'index.js'));
+
+    const result = cleanupUnhealthyPeers(projectRoot);
+
+    expect(fs.existsSync(own)).toBe(true);
+    expect(result.removed).toHaveLength(0);
+  });
+
+  it('ignores an unrecognized plist (no dist/index.js target)', () => {
+    const { agentsDir, projectRoot } = setup();
+    const weird = path.join(agentsDir, 'com.nanoclaw-v2-weird.plist');
+    fs.writeFileSync(weird, '<plist><dict></dict></plist>');
+
+    const result = cleanupUnhealthyPeers(projectRoot);
+
+    expect(fs.existsSync(weird)).toBe(true);
+    expect(result.removed).toHaveLength(0);
+  });
+});
+
+describe('cleanupUnhealthyPeers — dead systemd registrations', () => {
+  function setup(): { unitDir: string; projectRoot: string } {
+    const home = tempHome();
+    created.push(home);
+    const unitDir = path.join(home, '.config', 'systemd', 'user');
+    fs.mkdirSync(unitDir, { recursive: true });
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+    vi.spyOn(os, 'platform').mockReturnValue('linux');
+    return { unitDir, projectRoot: path.join(home, 'install') };
+  }
+
+  it('removes a unit whose target binary is gone', () => {
+    const { unitDir, projectRoot } = setup();
+    const dead = path.join(unitDir, 'nanoclaw-v2-dead.service');
+    writeUnit(dead, path.join(unitDir, 'gone', 'dist', 'index.js'));
+
+    const result = cleanupUnhealthyPeers(projectRoot);
+
+    expect(fs.existsSync(dead)).toBe(false);
+    expect(result.removed.map((r) => r.label)).toContain('nanoclaw-v2-dead');
+  });
+
+  it("never reaps this install's own unit", () => {
+    const { unitDir, projectRoot } = setup();
+    const ownUnit = getSystemdUnit(projectRoot);
+    const own = path.join(unitDir, `${ownUnit}.service`);
+    writeUnit(own, path.join(unitDir, 'gone', 'dist', 'index.js'));
+
+    const result = cleanupUnhealthyPeers(projectRoot);
+
+    expect(fs.existsSync(own)).toBe(true);
+    expect(result.removed).toHaveLength(0);
+  });
+});

setup/peer-cleanup.ts

@@ -11,6 +11,14 @@
  *   - launchd: `state != running` AND `runs > UNHEALTHY_RUNS_THRESHOLD`
  *   - systemd: unit is in `failed` state, OR `activating` with many restarts
  *
+ * Separately, a peer registration is "dead" when the program it launches no
+ * longer exists on disk — almost always a deleted test checkout or worktree.
+ * The service manager keeps retrying the missing binary forever, and the
+ * health probes can't see it because an unloaded/inactive job doesn't report
+ * via `launchctl print` / `systemctl show`. Deleting an install's folder
+ * without running the uninstaller leaves these behind, so they accumulate. We
+ * unload and delete the orphaned config file outright.
+ *
  * Healthy peers are left alone — multiple installs can coexist fine now that
  * container-reaper is label-scoped.
  */
@@ -35,6 +43,7 @@ export interface PeerStatus {
 export interface PeerCleanupResult {
   checked: PeerStatus[];
   unloaded: PeerStatus[];
+  removed: Array<{ label: string; configPath: string }>;
   failures: Array<{ label: string; err: string }>;
 }
 
@@ -50,7 +59,39 @@ export function cleanupUnhealthyPeers(projectRoot: string = process.cwd()): Peer
   if (platform === 'linux') {
     return cleanupSystemdPeers(projectRoot);
   }
-  return { checked: [], unloaded: [], failures: [] };
+  return { checked: [], unloaded: [], removed: [], failures: [] };
+}
+
+/**
+ * Unload a dead peer's job (best-effort) and delete its orphaned config file.
+ * `unload` runs first and may throw harmlessly when the job isn't loaded or the
+ * service-manager binary is absent (e.g. exercising launchd cleanup on Linux).
+ */
+function reapDeadPeer(
+  result: PeerCleanupResult,
+  peer: { label: string; configPath: string },
+  unload: () => void,
+  kind: string,
+  missingTarget: string,
+): void {
+  try {
+    unload();
+  } catch {
+    /* job not loaded — nothing to unload */
+  }
+  try {
+    fs.rmSync(peer.configPath, { force: true });
+    log.info(`Removed dead peer ${kind}`, {
+      label: peer.label,
+      configPath: peer.configPath,
+      missingTarget,
+    });
+    result.removed.push(peer);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn(`Failed to remove dead peer ${kind}`, { label: peer.label, err: message });
+    result.failures.push({ label: peer.label, err: message });
+  }
 }
 
 // ---- launchd (macOS) --------------------------------------------------------
@@ -58,7 +99,7 @@ export function cleanupUnhealthyPeers(projectRoot: string = process.cwd()): Peer
 function cleanupLaunchdPeers(projectRoot: string): PeerCleanupResult {
   const ownLabel = getLaunchdLabel(projectRoot);
   const agentsDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
-  const result: PeerCleanupResult = { checked: [], unloaded: [], failures: [] };
+  const result: PeerCleanupResult = { checked: [], unloaded: [], removed: [], failures: [] };
 
   let plists: string[];
   try {
@@ -76,6 +117,20 @@ function cleanupLaunchdPeers(projectRoot: string): PeerCleanupResult {
     const label = path.basename(plistPath, '.plist');
     if (label === ownLabel) continue;
 
+    const missingTarget = deadLaunchdTarget(plistPath);
+    if (missingTarget) {
+      reapDeadPeer(
+        result,
+        { label, configPath: plistPath },
+        // Best-effort unload in case launchd still has it registered; throwing
+        // (not loaded, or launchctl absent off-macOS) is expected and ignored.
+        () => execFileSync('launchctl', ['unload', plistPath], { stdio: 'pipe' }),
+        'launchd plist',
+        missingTarget,
+      );
+      continue;
+    }
+
     const status = probeLaunchdPeer(label, plistPath, uid);
     if (!status) continue;
     result.checked.push(status);
@@ -121,12 +176,32 @@ function probeLaunchdPeer(label: string, plistPath: string, uid: number): PeerSt
   return { label, configPath: plistPath, state, runs, unhealthy };
 }
 
+/**
+ * Returns the program path a launchd plist launches when that program no longer
+ * exists on disk (a dead registration), or undefined when the plist is
+ * unreadable, has an unrecognized shape, or its target still exists — in which
+ * case the plist must not be touched.
+ */
+function deadLaunchdTarget(plistPath: string): string | undefined {
+  let xml: string;
+  try {
+    xml = fs.readFileSync(plistPath, 'utf-8');
+  } catch {
+    return undefined;
+  }
+  // ProgramArguments is [nodePath, "<projectRoot>/dist/index.js"]; the host
+  // entry point is the stable marker to match on.
+  const target = /<string>([^<]*\/dist\/index\.js)<\/string>/.exec(xml)?.[1];
+  if (!target) return undefined;
+  return fs.existsSync(target) ? undefined : target;
+}
+
 // ---- systemd (Linux) --------------------------------------------------------
 
 function cleanupSystemdPeers(projectRoot: string): PeerCleanupResult {
   const ownUnit = getSystemdUnit(projectRoot);
   const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
-  const result: PeerCleanupResult = { checked: [], unloaded: [], failures: [] };
+  const result: PeerCleanupResult = { checked: [], unloaded: [], removed: [], failures: [] };
 
   let units: string[];
   try {
@@ -141,6 +216,22 @@ function cleanupSystemdPeers(projectRoot: string): PeerCleanupResult {
   for (const unit of units) {
     if (unit === ownUnit) continue;
 
+    const unitPath = path.join(unitDir, `${unit}.service`);
+    const missingTarget = deadSystemdTarget(unitPath);
+    if (missingTarget) {
+      reapDeadPeer(
+        result,
+        { label: unit, configPath: unitPath },
+        () => {
+          execFileSync('systemctl', ['--user', 'disable', '--now', `${unit}.service`], { stdio: 'pipe' });
+          execFileSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'pipe' });
+        },
+        'systemd unit',
+        missingTarget,
+      );
+      continue;
+    }
+
     const status = probeSystemdPeer(unit);
     if (!status) continue;
     result.checked.push(status);
@@ -184,3 +275,21 @@ function probeSystemdPeer(unit: string): PeerStatus | null {
     return null;
   }
 }
+
+/**
+ * Returns the program path a systemd unit launches when that program no longer
+ * exists on disk (a dead registration), or undefined when the unit is
+ * unreadable, has an unrecognized shape, or its target still exists.
+ */
+function deadSystemdTarget(unitPath: string): string | undefined {
+  let unit: string;
+  try {
+    unit = fs.readFileSync(unitPath, 'utf-8');
+  } catch {
+    return undefined;
+  }
+  // ExecStart=<nodePath> <projectRoot>/dist/index.js
+  const target = /^ExecStart=\S+\s+(\S+\/dist\/index\.js)\s*$/m.exec(unit)?.[1];
+  if (!target) return undefined;
+  return fs.existsSync(target) ? undefined : target;
+}

setup/provider-contract.test.ts

@@ -55,12 +55,19 @@ describe('setup carries the picked provider to creation via a setup-run env var'
   // The creation scripts run as child processes, inherit the env var, and apply
   // it to the group's runtime config — container_configs.provider, the source of
   // truth materialized into container.json (agent_provider is deprecated) — before
-  // the welcome wakes the container. No `--provider` flag in the contract (above).
-  for (const file of ['scripts/init-first-agent.ts', 'scripts/init-cli-agent.ts']) {
+  // the welcome wakes the container, falling back to the instance default
+  // (DEFAULT_AGENT_PROVIDER) when the env var is unset. No `--provider` flag in
+  // the contract (above). init-first-agent stamps directly via
+  // ensureContainerConfig; init-cli-agent threads it through initGroupFilesystem.
+  const applyPattern: Record<string, RegExp> = {
+    'scripts/init-first-agent.ts': /ensureContainerConfig\([^)]*pickedProvider/,
+    'scripts/init-cli-agent.ts': /provider:\s*pickedProvider/,
+  };
+  for (const [file, pattern] of Object.entries(applyPattern)) {
     it(`${file} applies the env-carried provider to container_configs.provider`, () => {
       const src = read(file);
       expect(src).toContain('NANOCLAW_PICKED_PROVIDER');
-      expect(src).toMatch(/updateContainerConfigScalars\([^)]*provider:\s*pickedProvider/);
+      expect(src).toMatch(pattern);
     });
   }
 });

setup/providers/registry.test.ts

@@ -32,10 +32,17 @@ describe('setup flow consumes the registry (structural)', () => {
     const src = fs.readFileSync(path.join(process.cwd(), 'setup', 'auto.ts'), 'utf-8');
     expect(src).toContain('listSetupProviders()');
     expect(src).toContain("import './providers/index.js'");
+    expect(src).toContain('NANOCLAW_AGENT_PROVIDER');
     // The capability-keyed branch — a provider's own auth runs iff it declares one.
     expect(src).toMatch(/providerEntry\?\.runAuth/);
   });
 
+  it('the provider preset is exposed as an env setup knob', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'setup', 'lib', 'setup-config.ts'), 'utf-8');
+    expect(src).toContain('NANOCLAW_AGENT_PROVIDER');
+    expect(src).toContain("key: 'agentProvider'");
+  });
+
   it('the standalone provider-auth step is reachable from the STEPS map', () => {
     const src = fs.readFileSync(path.join(process.cwd(), 'setup', 'index.ts'), 'utf-8');
     expect(src).toContain("'provider-auth'");

setup/register.ts

@@ -126,11 +126,12 @@ export async function run(args: string[]): Promise<void> {
   const db = initDb(dbPath);
   runMigrations(db);
 
-  // 1. Create or find agent group. Provider-agnostic: provider is a DB
-  // property set via `ncl groups config update --provider`, not a creation
-  // flag. The workspace is scaffolded at the first spawn (group-init), where
-  // the DB-resolved provider is known; here we only ensure the config row
-  // exists so that update has a row to write.
+  // 1. Create or find agent group. The workspace is scaffolded at the first
+  // spawn (group-init), where the DB-resolved provider is known; here we only
+  // seed the config row — stamped with the instance default so a newly wired
+  // channel group is created on the operator's chosen provider (per-group
+  // `ncl groups config update --provider` still overrides). A reused group
+  // keeps its existing provider (INSERT OR IGNORE).
   let agentGroup = getAgentGroupByFolder(parsed.folder);
   if (!agentGroup) {
     const agId = generateId('ag');

setup/service.ts

@@ -72,6 +72,12 @@ export async function run(_args: string[]): Promise<void> {
       labels: peerReport.unloaded.map((p) => p.label),
     });
   }
+  if (peerReport.removed.length > 0) {
+    log.warn('Removed dead peer NanoClaw registrations (target binary missing)', {
+      count: peerReport.removed.length,
+      labels: peerReport.removed.map((p) => p.label),
+    });
+  }
 
   if (platform === 'macos') {
     setupLaunchd(projectRoot, nodePath, homeDir);

setup/set-env.ts

@@ -18,6 +18,34 @@ import path from 'path';
 import { log } from '../src/log.js';
 import { emitStatus } from './status.js';
 
+/**
+ * Upsert a `KEY=VALUE` line into the project's `.env`, returning whether the
+ * key already existed. The canonical writer for new `.env` edits (legacy setup
+ * steps still write directly) so flows don't invent grep/sed pipelines (which
+ * can't be allowlisted tightly).
+ */
+export function upsertEnvVar(key: string, value: string): { existed: boolean } {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env key: ${key} (must be UPPER_SNAKE_CASE)`);
+  }
+  const envFile = path.join(process.cwd(), '.env');
+  let content = '';
+  if (fs.existsSync(envFile)) {
+    content = fs.readFileSync(envFile, 'utf-8');
+  }
+  const lineRegex = new RegExp(`^${key}=.*$`, 'm');
+  const existed = lineRegex.test(content);
+  const newLine = `${key}=${value}`;
+  if (existed) {
+    content = content.replace(lineRegex, newLine);
+  } else {
+    const sep = content && !content.endsWith('\n') ? '\n' : '';
+    content = content + sep + newLine + '\n';
+  }
+  fs.writeFileSync(envFile, content);
+  return { existed };
+}
+
 export async function run(args: string[]): Promise<void> {
   const keyIdx = args.indexOf('--key');
   const valueIdx = args.indexOf('--value');
@@ -33,37 +61,15 @@ export async function run(args: string[]): Promise<void> {
   const key = args[keyIdx + 1];
   const value = args[valueIdx + 1];
 
-  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
-    throw new Error(`Invalid env key: ${key} (must be UPPER_SNAKE_CASE)`);
-  }
-
-  const projectRoot = process.cwd();
-  const envFile = path.join(projectRoot, '.env');
-
-  let content = '';
-  if (fs.existsSync(envFile)) {
-    content = fs.readFileSync(envFile, 'utf-8');
-  }
-
-  const lineRegex = new RegExp(`^${key}=.*$`, 'm');
-  const newLine = `${key}=${value}`;
-  const existed = lineRegex.test(content);
-
-  if (existed) {
-    content = content.replace(lineRegex, newLine);
-  } else {
-    const sep = content && !content.endsWith('\n') ? '\n' : '';
-    content = content + sep + newLine + '\n';
-  }
-
-  fs.writeFileSync(envFile, content);
+  const { existed } = upsertEnvVar(key, value);
   log.info('Updated .env', { key, existed });
 
   let synced = false;
   if (syncContainer) {
+    const projectRoot = process.cwd();
     const dataEnvDir = path.join(projectRoot, 'data', 'env');
     fs.mkdirSync(dataEnvDir, { recursive: true });
-    fs.copyFileSync(envFile, path.join(dataEnvDir, 'env'));
+    fs.copyFileSync(path.join(projectRoot, '.env'), path.join(dataEnvDir, 'env'));
     synced = true;
     log.info('Synced .env to container mount', { path: 'data/env/env' });
   }

src/claude-md-compose.test.ts

@@ -0,0 +1,93 @@
+import fs from 'fs';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const TEST_ROOT = '/tmp/nanoclaw-claude-md-compose-test';
+const GROUPS_DIR = path.join(TEST_ROOT, 'groups');
+
+vi.mock('./config.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./config.js')>()),
+  GROUPS_DIR: '/tmp/nanoclaw-claude-md-compose-test/groups',
+}));
+
+vi.mock('./log.js', () => ({
+  log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
+
+import { composeGroupClaudeMd } from './claude-md-compose.js';
+import { ensureContainerConfig } from './db/container-configs.js';
+import { closeDb, createAgentGroup, initTestDb, runMigrations } from './db/index.js';
+import { PERSONA_PREPEND_FILE } from './group-persona.js';
+import type { AgentGroup } 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;
+}
+
+function seed(ag: AgentGroup): void {
+  createAgentGroup(ag);
+  ensureContainerConfig(ag.id);
+}
+
+function writePersona(folder: string, text: string): void {
+  const dir = path.join(GROUPS_DIR, folder);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, PERSONA_PREPEND_FILE), text);
+}
+
+function importsOf(folder: string): string[] {
+  const md = fs.readFileSync(path.join(GROUPS_DIR, folder, 'CLAUDE.md'), 'utf-8');
+  return md.split('\n').filter((line) => line.startsWith('@'));
+}
+
+beforeEach(() => {
+  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
+  fs.mkdirSync(TEST_ROOT, { recursive: true });
+  runMigrations(initTestDb());
+});
+
+afterEach(() => {
+  closeDb();
+  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
+});
+
+describe('composeGroupClaudeMd persona prepend', () => {
+  it('imports the persona fragment FIRST, before the shared base', () => {
+    const ag = group('ag-persona', 'persona-group');
+    seed(ag);
+    writePersona(ag.folder, 'You are an SDR agent.\n');
+
+    composeGroupClaudeMd(ag);
+
+    const imports = importsOf(ag.folder);
+    expect(imports[0]).toBe('@./.claude-fragments/persona.md');
+    expect(imports[1]).toBe('@./.claude-shared.md');
+    expect(fs.readFileSync(path.join(GROUPS_DIR, ag.folder, '.claude-fragments', 'persona.md'), 'utf-8')).toBe(
+      'You are an SDR agent.',
+    );
+  });
+
+  it('keeps the persona across a second compose (not pruned)', () => {
+    const ag = group('ag-persona-2', 'persona-group-2');
+    seed(ag);
+    writePersona(ag.folder, 'persona body');
+
+    composeGroupClaudeMd(ag);
+    composeGroupClaudeMd(ag);
+
+    expect(fs.existsSync(path.join(GROUPS_DIR, ag.folder, '.claude-fragments', 'persona.md'))).toBe(true);
+    expect(importsOf(ag.folder)[0]).toBe('@./.claude-fragments/persona.md');
+  });
+
+  it('is inert when no persona file is present (non-template groups)', () => {
+    const ag = group('ag-no-persona', 'no-persona-group');
+    seed(ag);
+
+    composeGroupClaudeMd(ag);
+
+    const imports = importsOf(ag.folder);
+    expect(imports[0]).toBe('@./.claude-shared.md');
+    expect(imports).not.toContain('@./.claude-fragments/persona.md');
+    expect(fs.existsSync(path.join(GROUPS_DIR, ag.folder, '.claude-fragments', 'persona.md'))).toBe(false);
+  });
+});

src/claude-md-compose.ts

@@ -20,9 +20,14 @@ import path from 'path';
 import { GROUPS_DIR } from './config.js';
 import type { McpServerConfig } from './container-config.js';
 import { getContainerConfig } from './db/container-configs.js';
+import { readGroupPersona } from './group-persona.js';
 import { log } from './log.js';
 import type { AgentGroup } from './types.js';
 
+// Fragment holding a template's persona prepend. Imported FIRST (before the
+// shared base) so the persona is the top of the composed system prompt.
+const PERSONA_FRAGMENT = 'persona.md';
+
 // Symlink targets are container paths — dangling on host (hence the readlink
 // dance instead of existsSync), valid inside the container via RO mounts.
 const SHARED_CLAUDE_MD_CONTAINER_PATH = '/app/CLAUDE.md';
@@ -106,6 +111,13 @@ export function composeGroupClaudeMd(group: AgentGroup): void {
     }
   }
 
+  // Template persona (if any) — inline so it survives the prune below; imported
+  // first (see the imports assembly) so it prepends the composed system prompt.
+  const persona = readGroupPersona(groupDir);
+  if (persona) {
+    desired.set(PERSONA_FRAGMENT, { type: 'inline', content: persona });
+  }
+
   // Reconcile: drop stale, write desired.
   for (const existing of fs.readdirSync(fragmentsDir)) {
     if (!desired.has(existing)) {
@@ -121,9 +133,14 @@ export function composeGroupClaudeMd(group: AgentGroup): void {
     }
   }
 
-  // Composed entry — imports only.
-  const imports = ['@./.claude-shared.md'];
-  for (const name of [...desired.keys()].sort()) {
+  // Composed entry — imports only. Persona first (top of the system prompt),
+  // then the shared base, then the remaining fragments sorted.
+  const imports: string[] = [];
+  if (desired.has(PERSONA_FRAGMENT)) {
+    imports.push(`@./.claude-fragments/${PERSONA_FRAGMENT}`);
+  }
+  imports.push('@./.claude-shared.md');
+  for (const name of [...desired.keys()].filter((n) => n !== PERSONA_FRAGMENT).sort()) {
     imports.push(`@./.claude-fragments/${name}`);
   }
   const body = [COMPOSED_HEADER, ...imports, ''].join('\n');

src/cli/crud.ts

@@ -30,6 +30,8 @@ export interface ColumnDef {
   updatable?: boolean;
   /** Default value on create when not provided. */
   default?: unknown;
+  /** Default to another column's resolved value on create when not provided. */
+  defaultFrom?: string;
   /** Allowed values (shown in help). */
   enum?: string[];
 }
@@ -150,6 +152,8 @@ function genericCreate(def: ResourceDef) {
         throw new Error(`--${col.name.replace(/_/g, '-')} is required`);
       } else if (col.default !== undefined) {
         values[col.name] = col.default;
+      } else if (col.defaultFrom !== undefined && values[col.defaultFrom] !== undefined) {
+        values[col.name] = values[col.defaultFrom];
       }
     }
 

src/cli/resources/groups.ts

@@ -1,15 +1,20 @@
+import { randomUUID } from 'crypto';
+
 import type { McpServerConfig } from '../../container-config.js';
 import { buildAgentGroupImage, killContainer, wakeContainer } from '../../container-runner.js';
 import { restartAgentGroupContainers } from '../../container-restart.js';
+import { createAgentGroup } from '../../db/agent-groups.js';
 import { getDb, hasTable } from '../../db/connection.js';
 import { getSession } from '../../db/sessions.js';
 import { writeSessionMessage } from '../../session-manager.js';
 import {
+  ensureContainerConfig,
   getContainerConfig,
   updateContainerConfigScalars,
   updateContainerConfigJson,
 } from '../../db/container-configs.js';
-import type { ContainerConfigRow } from '../../types.js';
+import { createAgentFromTemplate } from '../../templates/create-agent.js';
+import type { AgentGroup, ContainerConfigRow } from '../../types.js';
 import { registerResource } from '../crud.js';
 
 /** Deserialize JSON columns for display. */
@@ -58,11 +63,42 @@ registerResource({
     },
     { name: 'created_at', type: 'string', description: 'Auto-set.', generated: true },
   ],
-  // `delete` is intentionally not in `operations` — the generic single-table
-  // DELETE violates FK constraints (see #2525). The cascading handler is
-  // provided as `customOperations.delete` below.
-  operations: { list: 'open', get: 'open', create: 'approval', update: 'approval' },
+  // `create` and `delete` are intentionally not in `operations` — create needs
+  // a `--template` branch (below); the generic single-table DELETE violates FK
+  // constraints (see #2525). Both are provided as `customOperations`.
+  operations: { list: 'open', get: 'open', update: 'approval' },
   customOperations: {
+    create: {
+      access: 'approval',
+      description:
+        'Create an agent group. With --template <ref>, stamp from a local template under templates/ ' +
+        '(MCP servers + instructions + skills); else insert a bare row (--name, --folder).',
+      handler: async (args) => {
+        if (args.template) {
+          return createAgentFromTemplate(String(args.template), {
+            name: args.name ? String(args.name) : undefined,
+          });
+        }
+        const name = args.name ? String(args.name) : '';
+        const folder = args.folder ? String(args.folder) : '';
+        if (!name) throw new Error('--name is required');
+        if (!folder) throw new Error('--folder is required');
+        const group: AgentGroup = {
+          id: randomUUID(),
+          name,
+          folder,
+          agent_provider: null,
+          created_at: new Date().toISOString(),
+        };
+        createAgentGroup(group);
+        // Seed the config row now so the group is created on the instance
+        // default (ensureContainerConfig stamps it) and is spawnable without
+        // waiting for the startup backfill. Per-group overrides via
+        // `groups config update --provider` still win.
+        ensureContainerConfig(group.id);
+        return group;
+      },
+    },
     delete: {
       access: 'approval',
       description:

src/cli/resources/index.ts

@@ -9,6 +9,7 @@ import './users.js';
 import './roles.js';
 import './members.js';
 import './destinations.js';
+import './policies.js';
 import './user-dms.js';
 import './dropped-messages.js';
 import './approvals.js';

src/cli/resources/messaging-groups.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Regression test: `ncl messaging-groups create` must satisfy the NOT NULL
+ * `instance` column without an operator-supplied `--instance`. The column has
+ * no CLI flag at the operator's altitude (the default instance IS the channel
+ * type), so the generic CRUD insert defaults it to `channel_type` — matching
+ * `createMessagingGroup`'s `instance ?? channel_type` fallback on the router
+ * path. Delete the `instance` column / `defaultFrom` wiring in
+ * `messaging-groups.ts` and this goes red: the insert fails the NOT NULL.
+ */
+import fs from 'fs';
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+
+vi.mock('../../container-runner.js', () => ({
+  wakeContainer: vi.fn().mockResolvedValue(undefined),
+  isContainerRunning: vi.fn().mockReturnValue(false),
+  getActiveContainerCount: vi.fn().mockReturnValue(0),
+  killContainer: vi.fn(),
+}));
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/nanoclaw-test-cli-msggroups' };
+});
+
+const TEST_DIR = '/tmp/nanoclaw-test-cli-msggroups';
+
+import { initTestDb, closeDb, runMigrations } from '../../db/index.js';
+import { getMessagingGroupByPlatform } from '../../db/messaging-groups.js';
+import { dispatch } from '../dispatch.js';
+// Side-effect import: registers the `messaging-groups-create` command.
+import './messaging-groups.js';
+
+describe('messaging-groups CLI create defaults instance to channel_type', () => {
+  beforeEach(() => {
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+    runMigrations(initTestDb());
+  });
+
+  afterEach(() => {
+    closeDb();
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  });
+
+  it('create without --instance sets instance = channel_type', async () => {
+    // caller: 'host' is the post-approval re-entry path for create (approval op).
+    const resp = await dispatch(
+      {
+        id: 'req-1',
+        command: 'messaging-groups-create',
+        args: { channel_type: 'telegram', platform_id: '12345' },
+      },
+      { caller: 'host' },
+    );
+
+    expect(resp.ok).toBe(true);
+    const row = getMessagingGroupByPlatform('telegram', '12345');
+    expect(row).toBeDefined();
+    expect(row?.instance).toBe('telegram');
+  });
+
+  it('create with an explicit --instance keeps that value', async () => {
+    const resp = await dispatch(
+      {
+        id: 'req-2',
+        command: 'messaging-groups-create',
+        args: { channel_type: 'telegram', platform_id: '67890', instance: 'work' },
+      },
+      { caller: 'host' },
+    );
+
+    expect(resp.ok).toBe(true);
+    expect(getMessagingGroupByPlatform('telegram', '67890', 'work')?.instance).toBe('work');
+  });
+});

src/cli/resources/messaging-groups.ts

@@ -23,6 +23,14 @@ registerResource({
         'Platform-specific chat ID. Format varies: Telegram chat ID, Discord channel snowflake, Slack channel ID, phone number, email address.',
       required: true,
     },
+    {
+      name: 'instance',
+      type: 'string',
+      description:
+        'Adapter instance that owns this chat, when running N adapters of one channel type. Defaults to channel_type (the default instance) when omitted.',
+      defaultFrom: 'channel_type',
+      updatable: true,
+    },
     {
       name: 'name',
       type: 'string',

src/cli/resources/policies.ts

@@ -0,0 +1,56 @@
+import { getAgentGroup } from '../../db/agent-groups.js';
+import { removeMessagePolicy, setMessagePolicy } from '../../modules/agent-to-agent/db/agent-message-policies.js';
+import { registerResource } from '../crud.js';
+
+registerResource({
+  name: 'policy',
+  plural: 'policies',
+  table: 'agent_message_policies',
+  description:
+    'Agent-to-agent approval policy. A row requires every message from one agent to another to be approved by a human before delivery — without un-wiring the connection. No row = free flow. Directed and per-pair: gate both directions with two policies. Operator-only (agents cannot manage their own gates).',
+  idColumn: 'from_agent_group_id',
+  columns: [
+    { name: 'from_agent_group_id', type: 'string', description: 'Source agent group. References agent_groups.id.' },
+    { name: 'to_agent_group_id', type: 'string', description: 'Target agent group. References agent_groups.id.' },
+    {
+      name: 'approver',
+      type: 'string',
+      description: 'User-id who approves each gated message (required). Only this user (or an owner) can approve.',
+    },
+    { name: 'created_at', type: 'string', description: 'Auto-set.' },
+  ],
+  operations: { list: 'open' },
+  customOperations: {
+    set: {
+      access: 'approval',
+      description:
+        'Require approval for messages from one agent to another. Use --from <agent-group-id> --to <agent-group-id> --approver <user-id>. Only the named approver (or an owner) can approve.',
+      handler: async (args) => {
+        const from = args.from as string;
+        const to = args.to as string;
+        const approver = args.approver as string;
+        if (!from) throw new Error('--from is required');
+        if (!to) throw new Error('--to is required');
+        if (!approver) throw new Error('--approver is required');
+        if (from === to) throw new Error('--from and --to must differ (self-messages are never gated)');
+        if (!getAgentGroup(from)) throw new Error(`source agent group not found: ${from}`);
+        if (!getAgentGroup(to)) throw new Error(`target agent group not found: ${to}`);
+
+        setMessagePolicy(from, to, approver, new Date().toISOString());
+        return { from_agent_group_id: from, to_agent_group_id: to, approver };
+      },
+    },
+    remove: {
+      access: 'approval',
+      description: 'Remove an approval policy (back to free flow). Use --from <agent-group-id> --to <agent-group-id>.',
+      handler: async (args) => {
+        const from = args.from as string;
+        const to = args.to as string;
+        if (!from) throw new Error('--from is required');
+        if (!to) throw new Error('--to is required');
+        if (!removeMessagePolicy(from, to)) throw new Error('policy not found');
+        return { removed: { from_agent_group_id: from, to_agent_group_id: to } };
+      },
+    },
+  },
+});

src/config.ts

@@ -6,9 +6,27 @@ import { getContainerImageBase, getDefaultContainerImage, getInstallSlug } from
 import { isValidTimezone } from './timezone.js';
 
 // Read config values from .env (falls back to process.env).
-const envConfig = readEnvFile(['ASSISTANT_NAME', 'ASSISTANT_HAS_OWN_NUMBER', 'ONECLI_URL', 'ONECLI_API_KEY', 'TZ']);
+const envConfig = readEnvFile([
+  'ASSISTANT_NAME',
+  'ASSISTANT_HAS_OWN_NUMBER',
+  'ONECLI_URL',
+  'ONECLI_API_KEY',
+  'TZ',
+  'DEFAULT_AGENT_PROVIDER',
+]);
 
 export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || envConfig.ASSISTANT_NAME || 'Andy';
+
+// Instance-wide default agent provider for newly created groups. `claude` (the
+// built-in provider) when unset, so existing installs are unaffected on upgrade.
+// Applied only at group-creation time (stamped onto the config row) — never in
+// provider resolution — so existing groups are never retroactively flipped.
+// Per-group `ncl groups config update --provider` still overrides it.
+export const DEFAULT_AGENT_PROVIDER = (
+  process.env.DEFAULT_AGENT_PROVIDER ||
+  envConfig.DEFAULT_AGENT_PROVIDER ||
+  'claude'
+).toLowerCase();
 export const ASSISTANT_HAS_OWN_NUMBER =
   (process.env.ASSISTANT_HAS_OWN_NUMBER || envConfig.ASSISTANT_HAS_OWN_NUMBER) === 'true';
 
@@ -22,6 +40,12 @@ export const SENDER_ALLOWLIST_PATH = path.join(HOME_DIR, '.config', 'nanoclaw',
 export const STORE_DIR = path.resolve(PROJECT_ROOT, 'store');
 export const GROUPS_DIR = path.resolve(PROJECT_ROOT, 'groups');
 export const DATA_DIR = path.resolve(PROJECT_ROOT, 'data');
+// Local agent-template library. Committed but ships empty (+ README). Resolved
+// once at load. Override to another LOCAL path via NANOCLAW_TEMPLATES_DIR; never
+// a remote URL, never an ncl flag, never runtime-mutable.
+export const TEMPLATES_DIR = process.env.NANOCLAW_TEMPLATES_DIR
+  ? path.resolve(process.env.NANOCLAW_TEMPLATES_DIR)
+  : path.resolve(PROJECT_ROOT, 'templates');
 
 // Per-checkout image tag so two installs on the same host don't share
 // `nanoclaw-agent:latest` and clobber each other on rebuild.
@@ -38,6 +62,11 @@ export const ONECLI_API_KEY = process.env.ONECLI_API_KEY || envConfig.ONECLI_API
 export const MAX_MESSAGES_PER_PROMPT = Math.max(1, parseInt(process.env.MAX_MESSAGES_PER_PROMPT || '10', 10) || 10);
 export const IDLE_TIMEOUT = parseInt(process.env.IDLE_TIMEOUT || '1800000', 10); // 30min default — how long to keep container alive after last result
 export const MAX_CONCURRENT_CONTAINERS = Math.max(1, parseInt(process.env.MAX_CONCURRENT_CONTAINERS || '5', 10) || 5);
+// Per-container resource caps, passed through to `docker run`. Default empty =
+// no flag added = today's unbounded behavior (don't OOM existing OSS workloads).
+// Operators opt in: CONTAINER_CPU_LIMIT=2, CONTAINER_MEMORY_LIMIT=8g.
+export const CONTAINER_CPU_LIMIT = process.env.CONTAINER_CPU_LIMIT || '';
+export const CONTAINER_MEMORY_LIMIT = process.env.CONTAINER_MEMORY_LIMIT || '';
 
 function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

src/container-runner.test.ts

@@ -47,6 +47,37 @@ describe('buildContainerArgs ordering invariant (structural)', () => {
   });
 });
 
+describe('per-container resource limits (structural)', () => {
+  // CONTAINER_CPU_LIMIT / CONTAINER_MEMORY_LIMIT pass through to `docker run` as
+  // --cpus / --memory, but only when set. The default is empty string → no flag →
+  // today's unbounded behavior (don't OOM existing OSS workloads). Swap is not
+  // managed here (a swapless host makes --memory a hard cap). buildContainerArgs
+  // needs a live gateway to drive, so guard the wiring structurally: the flags
+  // must be pushed, and each must be guarded by its env knob so empty emits nothing.
+  it('reads both limit knobs from config', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'src', 'container-runner.ts'), 'utf-8');
+    expect(src).toContain('CONTAINER_CPU_LIMIT');
+    expect(src).toContain('CONTAINER_MEMORY_LIMIT');
+  });
+
+  it('guards --cpus behind a truthy CONTAINER_CPU_LIMIT', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'src', 'container-runner.ts'), 'utf-8');
+    expect(src).toMatch(/if \(CONTAINER_CPU_LIMIT\)[\s\S]*?args\.push\('--cpus', CONTAINER_CPU_LIMIT\)/);
+  });
+
+  it('guards --memory behind a truthy CONTAINER_MEMORY_LIMIT (and sets no swap flag)', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'src', 'container-runner.ts'), 'utf-8');
+    expect(src).toMatch(/if \(CONTAINER_MEMORY_LIMIT\) args\.push\('--memory', CONTAINER_MEMORY_LIMIT\)/);
+    expect(src).not.toContain('--memory-swap');
+  });
+
+  it('defaults both knobs to empty string in config (no flag = unbounded)', () => {
+    const cfg = fs.readFileSync(path.join(process.cwd(), 'src', 'config.ts'), 'utf-8');
+    expect(cfg).toContain("CONTAINER_CPU_LIMIT = process.env.CONTAINER_CPU_LIMIT || ''");
+    expect(cfg).toContain("CONTAINER_MEMORY_LIMIT = process.env.CONTAINER_MEMORY_LIMIT || ''");
+  });
+});
+
 describe('container boot-failure tripwire (structural)', () => {
   // A container that dies at boot (unknown provider, missing CLI binary, bad
   // config) explains itself only on stderr — which logs at debug, below the

src/container-runner.ts

@@ -10,9 +10,11 @@ import path from 'path';
 import { OneCLI } from '@onecli-sh/sdk';
 
 import {
+  CONTAINER_CPU_LIMIT,
   CONTAINER_IMAGE,
   CONTAINER_IMAGE_BASE,
   CONTAINER_INSTALL_LABEL,
+  CONTAINER_MEMORY_LIMIT,
   DATA_DIR,
   GROUPS_DIR,
   ONECLI_API_KEY,
@@ -434,6 +436,13 @@ async function buildContainerArgs(
 ): Promise<string[]> {
   const args: string[] = ['run', '--rm', '--name', containerName, '--label', CONTAINER_INSTALL_LABEL];
 
+  // Per-container resource caps (opt-in; empty = unbounded, today's behavior).
+  // Only --memory is set. Whether that's a hard cap depends on the host having no
+  // swap (a deployment concern) — on a swapless host --memory is hard and a runaway
+  // is OOM-killed; we don't manage swap from here.
+  if (CONTAINER_CPU_LIMIT) args.push('--cpus', CONTAINER_CPU_LIMIT);
+  if (CONTAINER_MEMORY_LIMIT) args.push('--memory', CONTAINER_MEMORY_LIMIT);
+
   // Environment — only vars read by code we don't own.
   // Everything NanoClaw-specific is in container.json (read by runner at startup).
   args.push('-e', `TZ=${TIMEZONE}`);

src/db/container-configs.test.ts

@@ -0,0 +1,59 @@
+/**
+ * ensureContainerConfig provider stamping (global-default-provider feature).
+ *
+ * Two load-bearing guarantees:
+ *   1. A fresh row is stamped with the given provider (claude → NULL), so a new
+ *      group is created on the instance default.
+ *   2. An existing row is never overwritten (INSERT OR IGNORE), so enabling a
+ *      non-claude default never retroactively flips existing groups.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { initTestDb, closeDb } from './connection.js';
+import { runMigrations } from './migrations/index.js';
+import { createAgentGroup } from './agent-groups.js';
+import { ensureContainerConfig, getContainerConfig } from './container-configs.js';
+
+function makeGroup(id: string): void {
+  createAgentGroup({ id, name: id, folder: id, agent_provider: null, created_at: new Date().toISOString() });
+}
+
+describe('ensureContainerConfig provider stamping', () => {
+  beforeEach(() => {
+    const db = initTestDb();
+    runMigrations(db);
+  });
+  afterEach(() => {
+    closeDb();
+  });
+
+  it('stamps a non-default provider on a fresh row; claude is stored as NULL', () => {
+    makeGroup('ag-codex');
+    ensureContainerConfig('ag-codex', 'codex');
+    expect(getContainerConfig('ag-codex')?.provider).toBe('codex');
+
+    makeGroup('ag-claude');
+    ensureContainerConfig('ag-claude', 'claude');
+    expect(getContainerConfig('ag-claude')?.provider).toBeNull();
+
+    // Casing is normalized to match what resolution lowercases to.
+    makeGroup('ag-cased');
+    ensureContainerConfig('ag-cased', 'Codex');
+    expect(getContainerConfig('ag-cased')?.provider).toBe('codex');
+
+    makeGroup('ag-cased-claude');
+    ensureContainerConfig('ag-cased-claude', 'Claude');
+    expect(getContainerConfig('ag-cased-claude')?.provider).toBeNull();
+  });
+
+  it('never overwrites an existing row — existing groups are not flipped', () => {
+    makeGroup('ag-existing');
+    ensureContainerConfig('ag-existing', 'codex'); // existing group already on codex
+    expect(getContainerConfig('ag-existing')?.provider).toBe('codex');
+
+    // A later bare ensure (defensive re-init, or a changed instance default)
+    // must NOT change it — INSERT OR IGNORE keeps the row frozen.
+    ensureContainerConfig('ag-existing');
+    expect(getContainerConfig('ag-existing')?.provider).toBe('codex');
+  });
+});

src/db/container-configs.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_AGENT_PROVIDER } from '../config.js';
 import type { ContainerConfigRow } from '../types.js';
 import { getDb } from './connection.js';
 
@@ -39,14 +40,36 @@ export function createContainerConfig(config: ContainerConfigRow): void {
     .run(config);
 }
 
-/** Create an empty config row with sensible defaults. Idempotent — no-ops if row exists. */
-export function ensureContainerConfig(agentGroupId: string): void {
+/**
+ * Create a config row if one doesn't exist, stamping the provider. Idempotent —
+ * no-ops if the row already exists, so an existing group's provider is never
+ * overwritten (load-bearing: this is how the global default stays "new groups
+ * only" for groups that already have a row).
+ *
+ * An absent `provider` takes the instance default (`DEFAULT_AGENT_PROVIDER`);
+ * `claude` and an absent value that resolves to claude are stored as NULL — the
+ * column means "follows the built-in default", matching pre-feature rows.
+ */
+export function ensureContainerConfig(agentGroupId: string, provider?: string | null): void {
+  // Single chokepoint for the instance default: a fresh row with no explicit
+  // provider is stamped with DEFAULT_AGENT_PROVIDER, so every new-group creation
+  // path inherits it without each having to remember. INSERT OR IGNORE keeps an
+  // EXISTING row untouched — so this stays "new groups only" for any group that
+  // already has a config row (backfillContainerConfigs seeds one for every group
+  // at host startup; a non-claude default would only reach a row-less *legacy*
+  // group if a creation script reused it before that first backfill ran). Callers
+  // that know the provider (subagent → parent's, spawn → resolved) pass it
+  // explicitly and override the default.
+  // `claude` (the built-in default) and casing normalize to NULL/lowercase so the
+  // column matches what resolution lowercases to.
+  const normalized = (provider ?? DEFAULT_AGENT_PROVIDER).toLowerCase();
+  const stamped = normalized && normalized !== 'claude' ? normalized : null;
   getDb()
     .prepare(
-      `INSERT OR IGNORE INTO container_configs (agent_group_id, updated_at)
-       VALUES (?, ?)`,
+      `INSERT OR IGNORE INTO container_configs (agent_group_id, provider, updated_at)
+       VALUES (?, ?, ?)`,
     )
-    .run(agentGroupId, new Date().toISOString());
+    .run(agentGroupId, stamped, new Date().toISOString());
 }
 
 /** Update scalar fields on a config row. Only touches fields present in `updates`. */

src/db/migrations/017-agent-message-policies.ts

@@ -0,0 +1,20 @@
+import type Database from 'better-sqlite3';
+
+import type { Migration } from './index.js';
+
+/** Per-message approval gate on an agent-to-agent connection; no row = free flow. */
+export const migration017: Migration = {
+  version: 17,
+  name: 'agent-message-policies',
+  up(db: Database.Database) {
+    db.exec(`
+      CREATE TABLE agent_message_policies (
+        from_agent_group_id TEXT NOT NULL REFERENCES agent_groups(id),
+        to_agent_group_id   TEXT NOT NULL REFERENCES agent_groups(id),
+        approver            TEXT NOT NULL,
+        created_at          TEXT NOT NULL,
+        PRIMARY KEY (from_agent_group_id, to_agent_group_id)
+      );
+    `);
+  },
+};

src/db/migrations/018-approvals-approver-user-id.ts

@@ -0,0 +1,14 @@
+import type { Migration } from './index.js';
+
+/**
+ * `approver_user_id` on `pending_approvals`: when an approval names a specific
+ * approver (an a2a message-gate policy's approver), only that exact user may
+ * resolve it. NULL keeps the existing group/owner authorization path.
+ */
+export const migration018: Migration = {
+  version: 18,
+  name: 'approvals-approver-user-id',
+  up(db) {
+    db.exec(`ALTER TABLE pending_approvals ADD COLUMN approver_user_id TEXT;`);
+  },
+};

src/db/migrations/index.ts

@@ -4,6 +4,7 @@ import { log } from '../../log.js';
 import { migration001 } from './001-initial.js';
 import { migration002 } from './002-chat-sdk-state.js';
 import { moduleAgentToAgentDestinations } from './module-agent-to-agent-destinations.js';
+import { migration017 } from './017-agent-message-policies.js';
 import { migration008 } from './008-dropped-messages.js';
 import { migration009 } from './009-drop-pending-credentials.js';
 import { migration010 } from './010-engage-modes.js';
@@ -15,6 +16,7 @@ import { migration015 } from './015-cli-scope.js';
 import { migration016 } from './016-messaging-group-instance.js';
 import { moduleApprovalsPendingApprovals } from './module-approvals-pending-approvals.js';
 import { moduleApprovalsTitleOptions } from './module-approvals-title-options.js';
+import { migration018 } from './018-approvals-approver-user-id.js';
 
 export interface Migration {
   version: number;
@@ -36,7 +38,9 @@ export const migrations: Migration[] = [
   migration002,
   moduleApprovalsPendingApprovals,
   moduleAgentToAgentDestinations,
+  migration017,
   moduleApprovalsTitleOptions,
+  migration018,
   migration008,
   migration009,
   migration010,

src/db/sessions.ts

@@ -155,11 +155,11 @@ export function createPendingApproval(
       `INSERT OR IGNORE INTO pending_approvals
          (approval_id, session_id, request_id, action, payload, created_at,
           agent_group_id, channel_type, platform_id, platform_message_id, expires_at, status,
-          title, options_json)
+          title, options_json, approver_user_id)
        VALUES
          (@approval_id, @session_id, @request_id, @action, @payload, @created_at,
           @agent_group_id, @channel_type, @platform_id, @platform_message_id, @expires_at, @status,
-          @title, @options_json)`,
+          @title, @options_json, @approver_user_id)`,
     )
     .run({
       session_id: null,
@@ -169,6 +169,7 @@ export function createPendingApproval(
       platform_message_id: null,
       expires_at: null,
       status: 'pending',
+      approver_user_id: null,
       ...pa,
     });
   return result.changes > 0;
@@ -184,6 +185,28 @@ export function updatePendingApprovalStatus(approvalId: string, status: PendingA
   getDb().prepare('UPDATE pending_approvals SET status = ? WHERE approval_id = ?').run(status, approvalId);
 }
 
+/**
+ * Park an approval in the "rejected, awaiting reason" hold: the admin clicked
+ * "Reject with reason…" and we're waiting for their one-line reply. `expiresAt`
+ * is the deadline after which the host sweep finalizes a plain reject (so a
+ * ghosted hold never strands the requesting agent). Reuses the otherwise-unused
+ * `expires_at` column on module-initiated rows.
+ */
+export function markApprovalAwaitingReason(approvalId: string, expiresAt: string): void {
+  getDb()
+    .prepare("UPDATE pending_approvals SET status = 'awaiting_reason', expires_at = ? WHERE approval_id = ?")
+    .run(expiresAt, approvalId);
+}
+
+/** Awaiting-reason approvals whose reply window has elapsed — the sweep's ghost set. */
+export function getExpiredAwaitingReasonApprovals(nowIso: string): PendingApproval[] {
+  return getDb()
+    .prepare(
+      "SELECT * FROM pending_approvals WHERE status = 'awaiting_reason' AND expires_at IS NOT NULL AND expires_at <= ?",
+    )
+    .all(nowIso) as PendingApproval[];
+}
+
 export function deletePendingApproval(approvalId: string): void {
   getDb().prepare('DELETE FROM pending_approvals WHERE approval_id = ?').run(approvalId);
 }

src/group-init.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 
-import { DATA_DIR, GROUPS_DIR } from './config.js';
+import { DATA_DIR, DEFAULT_AGENT_PROVIDER, GROUPS_DIR } from './config.js';
 import { ensureContainerConfig } from './db/container-configs.js';
 import { log } from './log.js';
 import { providerProvidesAgentSurfaces } from './providers/provider-container-registry.js';
@@ -53,11 +53,18 @@ export function initGroupFilesystem(
 ): void {
   const initialized: string[] = [];
 
-  // Default agent surfaces apply unless the group's provider declares (at
-  // registration) that it provides its own. Callers that don't know the
-  // provider omit it — unregistered/unknown names report no capabilities,
-  // so the default surfaces are written, exactly as before this seam.
-  const defaultSurfaces = !providerProvidesAgentSurfaces(opts?.provider);
+  // `opts.provider` absent means "caller has no provider opinion" — for a
+  // brand-new group that resolves to the instance default, so the scaffold and
+  // the stamped config row both match it. A caller that knows the provider
+  // (subagent → parent's, spawn → resolved, setup → operator's pick) passes it
+  // explicitly — including `claude` — which pins the group and skips the
+  // default. ensureContainerConfig is INSERT OR IGNORE, so this only stamps a
+  // genuinely new group; existing rows are never touched.
+  const providerHint = (opts?.provider ?? DEFAULT_AGENT_PROVIDER).toLowerCase();
+
+  // Default agent surfaces apply unless the provider declares (at registration)
+  // that it provides its own.
+  const defaultSurfaces = !providerProvidesAgentSurfaces(providerHint);
 
   // 1. groups/<folder>/ — group memory + working dir
   const groupDir = path.resolve(GROUPS_DIR, group.folder);
@@ -106,8 +113,10 @@ export function initGroupFilesystem(
   }
 
   // Ensure container_configs row exists in the DB. Idempotent — no-op if
-  // the row already exists (e.g. created by backfill or group creation).
-  ensureContainerConfig(group.id);
+  // the row already exists (e.g. created by backfill or group creation). On a
+  // fresh row, stamp the resolved provider hint so a new group is created on
+  // the instance default (or the caller's explicit pick).
+  ensureContainerConfig(group.id, providerHint);
   initialized.push('container_configs');
 
   // 2. data/v2-sessions/<id>/.claude-shared/ — Claude state + per-group skills

src/group-persona.test.ts

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { PERSONA_PREPEND_FILE, readGroupPersona } from './group-persona.js';
+
+const TMP = '/tmp/nanoclaw-group-persona-test';
+
+beforeEach(() => {
+  fs.rmSync(TMP, { recursive: true, force: true });
+  fs.mkdirSync(TMP, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(TMP, { recursive: true, force: true });
+});
+
+describe('readGroupPersona', () => {
+  it('returns null when the prepend file is absent', () => {
+    expect(readGroupPersona(TMP)).toBeNull();
+  });
+
+  it('returns null for an empty / whitespace-only file', () => {
+    fs.writeFileSync(path.join(TMP, PERSONA_PREPEND_FILE), '  \n\n');
+    expect(readGroupPersona(TMP)).toBeNull();
+  });
+
+  it('returns the trimmed content when present', () => {
+    fs.writeFileSync(path.join(TMP, PERSONA_PREPEND_FILE), '\nYou are an SDR agent.\n\n');
+    expect(readGroupPersona(TMP)).toBe('You are an SDR agent.');
+  });
+});

src/group-persona.ts

@@ -0,0 +1,30 @@
+/**
+ * Provider-neutral per-group persona ("instructions prepend").
+ *
+ * A template stamps its standing instructions here (src/templates/create-agent.ts).
+ * Each provider's project-doc composer inlines this content at the TOP of the
+ * doc it generates every spawn — `CLAUDE.md` (Claude, src/claude-md-compose.ts)
+ * or `AGENTS.md` (Codex, src/providers/codex-agents-md.ts on the providers
+ * branch) — so a template persona lands at system-prompt tier on every provider
+ * rather than in a recall-tier memory file.
+ *
+ * This module is the single owner of the filename + read semantics so the two
+ * composers (one on main, one on the providers donor branch) never hardcode the
+ * path independently. Absent file ⇒ null ⇒ no-op for non-template groups.
+ */
+import fs from 'fs';
+import path from 'path';
+
+/** Per-group host file holding the persona prepend. Never regenerated — persistent. */
+export const PERSONA_PREPEND_FILE = 'instructions.prepend.md';
+
+/**
+ * Read a group's persona prepend from its host dir, or null if absent/empty.
+ * `groupDir` is the per-group host directory (`GROUPS_DIR/<folder>`).
+ */
+export function readGroupPersona(groupDir: string): string | null {
+  const file = path.join(groupDir, PERSONA_PREPEND_FILE);
+  if (!fs.existsSync(file)) return null;
+  const content = fs.readFileSync(file, 'utf-8').trim();
+  return content.length > 0 ? content : null;
+}

src/group-skills.test.ts

@@ -0,0 +1,71 @@
+import fs from 'fs';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const TEST_ROOT = '/tmp/nanoclaw-group-skills-test';
+const DATA_DIR = path.join(TEST_ROOT, 'data');
+
+vi.mock('./config.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./config.js')>()),
+  DATA_DIR: '/tmp/nanoclaw-group-skills-test/data',
+}));
+
+import { materializeTemplateSkills } from './group-skills.js';
+
+function templateSkill(groupId: string, name: string, file: string, content: string): void {
+  const dir = path.join(DATA_DIR, 'v2-sessions', groupId, '.claude-shared', 'skills', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, file), content);
+}
+
+beforeEach(() => {
+  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
+  fs.mkdirSync(TEST_ROOT, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
+});
+
+describe('materializeTemplateSkills', () => {
+  it('copies real template-skill dirs into the provider skills dir', () => {
+    templateSkill('g1', 'widget', 'SKILL.md', 'body');
+    const dest = path.join(TEST_ROOT, 'grp1', '.agents', 'skills');
+
+    materializeTemplateSkills('g1', dest);
+
+    expect(fs.readFileSync(path.join(dest, 'widget', 'SKILL.md'), 'utf-8')).toBe('body');
+    expect(fs.lstatSync(path.join(dest, 'widget')).isSymbolicLink()).toBe(false);
+  });
+
+  it('is a no-op when the group has no template skills', () => {
+    const dest = path.join(TEST_ROOT, 'grp2', '.agents', 'skills');
+    materializeTemplateSkills('g2', dest);
+    expect(fs.existsSync(dest)).toBe(false);
+  });
+
+  it('overwrites its own skill dirs but leaves other destination entries intact', () => {
+    templateSkill('g3', 'widget', 'SKILL.md', 'new');
+    const dest = path.join(TEST_ROOT, 'grp3', '.agents', 'skills');
+    fs.mkdirSync(dest, { recursive: true });
+    // Stale copy of the same skill (should be refreshed) + a coexisting
+    // shared-skill symlink (must NOT be touched — it is provider-owned).
+    fs.mkdirSync(path.join(dest, 'widget'), { recursive: true });
+    fs.writeFileSync(path.join(dest, 'widget', 'SKILL.md'), 'old');
+    fs.symlinkSync('/app/skills/shared', path.join(dest, 'shared'));
+
+    materializeTemplateSkills('g3', dest);
+
+    expect(fs.readFileSync(path.join(dest, 'widget', 'SKILL.md'), 'utf-8')).toBe('new');
+    expect(fs.lstatSync(path.join(dest, 'shared')).isSymbolicLink()).toBe(true);
+  });
+
+  it('does not destroy skills when dest equals the source (Claude reads source directly)', () => {
+    templateSkill('g4', 'widget', 'SKILL.md', 'body');
+    const src = path.join(DATA_DIR, 'v2-sessions', 'g4', '.claude-shared', 'skills');
+
+    materializeTemplateSkills('g4', src);
+
+    expect(fs.existsSync(path.join(src, 'widget', 'SKILL.md'))).toBe(true);
+  });
+});

src/group-skills.ts

@@ -0,0 +1,52 @@
+/**
+ * Provider-agnostic template-skill materialization.
+ *
+ * A template stamps its skills as REAL directories into the group-private store
+ * `data/v2-sessions/<group-id>/.claude-shared/skills/<name>` (src/templates/create-agent.ts).
+ * Claude reads that store directly — it is mounted at `~/.claude/skills`, and
+ * real dirs survive the symlink-only skill-link prune. Every OTHER surfaces-owning
+ * provider (codex, opencode, pi, …) reads a DIFFERENT per-group skills directory,
+ * often READ-ONLY-mounted, so the skills must be copied there host-side, before
+ * the container starts.
+ *
+ * This is the single shared spot that does that copy. Each provider's host-side
+ * container contribution calls it once with its own skills dir (codex →
+ * `.agents/skills`; a future provider → whatever it reads). Adding a provider
+ * therefore adds one call, not a new mirror implementation. The copied dirs are
+ * real (not symlinks), so they survive providers' symlink-only prunes and persist
+ * across respawns.
+ *
+ * This module is a main-owned seam that provider payloads (on the `providers`
+ * donor branch) import — mirrors src/group-persona.ts.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { DATA_DIR } from './config.js';
+
+/** The group-private store templates stamp skills into (Claude's read plane). */
+function templateSkillsSource(agentGroupId: string): string {
+  return path.join(DATA_DIR, 'v2-sessions', agentGroupId, '.claude-shared', 'skills');
+}
+
+/**
+ * Copy a group's template skills into a provider's per-group skills directory.
+ * No-op if the group has no template skills, or if `destSkillsDir` IS the source
+ * (Claude, which reads the source directly — copying onto itself would delete it).
+ * Idempotent: overwrites each template skill so edits propagate on respawn. It
+ * manages only its own skill dirs — other entries in the destination (e.g. a
+ * provider's shared-skill symlinks) are left untouched.
+ */
+export function materializeTemplateSkills(agentGroupId: string, destSkillsDir: string): void {
+  const src = templateSkillsSource(agentGroupId);
+  if (!fs.existsSync(src)) return;
+  if (path.resolve(src) === path.resolve(destSkillsDir)) return;
+
+  fs.mkdirSync(destSkillsDir, { recursive: true });
+  for (const name of fs.readdirSync(src)) {
+    if (!fs.statSync(path.join(src, name)).isDirectory()) continue;
+    const dest = path.join(destSkillsDir, name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(path.join(src, name), dest, { recursive: true });
+  }
+}

src/host-sweep.ts

@@ -152,6 +152,18 @@ async function sweep(): Promise<void> {
     log.error('Host sweep error', { err });
   }
 
+  // Finalize any "Reject with reason…" holds whose reply window elapsed (admin
+  // ghosted, or the host restarted mid-capture). Central-DB scan, once per tick
+  // — not per session.
+  // MODULE-HOOK:approvals-reason-sweep:start
+  try {
+    const { sweepAwaitingReasonRejects } = await import('./modules/approvals/index.js');
+    await sweepAwaitingReasonRejects();
+  } catch (err) {
+    log.error('Reject-with-reason sweep failed', { err });
+  }
+  // MODULE-HOOK:approvals-reason-sweep:end
+
   setTimeout(sweep, SWEEP_INTERVAL_MS);
 }
 

src/inbox-safety.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared containment guards for per-message inbox directories.
+ *
+ * Session dirs are mounted writable into agent containers, so a compromised
+ * agent can pre-place a symlink inside its own session dir and wait for the
+ * host to write through it — landing attacker-influenced bytes outside the
+ * sandbox (CWE-59). Both inbound paths that materialise files into a session's
+ * `inbox/<messageId>/` directory route through `ensureContainedInboxDir`:
+ *   - channel-inbound attachments (`extractAttachmentFiles` in session-manager)
+ *   - agent-to-agent forwarded files (`forwardAttachedFiles` in agent-route)
+ *
+ * Keeping the guard in one place means both paths defend identically; the fix
+ * for GHSA #2828 originally lived only in the A2A path and the channel path had
+ * the same gap (a symlinked `inbox` root was followed silently).
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { log } from './log.js';
+
+/** True if `child` is `parent` itself or nested within it (no traversal/escape). */
+export function isPathInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Resolve and create `<inboxRoot>/<messageId>`, refusing pre-placed symlinks a
+ * compromised container could use to redirect host writes outside the session.
+ *
+ * Guards, in order:
+ *   1. lstat the inbox ROOT — reject if it is a symlink or a non-directory.
+ *      Without this, a symlinked `inbox` is silently followed by mkdir AND the
+ *      containment check in step 4 passes, because it compares against the
+ *      already-followed (escaped) root. This is the gap that affected the
+ *      channel-inbound path.
+ *   2. lstat the per-message subdir — reject a pre-placed symlink/non-dir.
+ *      lstat does not follow the final path component, so it sees the link
+ *      itself even when the link target does not exist.
+ *   3. mkdir the subdir (recursive).
+ *   4. realpath containment — the resolved subdir must stay within the resolved
+ *      inbox root (defence in depth; symlinks are already ruled out above).
+ *
+ * Returns the resolved, contained subdir path (write into it with an exclusive
+ * flag — `COPYFILE_EXCL` / `wx` — so a pre-existing symlinked *file* can't be
+ * followed either), or `null` if any guard tripped. On `null` the caller logs
+ * its own context and skips; `context` is merged into the warn logs here so
+ * each call site stays diagnosable.
+ */
+export function ensureContainedInboxDir(
+  inboxRoot: string,
+  messageId: string,
+  context: Record<string, unknown>,
+): string | null {
+  const inboxDir = path.join(inboxRoot, messageId);
+
+  for (const dir of [inboxRoot, inboxDir]) {
+    try {
+      const st = fs.lstatSync(dir);
+      if (st.isSymbolicLink() || !st.isDirectory()) {
+        log.warn('inbox-safety: rejecting unsafe inbox path', { ...context, dir });
+        return null;
+      }
+    } catch {
+      // Does not exist yet — fine, mkdir below creates it.
+    }
+  }
+
+  fs.mkdirSync(inboxDir, { recursive: true });
+
+  try {
+    const realInboxDir = fs.realpathSync(inboxDir);
+    const realInboxRoot = fs.realpathSync(inboxRoot);
+    if (!isPathInside(realInboxRoot, realInboxDir)) {
+      log.warn('inbox-safety: inbox dir escaped inbox root', { ...context, inboxDir });
+      return null;
+    }
+    return realInboxDir;
+  } catch (err) {
+    log.warn('inbox-safety: failed to resolve inbox dir', { ...context, inboxDir, err });
+    return null;
+  }
+}

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

@@ -3,7 +3,8 @@ import fs from 'fs';
 import path from 'path';
 import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
 
-import { isSafeAttachmentName, routeAgentMessage } from './agent-route.js';
+import { forwardAttachedFiles, isSafeAttachmentName, routeAgentMessage } from './agent-route.js';
+import { log } from '../../log.js';
 import { createDestination } from './db/agent-destinations.js';
 import { initTestDb, closeDb, runMigrations, createAgentGroup } from '../../db/index.js';
 import { createSession, updateSession } from '../../db/sessions.js';
@@ -467,4 +468,129 @@ describe('routeAgentMessage return-path', () => {
     const parsed = JSON.parse(bRows[0].content);
     expect(parsed.attachments).toHaveLength(0);
   });
+
+  // #2828 — target-side symlink containment. A compromised target agent can
+  // write inside its own session dir; these tests prove it cannot redirect a
+  // forwarded attachment outside the session sandbox via a pre-placed symlink.
+
+  it('file forwarding (#2828): skips a symlinked target inbox dir, writes nothing outside', async () => {
+    const warnSpy = vi.spyOn(log, 'warn');
+    const canaryDir = path.join(TEST_DIR, 'canary-outside-inbox');
+    fs.mkdirSync(canaryDir, { recursive: true });
+
+    // Source has a real attachment to forward.
+    const outboxDir = path.join(sessionDir(A, S1.id), 'outbox', 'msg-evil-inbox');
+    fs.mkdirSync(outboxDir, { recursive: true });
+    fs.writeFileSync(path.join(outboxDir, 'pwn.txt'), 'attacker-bytes');
+
+    // Target pre-places its whole `inbox` as a symlink pointing outside.
+    const targetInbox = path.join(sessionDir(B, SB.id), 'inbox');
+    fs.rmSync(targetInbox, { recursive: true, force: true });
+    fs.symlinkSync(canaryDir, targetInbox);
+
+    await routeAgentMessage(
+      {
+        id: 'msg-evil-inbox',
+        platform_id: B,
+        content: JSON.stringify({ text: 'see attached', files: ['pwn.txt'] }),
+        in_reply_to: null,
+      },
+      S1,
+    );
+
+    // Message still routes — just with no attachments.
+    const bRows = readInbound(B, SB.id);
+    expect(bRows).toHaveLength(1);
+    expect(JSON.parse(bRows[0].content).attachments).toHaveLength(0);
+
+    // Nothing was written through the symlink to the canary location.
+    expect(fs.readdirSync(canaryDir)).toHaveLength(0);
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('file forwarding (#2828): skips a symlinked inbox/<msgId> subdir, writes nothing outside', async () => {
+    const warnSpy = vi.spyOn(log, 'warn');
+    const canaryDir = path.join(TEST_DIR, 'canary-outside-subdir');
+    fs.mkdirSync(canaryDir, { recursive: true });
+
+    const outboxDir = path.join(sessionDir(A, S1.id), 'outbox', 'msg-evil-subdir');
+    fs.mkdirSync(outboxDir, { recursive: true });
+    fs.writeFileSync(path.join(outboxDir, 'pwn.txt'), 'attacker-bytes');
+
+    // The forwarded a2a msg id generated inside routeAgentMessage is random, so
+    // a symlink can't be pre-placed at inbox/<that-id>. Drive forwardAttachedFiles
+    // directly with a fixed target message id and plant the symlink at that path.
+    const targetMsgId = 'evil-subdir-msg';
+    const realInbox = path.join(sessionDir(B, SB.id), 'inbox');
+    fs.mkdirSync(realInbox, { recursive: true });
+    fs.symlinkSync(canaryDir, path.join(realInbox, targetMsgId));
+
+    const attachments = forwardAttachedFiles(
+      { agentGroupId: A, sessionId: S1.id, messageId: 'msg-evil-subdir', filenames: ['pwn.txt'] },
+      { agentGroupId: B, sessionId: SB.id, messageId: targetMsgId },
+    );
+
+    expect(attachments).toHaveLength(0);
+    expect(fs.readdirSync(canaryDir)).toHaveLength(0);
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('file forwarding (#2828): refuses a pre-existing symlinked dst file (COPYFILE_EXCL)', async () => {
+    const warnSpy = vi.spyOn(log, 'warn');
+    const canaryFile = path.join(TEST_DIR, 'canary-dst-target.txt');
+    fs.writeFileSync(canaryFile, 'original-canary');
+
+    const outboxDir = path.join(sessionDir(A, S1.id), 'outbox', 'msg-evil-dst');
+    fs.mkdirSync(outboxDir, { recursive: true });
+    fs.writeFileSync(path.join(outboxDir, 'doc.txt'), 'attacker-bytes');
+
+    // inbox/<msgId>/ is a real dir, but contains a pre-placed symlink named
+    // exactly like the incoming attachment, pointing at the canary file.
+    // We can only do this once we know the a2a msg id, which is generated
+    // inside routeAgentMessage. So we instead drive forwardAttachedFiles
+    // directly with a fixed target message id.
+    const targetMsgId = 'fixed-evil-dst';
+    const realInboxSubdir = path.join(sessionDir(B, SB.id), 'inbox', targetMsgId);
+    fs.mkdirSync(realInboxSubdir, { recursive: true });
+    fs.symlinkSync(canaryFile, path.join(realInboxSubdir, 'doc.txt'));
+
+    const attachments = forwardAttachedFiles(
+      { agentGroupId: A, sessionId: S1.id, messageId: 'msg-evil-dst', filenames: ['doc.txt'] },
+      { agentGroupId: B, sessionId: SB.id, messageId: targetMsgId },
+    );
+
+    // The exclusive write failed → nothing forwarded.
+    expect(attachments).toHaveLength(0);
+    // Canary file untouched (symlink not followed/overwritten).
+    expect(fs.readFileSync(canaryFile, 'utf-8')).toBe('original-canary');
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it('file forwarding (#2828 regression): a normal forward still works end-to-end', async () => {
+    const outboxDir = path.join(sessionDir(A, S1.id), 'outbox', 'msg-ok-file');
+    fs.mkdirSync(outboxDir, { recursive: true });
+    fs.writeFileSync(path.join(outboxDir, 'ok.txt'), 'legit-bytes');
+
+    await routeAgentMessage(
+      {
+        id: 'msg-ok-file',
+        platform_id: B,
+        content: JSON.stringify({ text: 'see attached', files: ['ok.txt'] }),
+        in_reply_to: null,
+      },
+      S1,
+    );
+
+    const bRows = readInbound(B, SB.id);
+    expect(bRows).toHaveLength(1);
+    const parsed = JSON.parse(bRows[0].content);
+    expect(parsed.attachments).toHaveLength(1);
+    expect(parsed.attachments[0].name).toBe('ok.txt');
+    const targetPath = path.join(sessionDir(B, SB.id), parsed.attachments[0].localPath);
+    expect(fs.existsSync(targetPath)).toBe(true);
+    expect(fs.readFileSync(targetPath, 'utf-8')).toBe('legit-bytes');
+  });
 });

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

@@ -22,6 +22,7 @@ import fs from 'fs';
 import path from 'path';
 
 import { isSafeAttachmentName } from '../../attachment-safety.js';
+import { ensureContainedInboxDir, isPathInside } from '../../inbox-safety.js';
 import { getAgentGroup } from '../../db/agent-groups.js';
 import { getInboundSourceSessionId, getMostRecentPeerSourceSessionId } from '../../db/session-db.js';
 import { getSession } from '../../db/sessions.js';
@@ -29,7 +30,9 @@ import { wakeContainer } from '../../container-runner.js';
 import { log } from '../../log.js';
 import { openInboundDb, resolveSession, sessionDir, writeSessionMessage } from '../../session-manager.js';
 import type { Session } from '../../types.js';
+import { requestApproval } from '../approvals/index.js';
 import { hasDestination } from './db/agent-destinations.js';
+import { getMessagePolicy } from './db/agent-message-policies.js';
 
 export { isSafeAttachmentName };
 
@@ -40,11 +43,6 @@ export interface ForwardedAttachment {
   localPath: string;
 }
 
-function isPathInside(parent: string, child: string): boolean {
-  const relative = path.relative(parent, child);
-  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-}
-
 /**
  * Copy file attachments from the source agent's outbox into the target
  * agent's inbox. Returns attachments using the formatter's existing
@@ -96,8 +94,20 @@ export function forwardAttachedFiles(
     return [];
   }
 
-  const targetInboxDir = path.join(sessionDir(target.agentGroupId, target.sessionId), 'inbox', target.messageId);
-  fs.mkdirSync(targetInboxDir, { recursive: true });
+  // Target-side containment — shared with the channel-inbound path. A
+  // compromised target agent can write inside its own session dir, so it could
+  // pre-place `inbox` (or `inbox/<future-msgId>`) as a symlink pointing
+  // anywhere host-writable; ensureContainedInboxDir refuses the symlink before
+  // any copy lands outside the sandbox (#2828, CWE-59).
+  const inboxRoot = path.join(sessionDir(target.agentGroupId, target.sessionId), 'inbox');
+  const targetInboxDir = ensureContainedInboxDir(inboxRoot, target.messageId, {
+    targetGroup: target.agentGroupId,
+    targetSession: target.sessionId,
+    targetMsgId: target.messageId,
+  });
+  if (!targetInboxDir) {
+    return [];
+  }
 
   const attachments: ForwardedAttachment[] = [];
   for (const filename of source.filenames) {
@@ -135,7 +145,20 @@ export function forwardAttachedFiles(
       continue;
     }
     const dst = path.join(targetInboxDir, filename);
-    fs.copyFileSync(realSrc, dst);
+    try {
+      // COPYFILE_EXCL: fail with EEXIST rather than follow or overwrite a
+      // pre-placed symlink / existing file at dst — the host is the sole
+      // writer of these attachments.
+      fs.copyFileSync(realSrc, dst, fs.constants.COPYFILE_EXCL);
+    } catch (err) {
+      log.warn('agent-route: refusing to write target inbox file', {
+        sourceMsgId: source.messageId,
+        targetMsgId: target.messageId,
+        filename,
+        err,
+      });
+      continue;
+    }
     attachments.push({
       name: filename,
       filename,
@@ -208,21 +231,90 @@ function resolveTargetSession(msg: RoutableAgentMessage, sourceSession: Session,
 }
 
 export async function routeAgentMessage(msg: RoutableAgentMessage, session: Session): Promise<void> {
+  const sourceAgentGroupId = session.agent_group_id;
   const targetAgentGroupId = msg.platform_id;
   if (!targetAgentGroupId) {
     throw new Error(`agent-to-agent message ${msg.id} is missing a target agent group id`);
   }
-  if (
-    targetAgentGroupId !== session.agent_group_id &&
-    !hasDestination(session.agent_group_id, 'agent', targetAgentGroupId)
-  ) {
-    throw new Error(
-      `unauthorized agent-to-agent: ${session.agent_group_id} has no destination for ${targetAgentGroupId}`,
-    );
+  const isSelf = targetAgentGroupId === sourceAgentGroupId;
+  if (!isSelf && !hasDestination(sourceAgentGroupId, 'agent', targetAgentGroupId)) {
+    throw new Error(`unauthorized agent-to-agent: ${sourceAgentGroupId} has no destination for ${targetAgentGroupId}`);
   }
   if (!getAgentGroup(targetAgentGroupId)) {
     throw new Error(`target agent group ${targetAgentGroupId} not found for message ${msg.id}`);
   }
+
+  // Gated edge: hold the message and return (not throw) so the delivery loop
+  // consumes the outbound row; `applyA2aMessageGate` re-routes it on approve.
+  if (!isSelf) {
+    const policy = getMessagePolicy(sourceAgentGroupId, targetAgentGroupId);
+    if (policy) {
+      const { approver } = policy;
+      const sourceName = getAgentGroup(sourceAgentGroupId)?.name ?? sourceAgentGroupId;
+      const targetName = getAgentGroup(targetAgentGroupId)?.name ?? targetAgentGroupId;
+      await requestApproval({
+        session,
+        agentName: sourceName,
+        action: A2A_MESSAGE_GATE_ACTION,
+        approverUserId: approver,
+        title: 'Message approval',
+        question: buildGateQuestion(sourceName, targetName, msg.content),
+        payload: {
+          id: msg.id,
+          platform_id: targetAgentGroupId,
+          content: msg.content,
+          in_reply_to: msg.in_reply_to,
+        },
+      });
+      log.info('Agent message held for approval', {
+        from: sourceAgentGroupId,
+        to: targetAgentGroupId,
+        msgId: msg.id,
+      });
+      return;
+    }
+  }
+
+  await performAgentRoute(msg, session, targetAgentGroupId);
+}
+
+export const A2A_MESSAGE_GATE_ACTION = 'a2a_message_gate';
+
+const GATE_CARD_BODY_MAX = 1500;
+
+function parseMessageContent(contentStr: string): { text: string; files: string[] } {
+  try {
+    const parsed = JSON.parse(contentStr) as { text?: unknown; files?: unknown };
+    return {
+      text: typeof parsed.text === 'string' ? parsed.text : '',
+      files: Array.isArray(parsed.files) ? parsed.files.filter((f): f is string => typeof f === 'string') : [],
+    };
+  } catch {
+    return { text: contentStr, files: [] };
+  }
+}
+
+function buildGateQuestion(sourceName: string, targetName: string, contentStr: string): string {
+  const { text, files } = parseMessageContent(contentStr);
+  const body = text.length > GATE_CARD_BODY_MAX ? `${text.slice(0, GATE_CARD_BODY_MAX)}… (truncated)` : text;
+  const lines = [`Agent "${sourceName}" wants to send a message to "${targetName}":`, '', body];
+  if (files.length > 0) lines.push('', `Attachments: ${files.join(', ')}`);
+  lines.push(
+    '',
+    `Approve, Reject, or "Reject with reason…" to decline and then type a short reason I'll relay to "${sourceName}".`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Cross-session route: pick the target session, forward files, write to its
+ * inbound DB, wake it. Authorization is the caller's responsibility.
+ */
+export async function performAgentRoute(
+  msg: RoutableAgentMessage,
+  session: Session,
+  targetAgentGroupId: string,
+): Promise<void> {
   const targetSession = resolveTargetSession(msg, session, targetAgentGroupId);
   const a2aMsgId = `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 

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

@@ -16,7 +16,6 @@ const mockRequestApproval = vi.fn().mockResolvedValue(undefined);
 const mockGetContainerConfig = vi.fn();
 const mockCreateAgentGroup = vi.fn();
 const mockInitGroupFilesystem = vi.fn();
-const mockUpdateScalars = vi.fn();
 const mockWriteDestinations = vi.fn();
 const mockNotifyWrite = vi.fn();
 
@@ -26,7 +25,6 @@ vi.mock('../approvals/index.js', () => ({
 vi.mock('../../db/container-configs.js', () => ({
   getContainerConfig: (...a: unknown[]) => mockGetContainerConfig(...a),
   ensureContainerConfig: () => {},
-  updateContainerConfigScalars: (...a: unknown[]) => mockUpdateScalars(...a),
 }));
 vi.mock('../../db/agent-groups.js', () => ({
   getAgentGroup: (id: string) => ({ id, name: id.toUpperCase(), folder: id, agent_provider: null, created_at: '' }),
@@ -80,8 +78,10 @@ describe('handleCreateAgent — scope-based authorization', () => {
 
   it('child inherits the creator provider (codex parent → codex child)', async () => {
     // A subagent must run on the same authenticated runtime as its creator —
-    // on a codex-only install a claude default would 401. Red-on-delete:
-    // dropping the inheritance leaves the child provider-less (→ claude).
+    // on a codex-only install a claude default would 401. The provider is
+    // passed to initGroupFilesystem, which stamps the child's config row.
+    // Red-on-delete: dropping the inheritance lets the child fall through to the
+    // instance default instead of codex.
     mockGetContainerConfig.mockReturnValue({ cli_scope: 'global', provider: 'codex' });
 
     await handleCreateAgent({ name: 'Scout', instructions: 'help' }, SESSION);
@@ -90,15 +90,19 @@ describe('handleCreateAgent — scope-based authorization', () => {
       expect.anything(),
       expect.objectContaining({ provider: 'codex' }),
     );
-    expect(mockUpdateScalars).toHaveBeenCalledWith(expect.any(String), { provider: 'codex' });
   });
 
-  it('claude creator leaves the child provider unset (built-in default)', async () => {
-    mockGetContainerConfig.mockReturnValue({ cli_scope: 'global' }); // no provider
+  it('claude creator pins the child to claude, not the instance default', async () => {
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'global' }); // parent has no explicit provider
 
     await handleCreateAgent({ name: 'Scout', instructions: 'help' }, SESSION);
 
-    expect(mockUpdateScalars).not.toHaveBeenCalled();
+    // The child inherits the parent's EFFECTIVE provider (claude), passed
+    // explicitly so it never falls through to a non-claude instance default.
+    expect(mockInitGroupFilesystem).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ provider: 'claude' }),
+    );
   });
 
   it('group scope (default): requires approval, does NOT create directly', async () => {

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

@@ -16,7 +16,7 @@ import path from 'path';
 
 import { GROUPS_DIR } from '../../config.js';
 import { createAgentGroup, getAgentGroup, getAgentGroupByFolder } from '../../db/agent-groups.js';
-import { getContainerConfig, updateContainerConfigScalars } from '../../db/container-configs.js';
+import { getContainerConfig } from '../../db/container-configs.js';
 import { getSession } from '../../db/sessions.js';
 import { wakeContainer } from '../../container-runner.js';
 import { initGroupFilesystem } from '../../group-init.js';
@@ -163,17 +163,15 @@ async function performCreateAgent(
     created_at: now,
   };
   createAgentGroup(newGroup);
-  // A subagent inherits its creator's provider. Provider is a DB property; the
-  // child is created provider-agnostic, then stamped with the parent's runtime
-  // so a single-provider install (e.g. codex-only, where claude isn't
-  // authenticated) doesn't spawn a child on a runtime it can't reach. The
+  // Subagent path: a child inherits its creator's EFFECTIVE provider, NOT the
+  // instance-wide default — so a child is never spawned on a runtime the parent
+  // can't reach (e.g. a codex-only install where claude isn't authenticated).
+  // Passing it explicitly to initGroupFilesystem pins the child's scaffold and
+  // stamps its config row in one step (a NULL parent resolves to claude). The
   // operator can still flip a child later with `ncl groups config update
-  // --provider`. claude (the built-in default) leaves the column unset.
-  const parentProvider = getContainerConfig(sourceGroup.id)?.provider ?? undefined;
+  // --provider`.
+  const parentProvider = getContainerConfig(sourceGroup.id)?.provider ?? 'claude';
   initGroupFilesystem(newGroup, { instructions: instructions ?? undefined, provider: parentProvider });
-  if (parentProvider) {
-    updateContainerConfigScalars(newGroup.id, { provider: parentProvider });
-  }
 
   // Insert bidirectional destination rows (= ACL grants).
   // Creator refers to child by the name it chose; child refers to creator as "parent".

src/modules/agent-to-agent/db/agent-destinations.ts

@@ -36,6 +36,7 @@
  */
 import type { AgentDestination } from '../../../types.js';
 import { getDb } from '../../../db/connection.js';
+import { deletePoliciesTouching, removeMessagePolicy } from './agent-message-policies.js';
 
 /**
  * ⚠️  Caller responsibility: after this returns, call
@@ -89,9 +90,16 @@ export function hasDestination(agentGroupId: string, targetType: 'channel' | 'ag
  * so the deletion propagates to the running container's inbound.db.
  */
 export function deleteDestination(agentGroupId: string, localName: string): void {
+  // Resolve the target first so we can drop a matching policy for this edge (no ghost gate on re-wire).
+  const row = getDb()
+    .prepare('SELECT target_type, target_id FROM agent_destinations WHERE agent_group_id = ? AND local_name = ?')
+    .get(agentGroupId, localName) as { target_type: string; target_id: string } | undefined;
   getDb()
     .prepare('DELETE FROM agent_destinations WHERE agent_group_id = ? AND local_name = ?')
     .run(agentGroupId, localName);
+  if (row?.target_type === 'agent') {
+    removeMessagePolicy(agentGroupId, row.target_id);
+  }
 }
 
 /**
@@ -108,6 +116,7 @@ export function deleteAllDestinationsTouching(agentGroupId: string): void {
   getDb()
     .prepare('DELETE FROM agent_destinations WHERE agent_group_id = ? OR (target_type = ? AND target_id = ?)')
     .run(agentGroupId, 'agent', agentGroupId);
+  deletePoliciesTouching(agentGroupId);
 }
 
 /**

src/modules/agent-to-agent/db/agent-message-policies.ts

@@ -0,0 +1,38 @@
+/** Per-message approval policies for agent-to-agent connections; no row = free flow. */
+import type { AgentMessagePolicy } from '../../../types.js';
+import { getDb } from '../../../db/connection.js';
+
+export function getMessagePolicy(fromAgentGroupId: string, toAgentGroupId: string): AgentMessagePolicy | undefined {
+  return getDb()
+    .prepare('SELECT * FROM agent_message_policies WHERE from_agent_group_id = ? AND to_agent_group_id = ?')
+    .get(fromAgentGroupId, toAgentGroupId) as AgentMessagePolicy | undefined;
+}
+
+export function setMessagePolicy(
+  fromAgentGroupId: string,
+  toAgentGroupId: string,
+  approver: string,
+  createdAt: string,
+): void {
+  getDb()
+    .prepare(
+      `INSERT INTO agent_message_policies (from_agent_group_id, to_agent_group_id, approver, created_at)
+       VALUES (@from_agent_group_id, @to_agent_group_id, @approver, @created_at)
+       ON CONFLICT (from_agent_group_id, to_agent_group_id) DO UPDATE SET approver = excluded.approver`,
+    )
+    .run({ from_agent_group_id: fromAgentGroupId, to_agent_group_id: toAgentGroupId, approver, created_at: createdAt });
+}
+
+export function removeMessagePolicy(fromAgentGroupId: string, toAgentGroupId: string): boolean {
+  const info = getDb()
+    .prepare('DELETE FROM agent_message_policies WHERE from_agent_group_id = ? AND to_agent_group_id = ?')
+    .run(fromAgentGroupId, toAgentGroupId);
+  return info.changes > 0;
+}
+
+/** Delete every policy touching this agent group, so none outlives its connection. */
+export function deletePoliciesTouching(agentGroupId: string): void {
+  getDb()
+    .prepare('DELETE FROM agent_message_policies WHERE from_agent_group_id = ? OR to_agent_group_id = ?')
+    .run(agentGroupId, agentGroupId);
+}

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

@@ -22,7 +22,11 @@
  */
 import { registerDeliveryAction } from '../../delivery.js';
 import { registerApprovalHandler } from '../approvals/index.js';
+import { A2A_MESSAGE_GATE_ACTION } from './agent-route.js';
 import { applyCreateAgent, handleCreateAgent } from './create-agent.js';
+import { applyA2aMessageGate } from './message-gate.js';
 
 registerDeliveryAction('create_agent', handleCreateAgent);
 registerApprovalHandler('create_agent', applyCreateAgent);
+
+registerApprovalHandler(A2A_MESSAGE_GATE_ACTION, applyA2aMessageGate);

src/modules/agent-to-agent/message-gate.test.ts

@@ -0,0 +1,193 @@
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+
+import { routeAgentMessage } from './agent-route.js';
+import { createDestination, deleteDestination, deleteAllDestinationsTouching } from './db/agent-destinations.js';
+import { getMessagePolicy, removeMessagePolicy, setMessagePolicy } from './db/agent-message-policies.js';
+import { applyA2aMessageGate } from './message-gate.js';
+import { initTestDb, closeDb, runMigrations, createAgentGroup } from '../../db/index.js';
+import { getDb } from '../../db/connection.js';
+import { createSession } from '../../db/sessions.js';
+import { requestApproval } from '../approvals/index.js';
+import { initSessionFolder, inboundDbPath } from '../../session-manager.js';
+import type { Session } from '../../types.js';
+
+vi.mock('../../container-runner.js', () => ({
+  wakeContainer: vi.fn().mockResolvedValue(undefined),
+  isContainerRunning: vi.fn().mockReturnValue(false),
+  getActiveContainerCount: vi.fn().mockReturnValue(0),
+  killContainer: vi.fn(),
+}));
+
+vi.mock('../approvals/index.js', async (importActual) => {
+  const actual = await importActual<typeof import('../approvals/index.js')>();
+  return { ...actual, requestApproval: vi.fn().mockResolvedValue(undefined) };
+});
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/nanoclaw-test-a2a-gate' };
+});
+
+const TEST_DIR = '/tmp/nanoclaw-test-a2a-gate';
+const A = 'ag-A';
+const B = 'ag-B';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function policyCount(): number {
+  return (getDb().prepare('SELECT COUNT(*) AS n FROM agent_message_policies').get() as { n: number }).n;
+}
+
+function readInbound(agentGroupId: string, sessionId: string) {
+  const db = new Database(inboundDbPath(agentGroupId, sessionId), { readonly: true });
+  const rows = db.prepare('SELECT id, platform_id, content FROM messages_in ORDER BY seq').all() as Array<{
+    id: string;
+    platform_id: string | null;
+    content: string;
+  }>;
+  db.close();
+  return rows;
+}
+
+function makeSession(id: string, agentGroupId: string): Session {
+  return {
+    id,
+    agent_group_id: agentGroupId,
+    messaging_group_id: null,
+    thread_id: null,
+    agent_provider: null,
+    status: 'active',
+    container_status: 'stopped',
+    last_active: null,
+    created_at: now(),
+  };
+}
+
+describe('agent message policies', () => {
+  let SA: Session;
+  let SB: Session;
+
+  beforeEach(() => {
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+    const db = initTestDb();
+    runMigrations(db);
+    vi.mocked(requestApproval).mockClear();
+
+    createAgentGroup({ id: A, name: 'A', folder: 'a', agent_provider: null, created_at: now() });
+    createAgentGroup({ id: B, name: 'B', folder: 'b', agent_provider: null, created_at: now() });
+    SA = makeSession('sess-A', A);
+    SB = makeSession('sess-B', B);
+    createSession(SA);
+    createSession(SB);
+    initSessionFolder(A, SA.id);
+    initSessionFolder(B, SB.id);
+    // A→B connection wired.
+    createDestination({ agent_group_id: A, local_name: 'b', target_type: 'agent', target_id: B, created_at: now() });
+  });
+
+  afterEach(() => {
+    closeDb();
+    if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  });
+
+  // ── policy table round-trip ──
+
+  it('set / get / remove round-trip, incl. approver', () => {
+    expect(getMessagePolicy(A, B)).toBeUndefined();
+
+    setMessagePolicy(A, B, 'telegram:sam', now());
+    expect(getMessagePolicy(A, B)).toMatchObject({
+      from_agent_group_id: A,
+      to_agent_group_id: B,
+      approver: 'telegram:sam',
+    });
+    expect(policyCount()).toBe(1);
+
+    // Upsert updates the approver without inserting a duplicate row.
+    setMessagePolicy(A, B, 'telegram:dana', now());
+    expect(getMessagePolicy(A, B)!.approver).toBe('telegram:dana');
+    expect(policyCount()).toBe(1);
+
+    expect(removeMessagePolicy(A, B)).toBe(true);
+    expect(getMessagePolicy(A, B)).toBeUndefined();
+    expect(removeMessagePolicy(A, B)).toBe(false);
+  });
+
+  // ── gate behavior in routeAgentMessage ──
+
+  it('no policy → routes normally, no approval requested', async () => {
+    await routeAgentMessage(
+      { id: 'm1', platform_id: B, content: JSON.stringify({ text: 'hi B' }), in_reply_to: null },
+      SA,
+    );
+    expect(readInbound(B, SB.id)).toHaveLength(1);
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('policy present → holds the message and requests approval from the policy approver scoped to the target', async () => {
+    setMessagePolicy(A, B, 'telegram:dana', now());
+
+    await routeAgentMessage(
+      { id: 'm2', platform_id: B, content: JSON.stringify({ text: 'sensitive' }), in_reply_to: null },
+      SA,
+    );
+
+    // Held: nothing routed to B.
+    expect(readInbound(B, SB.id)).toHaveLength(0);
+    // One approval requested, to the policy's approver, scoped to the target group.
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    const opts = vi.mocked(requestApproval).mock.calls[0][0];
+    expect(opts.action).toBe('a2a_message_gate');
+    expect(opts.approverUserId).toBe('telegram:dana');
+    expect(opts.payload).toMatchObject({ id: 'm2', platform_id: B });
+    expect(JSON.parse(String(opts.payload.content)).text).toBe('sensitive');
+  });
+
+  it('self-message is never gated even if a policy row somehow exists', async () => {
+    setMessagePolicy(A, A, 'telegram:dana', now()); // pathological, but must be ignored
+    await routeAgentMessage(
+      { id: 'self', platform_id: A, content: JSON.stringify({ text: 'note' }), in_reply_to: null },
+      SA,
+    );
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(readInbound(A, SA.id)).toHaveLength(1);
+  });
+
+  // ── approve handler re-routes the held message ──
+
+  it('applyA2aMessageGate delivers the held message to the target', async () => {
+    const notify = vi.fn();
+    await applyA2aMessageGate({
+      session: SA,
+      userId: 'slack:dana',
+      notify,
+      payload: { id: 'held-1', platform_id: B, content: JSON.stringify({ text: 'approved!' }), in_reply_to: null },
+    });
+
+    const bRows = readInbound(B, SB.id);
+    expect(bRows).toHaveLength(1);
+    expect(JSON.parse(bRows[0].content).text).toBe('approved!');
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  // ── ghost-gate cleanup ──
+
+  it('deleting the connection drops its policy', () => {
+    setMessagePolicy(A, B, 'telegram:dana', now());
+    deleteDestination(A, 'b'); // removes the A→B agent destination
+    expect(getMessagePolicy(A, B)).toBeUndefined();
+  });
+
+  it('deleteAllDestinationsTouching drops policies on both sides', () => {
+    setMessagePolicy(A, B, 'telegram:dana', now());
+    setMessagePolicy(B, A, 'telegram:dana', now());
+    deleteAllDestinationsTouching(A);
+    expect(getMessagePolicy(A, B)).toBeUndefined();
+    expect(getMessagePolicy(B, A)).toBeUndefined();
+  });
+});

src/modules/agent-to-agent/message-gate.ts

@@ -0,0 +1,27 @@
+/** Approve handler for a held a2a message. (Reject is handled by the generic response-handler path.) */
+import { log } from '../../log.js';
+import type { ApprovalHandler } from '../approvals/index.js';
+import { performAgentRoute, type RoutableAgentMessage } from './agent-route.js';
+
+export const applyA2aMessageGate: ApprovalHandler = async ({ session, payload, notify }) => {
+  const { id, platform_id, content, in_reply_to } = payload;
+  if (typeof platform_id !== 'string' || !platform_id) {
+    notify('Message approved but the target agent group was missing from the request.');
+    log.warn('a2a_message_gate apply: missing target', { sessionId: session.id });
+    return;
+  }
+
+  const msg: RoutableAgentMessage = {
+    id: typeof id === 'string' ? id : `a2a-gate-${Date.now()}`,
+    platform_id,
+    content: typeof content === 'string' ? content : '',
+    in_reply_to: typeof in_reply_to === 'string' ? in_reply_to : null,
+  };
+
+  await performAgentRoute(msg, session, platform_id);
+  log.info('Held agent message delivered after approval', {
+    from: session.agent_group_id,
+    to: platform_id,
+    msgId: msg.id,
+  });
+};

src/modules/approvals/finalize.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared "finalize a rejected approval" path.
+ *
+ * Three entry points land here so they relay one message and clean up
+ * identically:
+ *   1. The instant Reject button            (response-handler.ts)
+ *   2. A captured Reject-with-reason reply   (reason-capture.ts)
+ *   3. The host-sweep ghost finalizer        (reason-capture.ts, via host-sweep)
+ *
+ * Kept in its own leaf file so both response-handler.ts and reason-capture.ts
+ * can import it without an import cycle (finalize → primitive only).
+ */
+import { wakeContainer } from '../../container-runner.js';
+import { deletePendingApproval } from '../../db/sessions.js';
+import { log } from '../../log.js';
+import { writeSessionMessage } from '../../session-manager.js';
+import type { PendingApproval, Session } from '../../types.js';
+import { notifyApprovalResolved } from './primitive.js';
+
+/**
+ * Notify the requesting agent that its action was rejected, drop the pending
+ * row, fire approval-resolved callbacks, and wake the container.
+ *
+ * When `reason` is provided it's appended to the agent-facing note with generic
+ * attribution — the why, not the who (the rejecting admin may belong to a
+ * different owner than the requesting agent). Callers are responsible for
+ * clamping the reason length before passing it in.
+ */
+export async function finalizeReject(
+  approval: PendingApproval,
+  session: Session,
+  userId: string,
+  reason?: string,
+): Promise<void> {
+  const text = reason
+    ? `Your ${approval.action} request was rejected by admin: "${reason}"`
+    : `Your ${approval.action} request was rejected by admin.`;
+
+  writeSessionMessage(session.agent_group_id, session.id, {
+    id: `appr-note-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    kind: 'chat',
+    timestamp: new Date().toISOString(),
+    platformId: session.agent_group_id,
+    channelType: 'agent',
+    threadId: null,
+    content: JSON.stringify({ text, sender: 'system', senderId: 'system' }),
+  });
+
+  log.info('Approval rejected', {
+    approvalId: approval.approval_id,
+    action: approval.action,
+    userId,
+    withReason: reason !== undefined,
+  });
+
+  deletePendingApproval(approval.approval_id);
+  await notifyApprovalResolved({ approval, session, outcome: 'reject', userId });
+  await wakeContainer(session);
+}

src/modules/approvals/index.ts

@@ -8,10 +8,16 @@
  *   - A response handler that claims pending_approvals rows and dispatches
  *     to whatever module registered for the row's `action` string. Also
  *     resolves in-memory OneCLI credential approvals.
+ *   - A message-interceptor (via ./reason-capture.js) that captures an admin's
+ *     one-line reply after they click "Reject with reason…".
  *   - An adapter-ready callback that starts the OneCLI manual-approval handler
  *     once the delivery adapter is set.
  *   - A shutdown callback that stops the OneCLI handler cleanly.
  *
+ * Exposes `sweepAwaitingReasonRejects` for the host sweep to finalize ghosted
+ * reject-with-reason holds (re-exported here, which also loads reason-capture
+ * so its interceptor registers).
+ *
  * Self-mod flows (install_packages, add_mcp_server) moved out to
  * `src/modules/self-mod/` in PR #7 — they now register delivery actions
  * + approval handlers via this module's public API.
@@ -24,6 +30,9 @@ import { startOneCLIApprovalHandler, stopOneCLIApprovalHandler } from './onecli-
 // Public API re-exports so consumers import from the module root.
 export { requestApproval, registerApprovalHandler, notifyAgent } from './primitive.js';
 export type { ApprovalHandler, ApprovalHandlerContext, RequestApprovalOptions } from './primitive.js';
+// Host-sweep hook for ghosted "Reject with reason…" holds. The re-export also
+// loads reason-capture.js, registering its message-interceptor on import.
+export { sweepAwaitingReasonRejects } from './reason-capture.js';
 
 registerResponseHandler(handleApprovalsResponse);
 

src/modules/approvals/primitive.ts

@@ -32,10 +32,23 @@ import type { MessagingGroup, PendingApproval, Session } from '../../types.js';
 import { getAdminsOfAgentGroup, getGlobalAdmins, getOwners } from '../permissions/db/user-roles.js';
 import { ensureUserDm } from '../permissions/user-dm.js';
 
-/** Two-button approval UI — the only options the primitive supports today. */
+/**
+ * Card value for the "Reject with reason…" button. Selecting it doesn't
+ * finalize the reject — it holds the row and captures the approver's next DM
+ * as a one-line reason relayed to the requesting agent. See reason-capture.ts.
+ */
+export const REJECT_WITH_REASON_VALUE = 'reject_with_reason';
+
+/**
+ * Three-button approval UI. Plain Reject is the instant fast path; "Reject with
+ * reason…" opts into the reason-capture flow. Shared by every module approval
+ * (create_agent, install_packages, add_mcp_server); OneCLI credential cards
+ * keep their own two-button set in onecli-approvals.ts.
+ */
 const APPROVAL_OPTIONS: RawOption[] = [
   { label: 'Approve', selectedLabel: '✅ Approved', value: 'approve' },
   { label: 'Reject', selectedLabel: '❌ Rejected', value: 'reject' },
+  { label: 'Reject with reason…', selectedLabel: '📝 Rejected (awaiting reason)', value: REJECT_WITH_REASON_VALUE },
 ];
 
 // ── Approval handler registry ──
@@ -197,6 +210,8 @@ export interface RequestApprovalOptions {
   title: string;
   /** Card body shown to the admin. */
   question: string;
+  /** Deliver the card to this specific user instead of all of the session group's admins. */
+  approverUserId?: string;
 }
 
 /**
@@ -206,9 +221,9 @@ export interface RequestApprovalOptions {
  * approval handler for this action via the response dispatcher.
  */
 export async function requestApproval(opts: RequestApprovalOptions): Promise<void> {
-  const { session, action, payload, title, question, agentName } = opts;
+  const { session, action, payload, title, question, agentName, approverUserId } = opts;
 
-  const approvers = pickApprover(session.agent_group_id);
+  const approvers = approverUserId ? [approverUserId] : pickApprover(session.agent_group_id);
   if (approvers.length === 0) {
     notifyAgent(session, `${action} failed: no owner or admin configured to approve.`);
     return;
@@ -235,6 +250,7 @@ export async function requestApproval(opts: RequestApprovalOptions): Promise<voi
     created_at: new Date().toISOString(),
     title,
     options_json: JSON.stringify(normalizedOptions),
+    approver_user_id: approverUserId ?? null,
   });
 
   const adapter = getDeliveryAdapter();

src/modules/approvals/reason-capture.test.ts

@@ -0,0 +1,279 @@
+/**
+ * "Reject with reason…" capture flow.
+ *
+ * Covers the three entry points end to end against the real central DB:
+ *   - arming (handleApprovalsResponse with the third option) holds the row and
+ *     prompts the admin instead of finalizing;
+ *   - the captured reply relays one combined message, clamped to 280 chars;
+ *   - the host sweep finalizes a ghosted hold as a plain reject.
+ *
+ * writeSessionMessage is mocked so the relayed agent-facing text can be read
+ * back directly; the delivery adapter is a fake that records prompt sends.
+ */
+import * as fs from 'fs';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { InboundEvent } from '../../channels/adapter.js';
+import { initTestDb, closeDb, runMigrations } from '../../db/index.js';
+import { createAgentGroup } from '../../db/agent-groups.js';
+import { createMessagingGroup } from '../../db/messaging-groups.js';
+import {
+  createSession,
+  createPendingApproval,
+  deletePendingApproval,
+  getPendingApproval,
+  markApprovalAwaitingReason,
+} from '../../db/sessions.js';
+import { setDeliveryAdapter, type ChannelDeliveryAdapter } from '../../delivery.js';
+import { writeSessionMessage } from '../../session-manager.js';
+import { upsertUser } from '../permissions/db/users.js';
+import { upsertUserDm } from '../permissions/db/user-dms.js';
+import { grantRole } from '../permissions/db/user-roles.js';
+import { REJECT_WITH_REASON_VALUE } from './primitive.js';
+
+vi.mock('../../container-runner.js', () => ({
+  wakeContainer: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/nanoclaw-test-reject-reason' };
+});
+
+vi.mock('../../session-manager.js', async () => {
+  const actual = await vi.importActual<typeof import('../../session-manager.js')>('../../session-manager.js');
+  return { ...actual, writeSessionMessage: vi.fn() };
+});
+
+const TEST_DIR = '/tmp/nanoclaw-test-reject-reason';
+const DM_CHANNEL = 'slack';
+const DM_PLATFORM = 'D-admin-1';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+let delivered: Array<{ channelType: string; platformId: string; content: string }>;
+
+const fakeAdapter: ChannelDeliveryAdapter = {
+  async deliver(channelType, platformId, _threadId, _kind, content) {
+    delivered.push({ channelType, platformId, content });
+    return 'pm-1';
+  },
+};
+
+function seedApproval(approvalId: string, action = 'create_agent'): void {
+  createPendingApproval({
+    approval_id: approvalId,
+    session_id: 'sess-1',
+    request_id: approvalId,
+    action,
+    payload: JSON.stringify({ name: 'child' }),
+    created_at: now(),
+    title: 'Approval',
+    options_json: JSON.stringify([]),
+  });
+}
+
+function dmReply(text?: string): InboundEvent {
+  const content: Record<string, unknown> = { sender: 'admin-1', senderId: 'admin-1' };
+  if (text !== undefined) content.text = text;
+  return {
+    channelType: DM_CHANNEL,
+    platformId: DM_PLATFORM,
+    threadId: null,
+    message: { id: 'm-1', kind: 'chat', content: JSON.stringify(content), timestamp: now() },
+  };
+}
+
+/** Click the "Reject with reason…" button as the seeded admin. */
+async function clickRejectWithReason(approvalId: string): Promise<void> {
+  const { handleApprovalsResponse } = await import('./response-handler.js');
+  await handleApprovalsResponse({
+    questionId: approvalId,
+    value: REJECT_WITH_REASON_VALUE,
+    userId: 'admin-1',
+    channelType: DM_CHANNEL,
+    platformId: '', // not surfaced by the click payload — resolved via ensureUserDm
+    threadId: null,
+  });
+}
+
+/** The text of the most recent agent-facing note written via writeSessionMessage. */
+function lastRelayedText(): string | undefined {
+  const call = vi.mocked(writeSessionMessage).mock.calls.at(-1);
+  if (!call) return undefined;
+  return (JSON.parse(call[2].content) as { text: string }).text;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+  const db = initTestDb();
+  runMigrations(db);
+  delivered = [];
+
+  createAgentGroup({ id: 'ag-1', name: 'Agent', folder: 'agent', agent_provider: null, created_at: now() });
+  createSession({
+    id: 'sess-1',
+    agent_group_id: 'ag-1',
+    messaging_group_id: null,
+    thread_id: null,
+    agent_provider: null,
+    status: 'active',
+    container_status: 'stopped',
+    last_active: now(),
+    created_at: now(),
+  });
+
+  // Authorized approver + a cached DM so ensureUserDm resolves without a
+  // platform openDM call.
+  upsertUser({ id: 'slack:admin-1', kind: 'slack', display_name: 'Admin', created_at: now() });
+  grantRole({ user_id: 'slack:admin-1', role: 'owner', agent_group_id: null, granted_by: null, granted_at: now() });
+  createMessagingGroup({
+    id: 'mg-dm-1',
+    channel_type: DM_CHANNEL,
+    platform_id: DM_PLATFORM,
+    name: 'Admin DM',
+    is_group: 0,
+    unknown_sender_policy: 'strict',
+    created_at: now(),
+  });
+  upsertUserDm({
+    user_id: 'slack:admin-1',
+    channel_type: DM_CHANNEL,
+    messaging_group_id: 'mg-dm-1',
+    resolved_at: now(),
+  });
+
+  setDeliveryAdapter(fakeAdapter);
+});
+
+afterEach(() => {
+  closeDb();
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe('reject with reason', () => {
+  it('holds the row and prompts the admin instead of finalizing', async () => {
+    seedApproval('appr-1');
+    await clickRejectWithReason('appr-1');
+
+    const row = getPendingApproval('appr-1');
+    expect(row?.status).toBe('awaiting_reason');
+    expect(row?.expires_at).toBeTruthy();
+
+    // Prompt went to the admin's resolved DM, not the (empty) click platformId.
+    expect(delivered).toHaveLength(1);
+    expect(delivered[0].channelType).toBe(DM_CHANNEL);
+    expect(delivered[0].platformId).toBe(DM_PLATFORM);
+    expect((JSON.parse(delivered[0].content) as { text: string }).text).toMatch(/reason/i);
+
+    // Agent is not notified yet — the hold is still open.
+    expect(vi.mocked(writeSessionMessage)).not.toHaveBeenCalled();
+  });
+
+  it('relays the captured reason as one combined message and clears the row', async () => {
+    const { captureReasonReply } = await import('./reason-capture.js');
+    seedApproval('appr-2', 'install_packages');
+    await clickRejectWithReason('appr-2');
+
+    const consumed = await captureReasonReply(dmReply('too risky for prod'));
+
+    expect(consumed).toBe(true);
+    expect(getPendingApproval('appr-2')).toBeUndefined();
+    expect(lastRelayedText()).toBe('Your install_packages request was rejected by admin: "too risky for prod"');
+  });
+
+  it('truncates an over-long reason to 280 chars with an ellipsis', async () => {
+    const { captureReasonReply } = await import('./reason-capture.js');
+    seedApproval('appr-3');
+    await clickRejectWithReason('appr-3');
+
+    await captureReasonReply(dmReply('x'.repeat(400)));
+
+    const reason = lastRelayedText()!.match(/: "(.*)"$/)![1];
+    expect(reason).toHaveLength(280);
+    expect(reason.endsWith('…')).toBe(true);
+  });
+
+  it('finalizes a plain reject when the captured reply carries no text', async () => {
+    const { captureReasonReply } = await import('./reason-capture.js');
+    seedApproval('appr-4');
+    await clickRejectWithReason('appr-4');
+
+    const consumed = await captureReasonReply(dmReply(undefined));
+
+    expect(consumed).toBe(true);
+    expect(getPendingApproval('appr-4')).toBeUndefined();
+    expect(lastRelayedText()).toBe('Your create_agent request was rejected by admin.');
+  });
+
+  it('does not swallow a later DM once the hold was already finalized', async () => {
+    const { captureReasonReply } = await import('./reason-capture.js');
+    seedApproval('appr-5');
+    await clickRejectWithReason('appr-5');
+    // Simulate the sweep (or any other path) finalizing first.
+    deletePendingApproval('appr-5');
+
+    const consumed = await captureReasonReply(dmReply('late reason'));
+
+    expect(consumed).toBe(false);
+  });
+
+  it('ignores DMs on channels with no armed reason capture', async () => {
+    const { captureReasonReply } = await import('./reason-capture.js');
+    const consumed = await captureReasonReply({
+      channelType: DM_CHANNEL,
+      platformId: 'D-someone-else',
+      threadId: null,
+      message: { id: 'm', kind: 'chat', content: JSON.stringify({ text: 'hi' }), timestamp: now() },
+    });
+    expect(consumed).toBe(false);
+  });
+});
+
+describe('reject-with-reason host sweep', () => {
+  it('finalizes a hold whose window elapsed as a plain reject', async () => {
+    const { sweepAwaitingReasonRejects } = await import('./reason-capture.js');
+    seedApproval('appr-ghost', 'add_mcp_server');
+    markApprovalAwaitingReason('appr-ghost', new Date(Date.now() - 1000).toISOString());
+
+    await sweepAwaitingReasonRejects();
+
+    expect(getPendingApproval('appr-ghost')).toBeUndefined();
+    expect(lastRelayedText()).toBe('Your add_mcp_server request was rejected by admin.');
+  });
+
+  it('leaves a still-open hold untouched', async () => {
+    const { sweepAwaitingReasonRejects } = await import('./reason-capture.js');
+    seedApproval('appr-open');
+    markApprovalAwaitingReason('appr-open', new Date(Date.now() + 60_000).toISOString());
+
+    await sweepAwaitingReasonRejects();
+
+    expect(getPendingApproval('appr-open')?.status).toBe('awaiting_reason');
+    expect(vi.mocked(writeSessionMessage)).not.toHaveBeenCalled();
+  });
+});
+
+describe('plain reject (regression)', () => {
+  it('finalizes immediately with no reason and no DM prompt', async () => {
+    const { handleApprovalsResponse } = await import('./response-handler.js');
+    seedApproval('appr-plain', 'install_packages');
+
+    await handleApprovalsResponse({
+      questionId: 'appr-plain',
+      value: 'reject',
+      userId: 'admin-1',
+      channelType: DM_CHANNEL,
+      platformId: '',
+      threadId: null,
+    });
+
+    expect(getPendingApproval('appr-plain')).toBeUndefined();
+    expect(delivered).toHaveLength(0);
+    expect(lastRelayedText()).toBe('Your install_packages request was rejected by admin.');
+  });
+});

src/modules/approvals/reason-capture.ts

@@ -0,0 +1,174 @@
+/**
+ * "Reject with reason…" capture flow.
+ *
+ * When an admin clicks the third approval button, the reject is held instead of
+ * finalized: the row is parked at status='awaiting_reason' and the admin is
+ * prompted in their DM for a one-line reason. Their next DM (≤ 280 chars) is
+ * captured by a router message-interceptor and relayed to the requesting agent
+ * as one combined message — `Your <action> request was rejected by admin:
+ * "<reason>"`. A plain Reject never arms this, so an unrelated DM is never
+ * swallowed.
+ *
+ * Restart-safety: arming lives in an in-memory map (lost on restart, like the
+ * agent-naming capture it mirrors), but the hold is a durable DB row. If the
+ * admin never replies — or the host restarts mid-capture — the host sweep
+ * (sweepAwaitingReasonRejects, run each tick) finalizes a plain reject once the
+ * row's window elapses, so the requesting agent is never stranded.
+ *
+ * Reuses, not reinvents: the agent-naming prompt-then-capture pattern
+ * (in-memory map + next-DM interceptor) and the shared finalizeReject path.
+ */
+import type { InboundEvent } from '../../channels/adapter.js';
+import { getDeliveryAdapter } from '../../delivery.js';
+import {
+  deletePendingApproval,
+  getExpiredAwaitingReasonApprovals,
+  getPendingApproval,
+  getSession,
+  markApprovalAwaitingReason,
+} from '../../db/sessions.js';
+import { log } from '../../log.js';
+import { registerMessageInterceptor } from '../../router.js';
+import type { PendingApproval, Session } from '../../types.js';
+import { ensureUserDm } from '../permissions/user-dm.js';
+import { finalizeReject } from './finalize.js';
+
+/** How long an awaiting-reason hold waits for the admin's reply before the sweep finalizes a plain reject. */
+const REASON_CAPTURE_WINDOW_MS = 5 * 60 * 1000;
+/** Cap on the relayed reason — one cheap guardrail against a wall of text landing in another team's agent context. */
+const MAX_REASON_LEN = 280;
+
+const PROMPT_TEXT =
+  "Reply with a one-line reason for the rejection — I'll relay it to the agent. " +
+  'No reply within ~5 min declines it without a reason.';
+
+interface ReasonArming {
+  approvalId: string;
+  /** Namespaced id of the admin who clicked, for resolution attribution. */
+  userId: string;
+}
+
+/**
+ * Approvers waiting to type a rejection reason, keyed by their DM channel
+ * (`<channelType>:<dmPlatformId>`). A DM's platform id is unique per user, so
+ * the inbound reply matches by channel alone — no sender re-parsing needed, and
+ * a group message can never collide with an armed DM. Cleared on receipt,
+ * staleness, or restart.
+ */
+const awaitingReason = new Map<string, ReasonArming>();
+
+function dmKey(channelType: string, platformId: string): string {
+  return `${channelType}:${platformId}`;
+}
+
+function clampReason(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length <= MAX_REASON_LEN) return trimmed;
+  return trimmed.slice(0, MAX_REASON_LEN - 1) + '…';
+}
+
+function extractText(event: InboundEvent): string {
+  try {
+    const parsed = JSON.parse(event.message.content) as Record<string, unknown>;
+    return typeof parsed.text === 'string' ? parsed.text : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Begin the reject-with-reason hold for an approval the admin chose not to
+ * finalize outright. Prompts the admin's DM, then parks the row and arms
+ * capture. If we can't reach the admin (no DM, no adapter, delivery throws) we
+ * finalize a plain reject immediately rather than strand the requesting agent.
+ */
+export async function armReasonCapture(approval: PendingApproval, session: Session, userId: string): Promise<void> {
+  const dm = userId ? await ensureUserDm(userId) : null;
+  const adapter = getDeliveryAdapter();
+  if (!dm || !adapter) {
+    log.warn('reject-with-reason: cannot reach approver, finalizing plain reject', {
+      approvalId: approval.approval_id,
+      userId,
+      hasDm: Boolean(dm),
+      hasAdapter: Boolean(adapter),
+    });
+    await finalizeReject(approval, session, userId);
+    return;
+  }
+
+  try {
+    await adapter.deliver(dm.channel_type, dm.platform_id, null, 'chat-sdk', JSON.stringify({ text: PROMPT_TEXT }));
+  } catch (err) {
+    log.error('reject-with-reason: reason prompt delivery failed, finalizing plain reject', {
+      approvalId: approval.approval_id,
+      err,
+    });
+    await finalizeReject(approval, session, userId);
+    return;
+  }
+
+  // Prompt is out — now hold the row and arm capture. Order matters: a reply
+  // can't arrive before the prompt is read, so there's no lost-message window.
+  const expiresAt = new Date(Date.now() + REASON_CAPTURE_WINDOW_MS).toISOString();
+  markApprovalAwaitingReason(approval.approval_id, expiresAt);
+  awaitingReason.set(dmKey(dm.channel_type, dm.platform_id), { approvalId: approval.approval_id, userId });
+  log.info('reject-with-reason: awaiting reason reply', { approvalId: approval.approval_id, userId });
+}
+
+/**
+ * Router message-interceptor: capture the next DM from an admin who armed a
+ * reason. Returns true (consume the message) when this DM is an armed reason
+ * channel and still holds a live row; false otherwise so normal routing runs.
+ *
+ * Exported for tests; registered as the interceptor below.
+ */
+export async function captureReasonReply(event: InboundEvent): Promise<boolean> {
+  const arming = awaitingReason.get(dmKey(event.channelType, event.platformId));
+  if (!arming) return false;
+
+  // This DM is an armed reason channel — disarm regardless of outcome.
+  awaitingReason.delete(dmKey(event.channelType, event.platformId));
+
+  const approval = getPendingApproval(arming.approvalId);
+  if (!approval || approval.status !== 'awaiting_reason') {
+    // Already finalized (e.g. ghosted by the sweep). The reply is no longer a
+    // reason — let it route normally instead of swallowing it.
+    return false;
+  }
+
+  const session = approval.session_id ? getSession(approval.session_id) : null;
+  if (!session) {
+    deletePendingApproval(approval.approval_id);
+    return true;
+  }
+
+  const reason = clampReason(extractText(event));
+  await finalizeReject(approval, session, arming.userId, reason || undefined);
+  log.info('reject-with-reason: reason captured and relayed', {
+    approvalId: approval.approval_id,
+    hasReason: reason.length > 0,
+  });
+  return true;
+}
+
+registerMessageInterceptor(captureReasonReply);
+
+/**
+ * Host-sweep finalizer: any reject-with-reason hold whose window elapsed (admin
+ * ghosted, or the host restarted mid-capture and lost the in-memory arming) is
+ * finalized as a plain reject. Restart-safe — the hold is a durable row, so the
+ * requesting agent always gets its decision. Called once per sweep tick.
+ */
+export async function sweepAwaitingReasonRejects(): Promise<void> {
+  const rows = getExpiredAwaitingReasonApprovals(new Date().toISOString());
+  for (const approval of rows) {
+    const session = approval.session_id ? getSession(approval.session_id) : null;
+    if (!session) {
+      deletePendingApproval(approval.approval_id);
+      continue;
+    }
+    // Plain reject, unknown resolver — the admin opted in but never typed.
+    await finalizeReject(approval, session, '');
+    log.info('reject-with-reason: window elapsed, finalized as plain reject', { approvalId: approval.approval_id });
+  }
+}

src/modules/approvals/response-handler.test.ts

@@ -161,4 +161,47 @@ describe('approval response authorization', () => {
     expect(handler).toHaveBeenCalledTimes(1);
     expect(getPendingApproval('appr-3')).toBeUndefined();
   });
+
+  it('an approval with approver_user_id is resolvable by that user, not a non-assignee', async () => {
+    const { registerApprovalHandler } = await import('./primitive.js');
+    const { handleApprovalsResponse } = await import('./response-handler.js');
+    const handler = vi.fn().mockResolvedValue(undefined);
+    registerApprovalHandler('assigned_approver_action', handler);
+
+    createPendingApproval({
+      approval_id: 'appr-4',
+      session_id: 'sess-1',
+      request_id: 'appr-4',
+      action: 'assigned_approver_action',
+      payload: JSON.stringify({}),
+      created_at: now(),
+      title: 'Assigned approval',
+      options_json: JSON.stringify([]),
+      approver_user_id: 'telegram:dana',
+    });
+
+    // A non-assignee (no global/owner role) cannot resolve it.
+    await handleApprovalsResponse({
+      questionId: 'appr-4',
+      value: 'approve',
+      userId: 'stranger',
+      channelType: 'telegram',
+      platformId: 'dm-stranger',
+      threadId: null,
+    });
+    expect(handler).not.toHaveBeenCalled();
+    expect(getPendingApproval('appr-4')).toBeDefined();
+
+    // The named approver resolves it.
+    await handleApprovalsResponse({
+      questionId: 'appr-4',
+      value: 'approve',
+      userId: 'dana',
+      channelType: 'telegram',
+      platformId: 'dm-dana',
+      threadId: null,
+    });
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(getPendingApproval('appr-4')).toBeUndefined();
+  });
 });

src/modules/approvals/response-handler.ts

@@ -5,7 +5,10 @@
  *   1. Module-initiated actions — the module called `requestApproval()` with
  *      some free-form `action` string and registered a handler via
  *      `registerApprovalHandler(action, handler)`. On approve, we look up the
- *      handler and call it; on reject, we notify the agent and move on.
+ *      handler and call it; on plain reject we relay a decline to the agent; on
+ *      "Reject with reason…" we hold the row and capture the admin's next DM as
+ *      a one-line reason (see reason-capture.ts). Reject finalization is shared
+ *      via finalizeReject.
  *   2. OneCLI credential approvals (`action = 'onecli_credential'`). Resolved
  *      via an in-memory Promise — see onecli-approvals.ts.
  *
@@ -19,8 +22,10 @@ import { log } from '../../log.js';
 import { writeSessionMessage } from '../../session-manager.js';
 import type { PendingApproval } from '../../types.js';
 import { hasAdminPrivilege, isGlobalAdmin, isOwner } from '../permissions/db/user-roles.js';
+import { finalizeReject } from './finalize.js';
 import { ONECLI_ACTION, resolveOneCLIApproval } from './onecli-approvals.js';
-import { getApprovalHandler, notifyApprovalResolved } from './primitive.js';
+import { getApprovalHandler, notifyApprovalResolved, REJECT_WITH_REASON_VALUE } from './primitive.js';
+import { armReasonCapture } from './reason-capture.js';
 
 export async function handleApprovalsResponse(payload: ResponsePayload): Promise<boolean> {
   const approval = getPendingApproval(payload.questionId);
@@ -65,6 +70,21 @@ async function handleRegisteredApproval(
     return;
   }
 
+  // "Reject with reason…" — hold the row and capture the admin's next DM
+  // instead of finalizing now. The agent is notified exactly once: after the
+  // reason arrives, or after the sweep's timeout if the admin ghosts.
+  if (selectedOption === REJECT_WITH_REASON_VALUE) {
+    await armReasonCapture(approval, session, userId);
+    return;
+  }
+
+  // Plain Reject (or any other non-approve value) — instant fast path.
+  if (selectedOption !== 'approve') {
+    await finalizeReject(approval, session, userId);
+    return;
+  }
+
+  // Approved — dispatch to the module that registered for this action.
   const notify = (text: string): void => {
     writeSessionMessage(session.agent_group_id, session.id, {
       id: `appr-note-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
@@ -77,16 +97,6 @@ async function handleRegisteredApproval(
     });
   };
 
-  if (selectedOption !== 'approve') {
-    notify(`Your ${approval.action} request was rejected by admin.`);
-    log.info('Approval rejected', { approvalId: approval.approval_id, action: approval.action, userId });
-    deletePendingApproval(approval.approval_id);
-    await notifyApprovalResolved({ approval, session, outcome: 'reject', userId });
-    await wakeContainer(session);
-    return;
-  }
-
-  // Approved — dispatch to the module that registered for this action.
   const handler = getApprovalHandler(approval.action);
   if (!handler) {
     log.warn('No approval handler registered — row dropped', {
@@ -125,6 +135,11 @@ function isAuthorizedApprovalClick(approval: PendingApproval, payload: ResponseP
   const userId = namespacedUserId(payload);
   if (!userId) return false;
 
+  // An approval may name a specific approver; only that exact user may resolve it.
+  if (approval.approver_user_id) {
+    return userId === approval.approver_user_id;
+  }
+
   const agentGroupId =
     approval.agent_group_id ?? (approval.session_id ? getSession(approval.session_id)?.agent_group_id : null);
 

src/modules/permissions/channel-approval.ts

@@ -292,8 +292,10 @@ export function createNewAgentGroup(name: string): AgentGroup {
   });
 
   const ag = getAgentGroup(agId)!;
-  // Channel-approved groups get the built-in default provider (claude); the
-  // operator flips a group with `ncl groups config update --provider`.
+  // Channel-approved groups are created on the instance default provider
+  // (DEFAULT_AGENT_PROVIDER, or claude when unset) — initGroupFilesystem stamps
+  // it onto the fresh config row. The operator flips a group afterward with
+  // `ncl groups config update --provider`.
   initGroupFilesystem(ag);
   return ag;
 }

src/modules/permissions/index.ts

@@ -22,7 +22,7 @@ import {
   routeInbound,
   setAccessGate,
   setChannelRequestGate,
-  setMessageInterceptor,
+  registerMessageInterceptor,
   setSenderResolver,
   setSenderScopeGate,
   type AccessGateResult,
@@ -521,7 +521,7 @@ registerResponseHandler(handleChannelApprovalResponse);
 // Captures the next DM from an approver who clicked "Create new agent",
 // creates the agent immediately, wires the channel, and replays.
 
-setMessageInterceptor(async (event: InboundEvent): Promise<boolean> => {
+registerMessageInterceptor(async (event: InboundEvent): Promise<boolean> => {
   const userId = extractAndUpsertUser(event);
   if (!userId) return false;
 

src/router.ts

@@ -110,16 +110,20 @@ export function setSenderScopeGate(fn: SenderScopeGateFn): void {
 
 /**
  * Message-interceptor hook. Runs at the very top of routeInbound, before
- * messaging-group resolution. When the interceptor returns true the message
- * is consumed and routing stops. Used by the permissions module to capture
- * free-text replies during multi-step approval flows (e.g. agent naming).
+ * messaging-group resolution. When an interceptor returns true the message is
+ * consumed and routing stops. Multiple interceptors may register; they run in
+ * registration order and the first to claim the message (return true) wins.
+ *
+ * Used by modules to capture free-text DM replies during multi-step approval
+ * flows — the permissions module (agent naming during channel registration)
+ * and the approvals module (reject-with-reason capture).
  */
 export type MessageInterceptorFn = (event: InboundEvent) => Promise<boolean>;
 
-let messageInterceptor: MessageInterceptorFn | null = null;
+const messageInterceptors: MessageInterceptorFn[] = [];
 
-export function setMessageInterceptor(fn: MessageInterceptorFn): void {
-  messageInterceptor = fn;
+export function registerMessageInterceptor(fn: MessageInterceptorFn): void {
+  messageInterceptors.push(fn);
 }
 
 /**
@@ -156,9 +160,13 @@ function safeParseContent(raw: string): { text?: string; sender?: string; sender
  * Creates messaging group + session if they don't exist yet.
  */
 export async function routeInbound(event: InboundEvent): Promise<void> {
-  // Pre-route interceptor — lets modules consume messages before any routing
-  // (e.g. free-text replies during multi-step approval flows).
-  if (messageInterceptor && (await messageInterceptor(event))) return;
+  // Pre-route interceptors — let modules consume messages before any routing
+  // (e.g. free-text DM replies during multi-step approval flows). They run in
+  // registration order; the first to claim the message stops routing. The
+  // sequential await is intentional — first-to-claim is order-dependent.
+  for (const intercept of messageInterceptors) {
+    if (await intercept(event)) return;
+  }
 
   // 0. Apply the adapter's thread policy. Non-threaded adapters (Telegram,
   //    WhatsApp, iMessage, email) collapse threads to the channel. Resolved

src/session-manager.attachments.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Security regression for the channel-inbound attachment path (#2828 sibling).
+ *
+ * `extractAttachmentFiles` (via `writeSessionMessage`) hardens the per-message
+ * inbox subdir against pre-placed symlinks, but NOT the `inbox` root itself.
+ * A compromised container can write inside its own session dir, so it can
+ * replace `inbox` with a symlink pointing outside the session sandbox. The
+ * existing guard then:
+ *   - skips the lstat branch (it only lstats `inbox/<msgId>`, not `inbox`),
+ *   - mkdirs `inbox/<msgId>` *through* the symlink,
+ *   - passes the containment check, because it compares against
+ *     `realpathSync(inboxRoot)` which has already followed the symlink, and
+ *   - writes a brand-new file (the `wx` flag only blocks an existing dst).
+ *
+ * Result: the host writes attacker-influenced bytes outside the session root —
+ * the same class of bug fixed for the A2A path in forwardAttachedFiles (#2828).
+ *
+ * This test asserts the SECURE behaviour (nothing written outside). It FAILS
+ * against the current code, demonstrating the gap.
+ */
+import fs from 'fs';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('./config.js', async () => {
+  const actual = await vi.importActual<typeof import('./config.js')>('./config.js');
+  return { ...actual, DATA_DIR: '/tmp/nanoclaw-test-saveatt-gap' };
+});
+
+import { initTestDb, closeDb, runMigrations, createAgentGroup } from './db/index.js';
+import { createSession } from './db/sessions.js';
+import { initSessionFolder, sessionDir, writeSessionMessage } from './session-manager.js';
+import type { Session } from './types.js';
+
+const TEST_DIR = '/tmp/nanoclaw-test-saveatt-gap';
+const AG = 'ag-saveatt';
+const SESS = 'sess-saveatt';
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+
+  const db = initTestDb();
+  runMigrations(db);
+
+  createAgentGroup({ id: AG, name: 'SaveAtt', folder: 'saveatt', agent_provider: null, created_at: now() });
+  const sess: Session = {
+    id: SESS,
+    agent_group_id: AG,
+    messaging_group_id: null,
+    thread_id: null,
+    agent_provider: null,
+    status: 'active',
+    container_status: 'stopped',
+    last_active: null,
+    created_at: now(),
+  };
+  createSession(sess);
+  initSessionFolder(AG, SESS);
+});
+
+afterEach(() => {
+  closeDb();
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+});
+
+describe('extractAttachmentFiles — inbox-root symlink containment (#2828 sibling)', () => {
+  it('does not write an attachment outside the session root via a symlinked inbox root', () => {
+    // Attacker-controlled location outside the session sandbox.
+    const canaryDir = path.join(TEST_DIR, 'canary-outside');
+    fs.mkdirSync(canaryDir, { recursive: true });
+
+    // Container pre-places its whole `inbox` as a symlink pointing outside.
+    const inboxRoot = path.join(sessionDir(AG, SESS), 'inbox');
+    fs.rmSync(inboxRoot, { recursive: true, force: true });
+    fs.symlinkSync(canaryDir, inboxRoot);
+
+    const content = JSON.stringify({
+      text: 'see attached',
+      attachments: [{ name: 'pwn.txt', data: Buffer.from('attacker-bytes').toString('base64') }],
+    });
+
+    writeSessionMessage(AG, SESS, {
+      id: 'evil-inbox-root',
+      kind: 'chat',
+      timestamp: now(),
+      platformId: 'whatsapp:123',
+      channelType: 'whatsapp',
+      threadId: null,
+      content,
+    });
+
+    // SECURE expectation: nothing was written through the symlink to the
+    // attacker-controlled canary location.
+    const escaped = path.join(canaryDir, 'evil-inbox-root', 'pwn.txt');
+    expect(fs.existsSync(escaped)).toBe(false);
+    expect(fs.readdirSync(canaryDir)).toHaveLength(0);
+  });
+});

src/session-manager.ts

@@ -18,6 +18,7 @@ import { deriveAttachmentName } from './attachment-naming.js';
 import { isSafeAttachmentName } from './attachment-safety.js';
 import type { OutboundFile } from './channels/adapter.js';
 import { DATA_DIR } from './config.js';
+import { ensureContainedInboxDir, isPathInside } from './inbox-safety.js';
 import { getMessagingGroup } from './db/messaging-groups.js';
 import {
   createSession,
@@ -38,11 +39,6 @@ import {
 import { log } from './log.js';
 import type { Session } from './types.js';
 
-function isPathInside(parent: string, child: string): boolean {
-  const relative = path.relative(parent, child);
-  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-}
-
 /** Root directory for all session data. */
 export function sessionsBaseDir(): string {
   return path.join(DATA_DIR, 'v2-sessions');
@@ -288,6 +284,14 @@ function extractAttachmentFiles(
     return contentStr;
   }
 
+  const inboxRoot = path.join(sessionDir(agentGroupId, sessionId), 'inbox');
+  // Resolved lazily on the first attachment that actually carries bytes, so a
+  // message whose attachments have no inline `data` never creates an inbox dir.
+  // ensureContainedInboxDir refuses a pre-placed symlink at the inbox root or
+  // the per-message subdir before any write lands outside the sandbox (#2828).
+  let inboxDir: string | null = null;
+  let inboxResolved = false;
+
   let changed = false;
   for (const att of attachments) {
     if (typeof att.data !== 'string') continue;
@@ -302,32 +306,12 @@ function extractAttachmentFiles(
       });
     }
 
-    const inboxDir = path.join(sessionDir(agentGroupId, sessionId), 'inbox', messageId);
-
-    // Refuse to mkdir through a symlink that the container may have pre placed
-    // at inboxDir. With recursive:true, mkdirSync would silently no op on a
-    // pre existing symlink and the subsequent writeFileSync would follow it.
-    if (fs.existsSync(inboxDir)) {
-      const stat = fs.lstatSync(inboxDir);
-      if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        log.warn('Rejecting unsafe inbox directory', { messageId, inboxDir });
-        continue;
-      }
-    }
-    fs.mkdirSync(inboxDir, { recursive: true });
-
-    let realInboxDir: string;
-    try {
-      realInboxDir = fs.realpathSync(inboxDir);
-    } catch (err) {
-      log.warn('Failed to resolve inbox directory', { messageId, err });
-      continue;
-    }
-    const inboxRoot = path.join(sessionDir(agentGroupId, sessionId), 'inbox');
-    if (!isPathInside(fs.realpathSync(inboxRoot), realInboxDir)) {
-      log.warn('Inbox directory escaped session inbox root', { messageId, inboxDir });
-      continue;
+    if (!inboxResolved) {
+      inboxDir = ensureContainedInboxDir(inboxRoot, messageId, { messageId });
+      inboxResolved = true;
     }
+    // Unsafe inbox (symlink / escape) — no attachment can be written safely.
+    if (!inboxDir) break;
 
     const filePath = path.join(inboxDir, filename);
     try {

src/templates/create-agent.test.ts

@@ -0,0 +1,83 @@
+import fs from 'fs';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const TEST_ROOT = '/tmp/nanoclaw-create-agent-test';
+const GROUPS_DIR = path.join(TEST_ROOT, 'groups');
+const DATA_DIR = path.join(TEST_ROOT, 'data');
+const TEMPLATES_DIR = path.join(TEST_ROOT, 'templates');
+
+vi.mock('../config.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../config.js')>()),
+  GROUPS_DIR: '/tmp/nanoclaw-create-agent-test/groups',
+  DATA_DIR: '/tmp/nanoclaw-create-agent-test/data',
+  TEMPLATES_DIR: '/tmp/nanoclaw-create-agent-test/templates',
+}));
+
+vi.mock('../log.js', () => ({
+  log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), fatal: vi.fn() },
+}));
+
+import { closeDb, initTestDb, runMigrations } from '../db/index.js';
+import { getContainerConfig } from '../db/container-configs.js';
+import { PERSONA_PREPEND_FILE } from '../group-persona.js';
+import { createAgentFromTemplate } from './create-agent.js';
+
+function writeTemplate(): void {
+  const t = path.join(TEMPLATES_DIR, 'sales', 'sdr');
+  fs.mkdirSync(path.join(t, 'context', 'additional_context'), { recursive: true });
+  fs.writeFileSync(path.join(t, 'context', 'instructions.md'), 'You are an SDR agent.\n');
+  fs.writeFileSync(path.join(t, 'context', 'playbook.md'), '# Playbook\n');
+  fs.writeFileSync(path.join(t, 'context', 'additional_context', 'faq.md'), '# FAQ\n');
+  fs.writeFileSync(
+    path.join(t, '.mcp.json'),
+    JSON.stringify({ mcpServers: { hubspot: { command: 'npx', args: ['-y', '@hubspot/mcp-server'] } } }),
+  );
+  const skillDir = path.join(t, 'skills', 'widget');
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), '---\nname: widget\n---\n');
+}
+
+beforeEach(() => {
+  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
+  fs.mkdirSync(TEST_ROOT, { recursive: true });
+  runMigrations(initTestDb());
+  writeTemplate();
+});
+
+afterEach(() => {
+  closeDb();
+  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
+});
+
+describe('createAgentFromTemplate', () => {
+  it('writes the persona prepend verbatim — no injected context refs, no .seed.md', () => {
+    const g = createAgentFromTemplate('sales/sdr', { name: 'SDR Test' });
+
+    const groupDir = path.join(GROUPS_DIR, g.folder);
+    const prepend = fs.readFileSync(path.join(groupDir, PERSONA_PREPEND_FILE), 'utf-8');
+    expect(prepend).toBe('You are an SDR agent.\n');
+    expect(fs.existsSync(path.join(groupDir, '.seed.md'))).toBe(false);
+  });
+
+  it('copies template skills into the group-private Claude-plane skills dir', () => {
+    const g = createAgentFromTemplate('sales/sdr', { name: 'SDR Skills' });
+
+    const skill = path.join(DATA_DIR, 'v2-sessions', g.id, '.claude-shared', 'skills', 'widget', 'SKILL.md');
+    expect(fs.existsSync(skill)).toBe(true);
+  });
+
+  it('writes MCP servers to the container config and context extras at their template-relative paths', () => {
+    const g = createAgentFromTemplate('sales/sdr', { name: 'SDR Mcp' });
+
+    const cfg = getContainerConfig(g.id);
+    expect(cfg).toBeTruthy();
+    expect(JSON.parse(cfg!.mcp_servers)).toHaveProperty('hubspot');
+    // Extras land relative to the group root, exactly as they sit relative to
+    // instructions.md in the template — no context/ prefix in between.
+    const groupDir = path.join(GROUPS_DIR, g.folder);
+    expect(fs.existsSync(path.join(groupDir, 'playbook.md'))).toBe(true);
+    expect(fs.existsSync(path.join(groupDir, 'additional_context', 'faq.md'))).toBe(true);
+    expect(fs.existsSync(path.join(groupDir, 'context'))).toBe(false);
+  });
+});

src/templates/create-agent.ts

@@ -0,0 +1,78 @@
+import { randomUUID } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+import { DATA_DIR, GROUPS_DIR } from '../config.js';
+import { createAgentGroup } from '../db/agent-groups.js';
+import { ensureContainerConfig, updateContainerConfigJson } from '../db/container-configs.js';
+import { assertValidGroupFolder, resolveGroupFolderPath } from '../group-folder.js';
+import { PERSONA_PREPEND_FILE } from '../group-persona.js';
+import { normalizeName } from '../modules/agent-to-agent/db/agent-destinations.js';
+import type { AgentGroup } from '../types.js';
+import { resolveLocalTemplate } from './local-dir.js';
+import { parseTemplate } from './parse.js';
+
+export interface CreateAgentOptions {
+  name?: string;
+}
+
+/**
+ * Stamp a self-contained agent group from a LOCAL template ref under
+ * TEMPLATES_DIR. The template carries MCP servers, instructions, optional
+ * context extras, and optional skills — nothing else (no policy, no packages,
+ * no provider).
+ *
+ * The template persona is written to the provider-neutral `instructions.prepend.md`
+ * (see src/group-persona.ts). Each provider's project-doc composer inlines it at
+ * the TOP of the doc it generates every spawn, so the persona is system-prompt
+ * tier regardless of which provider the group ends up running. Because the file
+ * is provider-agnostic, placement needs no provider knowledge at stamp time (the
+ * provider is DB-resolved later, at first spawn).
+ *
+ * Returns the created group; the caller wires it to a channel as usual.
+ */
+export function createAgentFromTemplate(ref: string, opts?: CreateAgentOptions): AgentGroup {
+  const dir = resolveLocalTemplate(ref);
+  const tpl = parseTemplate(dir);
+
+  const id = randomUUID();
+  const name = opts?.name ?? path.basename(dir);
+  let folder = normalizeName(name);
+  assertValidGroupFolder(folder);
+  if (fs.existsSync(resolveGroupFolderPath(folder))) folder = `${folder}-${randomUUID().slice(0, 8)}`;
+
+  const group: AgentGroup = { id, name, folder, agent_provider: null, created_at: new Date().toISOString() };
+  createAgentGroup(group);
+  ensureContainerConfig(id);
+
+  // group-init.ts owns the mkdir at first spawn, but it isn't called here — so we
+  // create the dir ourselves to land instructions.prepend.md + context/.
+  const groupDir = path.resolve(GROUPS_DIR, folder);
+  fs.mkdirSync(groupDir, { recursive: true });
+
+  // Persona → provider-neutral prepend, inlined at the top of the group's
+  // CLAUDE.md/AGENTS.md every spawn (system-prompt tier on any provider).
+  fs.writeFileSync(path.join(groupDir, PERSONA_PREPEND_FILE), tpl.instructions + '\n');
+
+  // Context extras keep their template-relative layout, placed next to the doc
+  // the persona is inlined into — so a reference written in instructions.md
+  // (e.g. `additional_context/faq.md`) resolves unchanged in the agent's
+  // workspace. Nothing is injected into the persona; referencing each file from
+  // instructions.md is the template author's job (docs/templates.md).
+  for (const { name: file, content } of tpl.contextExtras) {
+    const dest = path.join(groupDir, file);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, content);
+  }
+
+  updateContainerConfigJson(id, 'mcp_servers', tpl.mcpServers);
+
+  // Per-group skills overlay — keyed by group id, never shared. cpSync creates
+  // intermediate dirs, so .claude-shared/skills need not exist yet.
+  const skillsDir = path.join(DATA_DIR, 'v2-sessions', id, '.claude-shared', 'skills');
+  for (const { name: skill, srcDir } of tpl.skills) {
+    fs.cpSync(srcDir, path.join(skillsDir, skill), { recursive: true });
+  }
+
+  return group;
+}

src/templates/local-dir.test.ts

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { resolveLocalTemplate } from './local-dir.js';
+
+let base: string;
+
+beforeEach(() => {
+  base = fs.mkdtempSync(path.join(os.tmpdir(), 'tpl-local-'));
+  fs.mkdirSync(path.join(base, 'sales', 'sdr'), { recursive: true });
+  fs.writeFileSync(path.join(base, 'afile.md'), 'not a directory');
+});
+afterEach(() => fs.rmSync(base, { recursive: true, force: true }));
+
+describe('resolveLocalTemplate', () => {
+  it('resolves a valid multi-segment relative ref under the base', () => {
+    expect(resolveLocalTemplate('sales/sdr', base)).toBe(path.join(base, 'sales', 'sdr'));
+  });
+
+  it('rejects a ref that escapes the base via ../', () => {
+    expect(() => resolveLocalTemplate('../escape', base)).toThrow(/escapes/);
+  });
+
+  it('rejects a multi-segment escape like sales/../../etc', () => {
+    expect(() => resolveLocalTemplate('sales/../../etc', base)).toThrow(/escapes/);
+  });
+
+  it('rejects an absolute ref', () => {
+    expect(() => resolveLocalTemplate('/etc', base)).toThrow(/relative/);
+  });
+
+  it('rejects a ~-prefixed ref', () => {
+    expect(() => resolveLocalTemplate('~/x', base)).toThrow(/relative/);
+  });
+
+  it('rejects empty and whitespace-only refs', () => {
+    expect(() => resolveLocalTemplate('', base)).toThrow(/Invalid/);
+    expect(() => resolveLocalTemplate('   ', base)).toThrow(/Invalid/);
+  });
+
+  it('rejects an untrimmed ref', () => {
+    expect(() => resolveLocalTemplate(' sales/sdr', base)).toThrow(/Invalid/);
+  });
+
+  it('throws when the ref does not exist', () => {
+    expect(() => resolveLocalTemplate('nope', base)).toThrow(/not found/i);
+  });
+
+  it('throws when the ref is a file, not a directory', () => {
+    expect(() => resolveLocalTemplate('afile.md', base)).toThrow(/not found/i);
+  });
+});