feat(skills): structured nc: directive format + apply engine, first applied to Slack

Introduces the optionally-deterministic skill format. Official skills carry `nc:` directive fences (copy/append/dep/run/prompt/env-set/env-sync) embedded in prose, so one SKILL.md is both agent-readable and machine-appliable. Robustness lives in the whole system — graceful degradation to an agent, plus lint + tests — not in the syntax, so the directives stay minimal and readable. scripts/skill-directives.ts — parser + linter. Extracts nc: directives; flags unpinned deps, undefined {{var}} references, and a @chat-adapter/* pin that doesn't match our lockfile's `chat` core (the drift that put add-slack on the wrong version). scripts/skill-apply.ts — the application engine. Plan (idempotency, prompt resolution, no writes) → mutate (copy/append/env-set, journaled) → run (dep/build/test). Remove is the journal played back (no hand-written REMOVE.md). Anything the engine can't do bounces to an AGENT with its prose — never the human, never a hard abort. A Prompter abstraction lets one engine serve both interactive setup and headless rebuilds; fork-aware remote resolution replaces a hardcoded `origin`. .claude/skills/add-slack/SKILL.md — converted to the format; `prompt` split from `env-set` so a captured secret can feed env, ncl, or the vault; pinned 4.26.0 to match our chat core. setup/channels/slack.ts — the Slack setup flow now applies the skill through the engine in-process (secrets via the Prompter, never argv/disk), deleting the hand-maintained setup/add-slack.sh + install-slack.sh, which had drifted from the skill (they pinned 4.26.0 vs the skill's stale 4.27.0). One source of truth. Verified end-to-end in an isolated worktree: apply copies the adapter + its registration test, installs 4.26.0, builds clean against chat@4.26.0, and the registration test passes. 19 unit tests for the parser + engine. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
refactor(add-codex): install Codex CLI via cli-tools.json, not the Dockerfile
2026-06-15 18:21:47 +08:00 · 2026-06-14 22:42:47 +03:00 · 2026-06-14 21:40:44 +03:00 · 2026-06-14 18:29:28 +00:00 · 2026-06-14 18:29:25 +00:00 · 2026-06-14 21:29:12 +03:00
68 changed files with 3062 additions and 682 deletions
@@ -1,83 +1,78 @@
-# Remove Codex provider
+# Remove the Codex agent provider

-Idempotent — safe to run even if some steps were never applied. Reverses both the host (`src/providers/`) and container (`container/agent-runner/src/providers/`) trees, plus the Dockerfile CLI install.
+Reverses every change `/add-codex` makes and returns every group to the default provider. Safe to run when partially installed — skip any step whose target is already absent.

-## 1. Delete the barrel import lines (both trees)
+## 1. Switch codex groups back to the default

-Delete (do not comment out) the `import './codex.js';` line from each barrel:
+List groups still on codex and switch each one (each group's `memory/` tree stays on disk and readable; run `/migrate-memory` per group if its memory should carry back to Claude — see [docs/provider-migration.md](../../docs/provider-migration.md)):
+
+```bash
+ncl groups list
+# for each group whose config shows provider=codex:
+ncl groups config update --id <group-id> --provider claude
+ncl groups restart --id <group-id>
+```
+
+## 2. Delete the barrel imports
+
+Delete (do not comment out) the `import './codex.js';` line from each of:

 - `src/providers/index.ts`
 - `container/agent-runner/src/providers/index.ts`
+- `setup/providers/index.ts`

-This unregisters the provider from both `listProviderContainerConfigNames()` (host) and `listProviderNames()` (container).
-
-## 2. Delete the copied files (both trees)
+## 3. Delete every copied file

 ```bash
 rm -f src/providers/codex.ts \
+      src/providers/codex-agents-md.ts \
      src/providers/codex-registration.test.ts \
+      src/providers/codex-host-contribution.test.ts \
+      src/providers/codex-agents-md.test.ts \
      container/agent-runner/src/providers/codex.ts \
      container/agent-runner/src/providers/codex-app-server.ts \
-      container/agent-runner/src/providers/codex.factory.test.ts \
+      container/agent-runner/src/providers/exchange-archive.ts \
+      container/agent-runner/src/providers/exchange-archive.test.ts \
      container/agent-runner/src/providers/codex-registration.test.ts \
-      container/agent-runner/src/providers/codex-dockerfile.test.ts
+      container/agent-runner/src/providers/codex.factory.test.ts \
+      container/agent-runner/src/providers/codex.turns.test.ts \
+      container/agent-runner/src/providers/codex-app-server.test.ts \
+      container/agent-runner/src/providers/codex-cli-tools.test.ts \
+      setup/providers/codex.ts \
+      setup/providers/codex.test.ts \
+      setup/providers/codex-registration.test.ts
 ```

-## 3. Revert the Dockerfile CLI install
+This skill itself (`.claude/skills/add-codex/`) stays — it ships with trunk so the provider can be re-added later.

-In `container/Dockerfile`, remove both Codex edits (skip whichever is already gone):
+`container/AGENTS.md` stays only if another installed provider uses agent surfaces; otherwise remove it too.

-**(a)** Delete the version ARG from the "Pin CLI versions" block:
+## 4. Remove the CLI manifest entry

-```dockerfile
-ARG CODEX_VERSION=0.124.0
-```
-
-**(b)** Delete the standalone Codex install layer:
-
-```dockerfile
-RUN --mount=type=cache,target=/root/.cache/pnpm \
-    pnpm install -g "@openai/codex@${CODEX_VERSION}"
-```
-
-Leave the other per-CLI install layers (claude-code, agent-browser, vercel) untouched.
-
-## 4. Dependency
-
-Codex is a CLI binary installed via the Dockerfile — there is no agent-runner package dependency to uninstall. Step 3 removes the only install surface; no `bun remove` / `pnpm uninstall` is needed.
-
-## 5. Unset Codex env vars
-
-Remove any Codex-specific lines you added to `.env` (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `CODEX_MODEL`) if no other integration uses them, then re-sync to the container:
+Delete the `@openai/codex` entry from `container/cli-tools.json`:

 ```bash
-mkdir -p data/env && cp .env data/env/env
+node -e '
+  const fs = require("fs");
+  const file = "container/cli-tools.json";
+  const tools = JSON.parse(fs.readFileSync(file, "utf8")).filter((t) => t.name !== "@openai/codex");
+  const fmt = (t) => "  { " + Object.entries(t).map(([k, v]) => JSON.stringify(k) + ": " + JSON.stringify(v)).join(", ") + " }";
+  fs.writeFileSync(file, "[\n" + tools.map(fmt).join(",\n") + "\n]\n");
+'
 ```

-Switch any group still on Codex back to the default provider — set `"provider": "claude"` in `groups/<folder>/container.json` and clear `agent_provider` on the group/session in the DB.
+## 5. Vault secret (optional)

-## 6. Rebuild and restart
+The ChatGPT/OpenAI secret in the OneCLI vault grants nothing once the provider is gone. To remove it: `onecli secrets list`, then `onecli secrets delete --id <id>` for the `chatgpt.com` / `api.openai.com` entry.

-Run from your NanoClaw project root:
+## 6. Rebuild and verify

 ```bash
-pnpm run build && ./container/build.sh
-source setup/lib/install-slug.sh
-
-# macOS
-launchctl kickstart -k gui/$(id -u)/$(launchd_label)
-
-# Linux
-systemctl --user restart $(systemd_unit)
+pnpm run build
+pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
+./container/build.sh
+pnpm test
+cd container/agent-runner && bun test
 ```

-## Verification
-
-After removal, the registration guards no longer apply (their files are gone). Confirm the provider is fully unwired:
-
-```bash
-grep -R "codex.js" src/providers/index.ts container/agent-runner/src/providers/index.ts   # no output
-grep "@openai/codex" container/Dockerfile                                                  # no output
-```
-
-In a wired agent, requesting `agent_provider = 'codex'` should fall back to the default provider since `codex` is no longer in the registry.
+All suites green and `ncl groups list` showing no codex groups means the removal is complete. Restart the service (`launchctl kickstart -k gui/$(id -u)/<label>` on macOS, `systemctl --user restart <unit>` on Linux).
@@ -1,186 +1,126 @@
 ---
 name: add-codex
-description: Use Codex (CLI + AppServer) as the full agent provider — planning, tool orchestration, native compaction, MCP tools, session resume — in place of the Claude Agent SDK. ChatGPT subscription or OPENAI_API_KEY. Per-group via agent_provider. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).
+description: Use Codex (OpenAI's codex app-server) as a full agent provider — planning, tool orchestration, MCP tools, server-side history, session resume — alongside or instead of Claude. ChatGPT subscription or OpenAI API key, vault-only via OneCLI. Per-group via `ncl groups config update --provider codex`. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).
 ---

 # Codex agent provider

-NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected with **`AGENT_PROVIDER`** (`claude` | `opencode` | `codex` | `mock`).
+> Shortcut: `pnpm exec tsx setup/index.ts --step provider-auth codex` performs this whole install (manifest-driven from the providers branch: files, barrels, CLI manifest entry, image rebuild) plus auth in one command. The steps below are the same operations, for agent-driven or manual application.

-Trunk ships with only the `claude` provider baked in. This skill copies the Codex provider files in from the `providers` branch, wires them into the host and container barrels, updates the Dockerfile to install the Codex CLI, and rebuilds the image.
+NanoClaw selects each group's agent backend from `container_configs.provider` (default `claude`). This skill installs the Codex provider: copy the payload from the `providers` branch, append one import to each of the three provider barrels, add the pinned Codex CLI to the container manifest (`container/cli-tools.json`), rebuild, then run the vault auth walk-through.

-The Codex provider runs `codex app-server` as a child process and speaks JSON-RPC over stdio. That gives it native session resume, streaming events, MCP tool access, and `thread/compact/start` compaction — same feature bar as the Claude Agent SDK, without the Anthropic-only lock-in.
+The provider runs `codex app-server` as a child process speaking JSON-RPC over stdio: native streaming, MCP tools, server-side conversation history (the continuation is a thread id, no on-disk transcript). Credentials are **vault-only**: OneCLI serves a sentinel `auth.json` stub into the container and swaps the real ChatGPT token or API key on the wire — no key in `.env`, nothing readable in the container.

 ## Install

 ### Pre-flight

-If all of the following are already present, skip to **Configuration**:
+Check whether the payload is already wired (a prior apply, or a trunk that still carries it). All of these present means installed — skip to **Authenticate**:

- `src/providers/codex.ts`
- `src/providers/codex-registration.test.ts`
- `container/agent-runner/src/providers/codex.ts`
- `container/agent-runner/src/providers/codex-app-server.ts`
- `container/agent-runner/src/providers/codex.factory.test.ts`
- `container/agent-runner/src/providers/codex-registration.test.ts`
- `container/agent-runner/src/providers/codex-dockerfile.test.ts`
- `import './codex.js';` line in `src/providers/index.ts`
- `import './codex.js';` line in `container/agent-runner/src/providers/index.ts`
- `ARG CODEX_VERSION` and `"@openai/codex@${CODEX_VERSION}"` in the pnpm global-install block in `container/Dockerfile`
+- `src/providers/codex.ts` and `src/providers/codex-agents-md.ts`
+- `container/agent-runner/src/providers/codex.ts` and `codex-app-server.ts`
+- `setup/providers/codex.ts`
+- `import './codex.js';` in `src/providers/index.ts`, `container/agent-runner/src/providers/index.ts`, and `setup/providers/index.ts`
+- an `@openai/codex` entry in `container/cli-tools.json`

-Missing pieces — continue below. All steps are idempotent; re-running is safe.
-
-### 1. Fetch the providers branch
+### Fetch and copy

 ```bash
 git fetch origin providers
 ```

-### 2. Copy the Codex source files and tests
+Copy each file with `git show origin/providers:<path> > <path>` (additive — never merge the branch):

-Wholesale copies (owned entirely by this skill — user edits to these files won't survive a re-run, as designed):
+Host (`src/providers/`):
+- `codex.ts` — provider contribution: per-group `.codex-shared` state dir, AGENTS.md compose, skill links
+- `codex-agents-md.ts` — AGENTS.md composition (32KB Codex cap: degrades by dropping the largest instruction sections, never blocks a spawn)
+- `codex-registration.test.ts` — barrel-driven host registration guard
+- `codex-host-contribution.test.ts` — drives the real contribution against a real test DB (the "consumes core" leg)
+- `codex-agents-md.test.ts` — cap-degradation behavior
+
+Container (`container/agent-runner/src/providers/`):
+- `codex.ts` — the provider (turn loop, steering, memory scaffold + `onExchangeComplete` archiving)
+- `codex-app-server.ts` — JSON-RPC child-process wrapper
+- `exchange-archive.ts` — per-exchange markdown writer the `onExchangeComplete` hook uses (provider-owned, not runner code)
+- `exchange-archive.test.ts` — writer behavior
+- `codex-registration.test.ts` — barrel-driven container registration guard
+- `codex.factory.test.ts`, `codex.turns.test.ts`, `codex-app-server.test.ts` — provider behavior
+- `codex-cli-tools.test.ts` — structural guard for the Codex entry in `container/cli-tools.json`
+
+Setup (`setup/providers/`):
+- `codex.ts` — picker entry self-registration + the vault auth walk-through + install check
+- `codex.test.ts` — install-check coverage
+- `codex-registration.test.ts` — barrel-driven setup registration guard
+
+Shared base (skip if present):
+- `container/AGENTS.md` — the runtime-contract base the composed AGENTS.md embeds
+
+### Wire the barrels
+
+Append `import './codex.js';` to each of:
+- `src/providers/index.ts`
+- `container/agent-runner/src/providers/index.ts`
+- `setup/providers/index.ts`
+
+### CLI manifest
+
+The agent's global Node CLIs install from `container/cli-tools.json` (a json-merge seam), not hand-edited Dockerfile layers. Add Codex by appending one entry — `@openai/codex` has no native postinstall, so no `onlyBuilt`:

 ```bash
-git show origin/providers:src/providers/codex.ts                                         > src/providers/codex.ts
-git show origin/providers:src/providers/codex-registration.test.ts                       > src/providers/codex-registration.test.ts
-git show origin/providers:container/agent-runner/src/providers/codex.ts                  > container/agent-runner/src/providers/codex.ts
-git show origin/providers:container/agent-runner/src/providers/codex-app-server.ts       > container/agent-runner/src/providers/codex-app-server.ts
-git show origin/providers:container/agent-runner/src/providers/codex.factory.test.ts     > container/agent-runner/src/providers/codex.factory.test.ts
-git show origin/providers:container/agent-runner/src/providers/codex-registration.test.ts > container/agent-runner/src/providers/codex-registration.test.ts
+node -e '
+  const fs = require("fs");
+  const file = "container/cli-tools.json";
+  const tools = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!tools.some((t) => t.name === "@openai/codex")) {
+    tools.push({ name: "@openai/codex", version: "0.138.0" });
+    const fmt = (t) => "  { " + Object.entries(t).map(([k, v]) => JSON.stringify(k) + ": " + JSON.stringify(v)).join(", ") + " }";
+    fs.writeFileSync(file, "[\n" + tools.map(fmt).join(",\n") + "\n]\n");
+  }
+'
 ```

-The two `codex-registration.test.ts` files are the **registration guards**. Each imports only the real barrel — the host one calls `listProviderContainerConfigNames()` from `src/providers/index.ts`, the container one calls `listProviderNames()` from `container/agent-runner/src/providers/index.ts` — and asserts `codex` is present. They go red the instant a barrel import line is deleted or drifts. (`codex.factory.test.ts` imports `./codex.js` directly and self-registers, so it stays green even if the barrel line is gone — keep it as a unit test of provider behavior, but it is **not** the registration guard.)
+The version (`0.138.0`) is the canonical pin — keep it in sync with `setup/add-codex.sh`. The Dockerfile already installs every manifest entry via pinned `pnpm install -g`; no Dockerfile edit is needed.

-If `git show origin/providers:.../codex-registration.test.ts` errors with `path ... does not exist`, the registration tests have not landed on `origin/providers` yet. Run `git fetch origin providers` again; once the branch carries them, the copies above succeed. The rest of the install proceeds regardless — the Dockerfile and factory tests still run.
-
-Copy the Dockerfile structural test that ships with this skill into the container provider tree:
+### Build

 ```bash
-cp .claude/skills/add-codex/codex-dockerfile.test.ts container/agent-runner/src/providers/codex-dockerfile.test.ts
+pnpm run build
+pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
+./container/build.sh
 ```

-`codex-dockerfile.test.ts` reads the real `container/Dockerfile` and asserts the `ARG CODEX_VERSION=` line and the `pnpm install -g "@openai/codex@${CODEX_VERSION}"` line are both present. The Codex CLI is a binary, not an importable package, so the registration tests cannot see it — this structural test is what guards the Dockerfile edits in step 4.
-
-### 3. Append the self-registration imports
-
-Each barrel gets one line — alphabetical placement keeps diffs small.
-
-`src/providers/index.ts`:
-
-```typescript
-import './codex.js';
-```
-
-`container/agent-runner/src/providers/index.ts`:
-
-```typescript
-import './codex.js';
-```
-
-### 4. Add the Codex CLI to the container Dockerfile
-
-Two edits to `container/Dockerfile`, both idempotent (skip if already present):
-
-**(a)** In the "Pin CLI versions" ARG block (around line 18), add after `ARG CLAUDE_CODE_VERSION=...`:
-
-```dockerfile
-ARG CODEX_VERSION=0.124.0
-```
-
-**(b)** Add a new standalone `RUN` block for the Codex CLI, after the existing per-CLI install blocks (around line 106, right after the `@anthropic-ai/claude-code` block). The Dockerfile splits each global CLI into its own layer for cache granularity — keep that pattern; do not collapse them into a single combined `pnpm install -g` call:
-
-```dockerfile
-RUN --mount=type=cache,target=/root/.cache/pnpm \
-    pnpm install -g "@openai/codex@${CODEX_VERSION}"
-```
-
-Note: **no agent-runner package dependency** — Codex is a CLI binary, not a library. Unlike OpenCode, there's nothing to add to `container/agent-runner/package.json`.
-
-### 5. Build and validate
+### Validate

 ```bash
-pnpm run build                                                          # host
-pnpm exec vitest run src/providers/codex-registration.test.ts          # host registration guard
-pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit         # container typecheck
-cd container/agent-runner && bun test src/providers/codex-registration.test.ts && cd -   # container registration guard
-cd container/agent-runner && bun test src/providers/codex-dockerfile.test.ts && cd -      # Dockerfile structural guard
-./container/build.sh                                                    # agent image
+pnpm vitest run src/providers/codex-registration.test.ts src/providers/codex-host-contribution.test.ts src/providers/codex-agents-md.test.ts setup/providers/
+cd container/agent-runner && bun test src/providers/
 ```

-All must be clean before proceeding.
+The registration tests import only the real barrels — they go red if a barrel line is missing, a barrel fails to evaluate, or the payload is broken.

- The **host** `codex-registration.test.ts` imports the real host barrel (`src/providers/index.ts`) and asserts `listProviderContainerConfigNames()` contains `codex`. It goes red if the `import './codex.js';` line is deleted or drifts, or if the barrel fails to evaluate.
- The **container** `codex-registration.test.ts` imports the real container barrel (`container/agent-runner/src/providers/index.ts`) and asserts `listProviderNames()` contains `codex`. Same failure surface for the container-side import line.
- The **Dockerfile** `codex-dockerfile.test.ts` reads `container/Dockerfile` and asserts the `ARG CODEX_VERSION=` and `@openai/codex@${CODEX_VERSION}` install lines are present — red if either edit is dropped.
-
-The `@openai/codex` CLI binary is guarded by the Dockerfile structural test plus the container build (`./container/build.sh` fails if the install line is bad), **not** by the registration test — Codex is a CLI binary, not an importable package, so nothing imports it for the registration guard to trip on. To confirm the binary is actually present after the image rebuild, probe it inside a running container with `docker exec <container> codex --version`.
-
-The host-side provider also consumes core APIs (per-session `~/.codex` mount, env passthrough); that typed core-API consumption is guarded by `pnpm run build`.
-
-## Configuration
-
-Codex supports two primary auth paths and one experimental BYO-endpoint path. Pick the one that matches your setup.
-
-### Option A — ChatGPT subscription (recommended for individuals)
-
-On the host (not inside the container), run Codex's OAuth login:
+## Authenticate

 ```bash
-codex login
+pnpm exec tsx setup/index.ts --step provider-auth codex
 ```

-This writes `~/.codex/auth.json` with a subscription token. The host-side Codex provider ([src/providers/codex.ts](../../../src/providers/codex.ts)) copies `auth.json` into a per-session `~/.codex` directory mounted into the container — your host's own Codex CLI is never touched.
+The same walk-through fresh installs get from the setup picker: ChatGPT subscription (browser login or device pairing) or an OpenAI API key, landed in the OneCLI vault. Idempotent — it short-circuits when a matching secret already exists. It finishes with the install check.

-No `.env` variables required for this mode.
+## Use it

-### Option B — API key (recommended for CI or API billing)
+Per group:

-```env
-OPENAI_API_KEY=sk-...
-CODEX_MODEL=gpt-5.4-mini
+```bash
+ncl groups config update --id <group-id> --provider codex
+ncl groups restart --id <group-id>
 ```

-The host forwards both variables into the container. If both subscription (`auth.json`) and `OPENAI_API_KEY` are present, Codex prefers the subscription.
+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.

-### Option C — BYO OpenAI-compatible endpoint (experimental)
+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.

-Codex's built-in `openai` provider honors the `OPENAI_BASE_URL` env var directly. Point it at any OpenAI-compatible endpoint — Groq, Together, self-hosted vLLM, an OpenAI proxy, etc.
+## Troubleshooting

-```env
-OPENAI_API_KEY=...
-OPENAI_BASE_URL=https://api.groq.com/openai/v1
-CODEX_MODEL=llama-3.3-70b-versatile
-```
-
-Codex also ships first-class local-runner flags — `codex --oss --local-provider ollama` or `--local-provider lmstudio` — that auto-detect a local server. To use those inside NanoClaw, set `CODEX_MODEL` to a model your local runner serves and add the corresponding base URL; see the Codex CLI docs for the full `model_provider = oss` configuration.
-
-**Experimental caveat:** tool-calling quality depends on the model and endpoint. Not every OpenAI-compat provider implements the full function-calling spec, and smaller models (< 30B) often struggle with multi-step tool orchestration. Test before committing.
-
-### Per group / per session
-
-Set `"provider": "codex"` in the group's **`container.json`** (`groups/<folder>/container.json`) — the in-container runner reads `provider` from there, not from the DB. The DB columns **`agent_groups.agent_provider`** and **`sessions.agent_provider`** (session overrides group) only drive host-side provider contribution — per-session `~/.codex` mount, `OPENAI_*` / `CODEX_MODEL` env passthrough — and do not propagate into `container.json` at spawn time. Set both, or just edit `container.json`; if they disagree, the runner uses `container.json` and the host-side resolver falls back through session → group → `container.json` → `'claude'`.
-
-`CODEX_MODEL` applies process-wide via `.env`; if you need different models for different groups, set them via `container_config.env` on the group.
-
-Extra MCP servers still come from **`NANOCLAW_MCP_SERVERS`** / `container_config.mcpServers` on the host. The runner merges them into the same `mcpServers` object passed to all providers.
-
-## Operational notes
-
- **Spawn-per-query:** Codex's app-server is spawned fresh per query invocation, matching the OpenCode pattern. No long-lived daemon to keep healthy across sessions.
- **Per-session `~/.codex` isolation:** each group gets its own copy of the host's `auth.json`. The container can rewrite `config.toml` freely on every wake without touching the host's Codex config.
- **Native compaction:** kicks in automatically at 40K cumulative input tokens between turns, via `thread/compact/start`. If compaction fails, the provider logs and continues uncompacted — no fatal error.
- **Approvals:** auto-accepted inside the container (the container is the sandbox; same posture as Claude/OpenCode).
- **Mid-turn input:** Codex turns don't accept mid-turn messages. Follow-up `push()` calls queue and drain between turns, matching the OpenCode pattern. The poll-loop only pushes between turns anyway, so no messages are dropped.
- **Stale thread recovery:** `isSessionInvalid` matches on stale-thread-ID errors (`thread not found`, `unknown thread`, etc.) so a cold-started app-server can recover cleanly when it sees a stored continuation it no longer has.
-
-## Next Steps
-
-The registration and Dockerfile guards in **Build and validate** confirm the wiring. For a live end-to-end check, set `agent_provider = 'codex'` on a test group and send a message after the image rebuild. A successful round-trip looks like:
-
- `init` event with a stable thread ID as continuation
- One or more `activity` / `progress` events during the turn
- `result` event with the model's reply
-
-If the agent hangs or errors, check `~/.codex/auth.json` exists on the host (Option A) or that `OPENAI_API_KEY` is forwarding correctly (Option B) — `docker exec` into a running container and `env | grep -i openai` to confirm. To confirm the CLI binary itself landed in the image, `docker exec <container> codex --version`.
-
-To back this provider out, follow [REMOVE.md](REMOVE.md).
+- **Container dies at boot, channel silent:** `grep 'Container exited non-zero' logs/nanoclaw.error.log` — the `stderrTail` carries the reason (e.g. `Unknown provider: codex. Registered: claude` means the barrels aren't wired in the running build).
+- **In-channel `Error: spawn codex ENOENT` on every message:** the image predates the manifest entry — re-run `./container/build.sh`.
+- **Auth errors mid-conversation:** the vault secret is missing or stale — re-run `pnpm exec tsx setup/index.ts --step provider-auth codex` (subscription re-login updates the vault copy).
@@ -0,0 +1,39 @@
+// Structural guard for the Codex CLI install in container/cli-tools.json.
+//
+// @openai/codex is a CLI *binary* installed from the global-CLI manifest (a
+// json-merge seam), not an importable package, so the barrel-driven
+// registration tests cannot see it. This test reads the real cli-tools.json
+// and asserts the @openai/codex entry is present and pinned to an exact
+// version. It goes red if the manifest entry is dropped or unpins.
+//
+// Runs under bun (same suite as the container registration test):
+//   cd container/agent-runner && bun test src/providers/codex-cli-tools.test.ts
+
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+
+import { describe, it, expect } from 'bun:test';
+
+// container/agent-runner/src/providers/ -> container/cli-tools.json
+const MANIFEST = path.join(import.meta.dir, '..', '..', '..', 'cli-tools.json');
+const manifestPresent = existsSync(MANIFEST);
+
+// Read lazily — `describe.skipIf` still runs the body to register tests, so the
+// read has to be guarded for the bare-branch (no manifest) case.
+const tools: Array<{ name: string; version: string }> = manifestPresent
+  ? JSON.parse(readFileSync(MANIFEST, 'utf8'))
+  : [];
+const codex = tools.find((t) => t.name === '@openai/codex');
+
+// cli-tools.json is a trunk file; on the bare providers branch it isn't present,
+// so skip there. In an installed tree (trunk + this payload) it must carry the
+// pinned @openai/codex entry.
+describe.skipIf(!manifestPresent)('container/cli-tools.json codex CLI install', () => {
+  it('includes the @openai/codex entry', () => {
+    expect(codex).toBeDefined();
+  });
+
+  it('pins it to an exact semver (no latest, no ranges)', () => {
+    expect(codex?.version).toMatch(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/);
+  });
+});
@@ -1,30 +0,0 @@
-// Structural guard for the Codex CLI install in container/Dockerfile.
-//
-// @openai/codex is a CLI *binary* installed via the Dockerfile, not an
-// importable package, so the barrel-driven registration tests cannot see it.
-// This test reads the real Dockerfile and asserts the version ARG and the
-// `pnpm install -g` line for @openai/codex are both present. It goes red if
-// either Dockerfile edit is dropped or drifts.
-//
-// Runs under bun (same suite as the container registration test):
-//   cd container/agent-runner && bun test src/providers/codex-dockerfile.test.ts
-
-import { readFileSync } from 'fs';
-import path from 'path';
-
-import { describe, it, expect } from 'bun:test';
-
-// container/agent-runner/src/providers/ -> container/Dockerfile
-const DOCKERFILE = path.join(import.meta.dir, '..', '..', '..', 'Dockerfile');
-
-describe('container/Dockerfile codex CLI install', () => {
-  const dockerfile = readFileSync(DOCKERFILE, 'utf8');
-
-  it('declares the CODEX_VERSION ARG', () => {
-    expect(dockerfile).toMatch(/ARG\s+CODEX_VERSION=/);
-  });
-
-  it('installs the @openai/codex CLI pinned to that ARG', () => {
-    expect(dockerfile).toMatch(/pnpm install -g\s+"@openai\/codex@\$\{CODEX_VERSION\}"/);
-  });
-});
@@ -5,114 +5,119 @@ description: Add Slack channel integration via Chat SDK.

 # Add Slack Channel

-Adds Slack support via the Chat SDK bridge.
+Adds Slack support via the Chat SDK bridge. NanoClaw doesn't ship channels in
+trunk — this skill copies the Slack adapter in from the `channels` branch.

-## Install
+The mechanical steps under **Apply** carry `nc:` directive fences: an agent
+reads the prose and applies them, and a parser can apply them deterministically
+from the same document. Every directive is idempotent, so the whole skill is
+safe to re-run; anything a parser can't apply falls back to the prose beside it.

-NanoClaw doesn't ship channels in trunk. This skill copies the Slack adapter in from the `channels` branch.
+## Apply

-### Pre-flight (idempotent)
+### 1. Copy the adapter and its registration test

-Skip to **Credentials** if all of these are already in place:
+Fetch the `channels` branch and copy the Slack adapter and its registration test
+into `src/channels/` (overwrite — the branch is canonical):

- `src/channels/slack.ts` exists
- `src/channels/slack-registration.test.ts` exists
- `src/channels/index.ts` contains `import './slack.js';`
- `@chat-adapter/slack` is listed in `package.json` dependencies
-
-Otherwise continue. Every step below is safe to re-run.
-
-### 1. Fetch the channels branch
-
-```bash
-git fetch origin channels
+```nc:copy from-branch:channels
+src/channels/slack.ts
+src/channels/slack-registration.test.ts
 ```

-### 2. Copy the adapter and its registration test
+### 2. Register the adapter

-```bash
-git show origin/channels:src/channels/slack.ts                 > src/channels/slack.ts
-git show origin/channels:src/channels/slack-registration.test.ts > src/channels/slack-registration.test.ts
-```
+Append the self-registration import to the channel barrel (skipped if the line
+is already present). This one line is the skill's only reach-in into core:

-### 3. Append the self-registration import
-
-Append to `src/channels/index.ts` (skip if the line is already present):
-
-```typescript
+```nc:append to:src/channels/index.ts
 import './slack.js';
 ```

-### 4. Install the adapter package (pinned)
+### 3. Install the adapter package

-```bash
-pnpm install @chat-adapter/slack@4.27.0
+Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
+
+```nc:dep
+@chat-adapter/slack@4.26.0
 ```

-### 5. Build and validate
+### 4. Build and validate

-```bash
+Build first: it guards the typed `createChatSdkBridge(...)` core call and proves
+the dependency is installed. Then run the one integration test.
+
+```nc:run effect:build
 pnpm run build
+```
+```nc:run effect:test
 pnpm exec vitest run src/channels/slack-registration.test.ts
 ```

-Both must be clean before proceeding. `slack-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `slack`. It goes red if the `import './slack.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/slack` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.
-
-End-to-end message delivery against a real Slack workspace is verified manually once the service is running — see Next Steps and the webhook setup above.
+`slack-registration.test.ts` imports the real channel barrel and asserts the
+registry contains `slack`. It goes red if the import line is deleted or drifts,
+if the barrel fails to evaluate, or if `@chat-adapter/slack` isn't installed (the
+import throws) — so it also covers the dependency from step 3. End-to-end
+delivery against a real workspace is verified manually once the service runs.

 ## Credentials

-### Create Slack App
+Slack app setup is human and interactive — these steps are prose, not directives
+(no parser can click through the Slack UI). A recipe rebuild produces a
+compiling, registered adapter that cannot receive a message until they're done.

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

 ### Enable DMs

-6. Go to **App Home** and enable the **Messages Tab**
-7. Check **"Allow users to send Slash commands and messages from the messages tab"**
+6. **App Home** → enable the **Messages Tab**.
+7. Check **"Allow users to send Slash commands and messages from the messages tab."**

-### Event Subscriptions
+### Event Subscriptions & Interactivity

-8. Go to **Event Subscriptions** and toggle **Enable Events**
-9. Set the **Request URL** to `https://your-domain/webhook/slack` — Slack will send a verification challenge; it must pass before you can save
-10. Under **Subscribe to bot events**, add:
-    - `message.channels`, `message.groups`, `message.im`, `app_mention`
-11. Click **Save Changes**
+8. **Event Subscriptions** → **Enable Events**. Set the **Request URL** to your public `https://your-domain/webhook/slack` (see Webhook server); Slack sends a challenge that must pass before you can save.
+9. Under **Subscribe to bot events**, add `message.channels`, `message.groups`, `message.im`, `app_mention`. **Save Changes**.
+10. **Interactivity & Shortcuts** → toggle **Interactivity** on, set the same Request URL, **Save Changes**, then **reinstall** the app when Slack prompts.

-### Interactivity
+### Store the credentials

-12. Go to **Interactivity & Shortcuts** and toggle **Interactivity** on
-13. Set the **Request URL** to the same `https://your-domain/webhook/slack`
-14. Click **Save Changes**
-15. Slack will show a banner asking you to **reinstall the app** — click it to apply the new settings
+Capture the two values, then write them. `prompt` only *asks* and binds the
+answer to a name; a separate directive consumes it — so the same prompts could
+feed `ncl` or the OneCLI vault instead of `.env` by swapping only the consumer.
+Here they go to `.env` (set-if-absent — a value you've already filled in is
+never overwritten) and sync to the container:

-### Configure environment
-
-Add to `.env`:
-
-```bash
-SLACK_BOT_TOKEN=xoxb-your-bot-token
-SLACK_SIGNING_SECRET=your-signing-secret
+```nc:prompt bot_token secret
+Paste the Bot User OAuth Token — OAuth & Permissions, starts with `xoxb-`.
+```
+```nc:prompt signing_secret secret
+Paste the Signing Secret — Basic Information.
+```
+```nc:env-set
+SLACK_BOT_TOKEN={{bot_token}}
+SLACK_SIGNING_SECRET={{signing_secret}}
+```
+```nc:env-sync
 ```
-
-Sync to container: `mkdir -p data/env && cp .env data/env/env`

 ### Webhook server

-The Chat SDK bridge automatically starts a shared webhook server on port 3000 (configurable via `WEBHOOK_PORT` env var). The server handles `/webhook/slack` for Slack and other webhook-based adapters. This port must be publicly reachable from the internet for Slack to deliver events.
-
-If running locally, discuss options for exposing the server — e.g. ngrok (`ngrok http 3000`), Cloudflare Tunnel, or a reverse proxy on a VPS. The resulting public URL becomes the base for `https://your-domain/webhook/slack`.
+The Chat SDK bridge automatically starts a shared webhook server on port 3000
+(`WEBHOOK_PORT` to change it), handling `/webhook/slack`. This port must be
+publicly reachable for Slack to deliver events. Running locally, expose it with
+ngrok (`ngrok http 3000`), a Cloudflare Tunnel, or a reverse proxy on a VPS —
+the resulting public URL is the base for the Request URL above.

 ## Next Steps

-If you're in the middle of `/setup`, return to the setup flow now.
-
-Otherwise, run `/manage-channels` to wire this channel to an agent group.
+If you're in the middle of `/setup`, return to the setup flow now. Otherwise run
+`/manage-channels` to wire this channel to an agent group.

 ## Channel Info

@@ -71,6 +71,8 @@ Parse the `PAIR_TELEGRAM_ISSUED` status block for `CODE` and follow the `REMINDE

 ## 4. Run the init script

+First, pick the agent provider. Read `src/providers/index.ts` and collect the installed providers from its `import './<name>.js';` lines — `claude` is always available as the built-in default. If a non-default provider is installed (e.g. codex), ask the user which one this agent should run on; if only claude is available, skip the question and omit the flag.
+
 ```bash
 npx tsx scripts/init-first-agent.ts \
  --channel "${CHANNEL}" \
@@ -80,7 +82,7 @@ npx tsx scripts/init-first-agent.ts \
  --agent-name "${AGENT_NAME}"
 ```

-Add `--welcome "System instruction: ..."` to override the default welcome prompt.
+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 script:
 1. Upserts the `users` row and grants `owner` role if no owner exists.
@@ -67,6 +67,8 @@ 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.
+
 For separate agents, also ask for a folder name and optionally a different assistant name.

 ## Add Channel Group
@@ -0,0 +1,50 @@
+---
+name: migrate-memory
+description: Carry an agent group's memory across a provider switch, in either direction (e.g. Claude ↔ Codex, or any provider to/from another). Run after the operator switches a group's provider with `ncl groups config update --provider`. The coding agent reads the source provider's memory store, distills it into the target provider's store, and restarts the group. Triggers on "migrate memory", "carry memory over", "the agent forgot everything after the switch".
+---
+
+# Migrate memory across a provider switch
+
+NanoClaw does not migrate memory at runtime — each provider keeps its own store, and carrying content across is the operator's move, executed by you (the coding agent). This skill is the whole mechanism: read the source store, **infer** what is durable, write it into the target store, restart.
+
+You translate between **store shapes**, not provider names. There are two:
+
+- **Flat file** — `CLAUDE.local.md` at the group workspace root (the Claude provider; may reference satellite files in the workspace).
+- **Scaffold tree** — `memory/` (any provider with `usesMemoryScaffold`, e.g. Codex). `memory/index.md` is the index; durable notes live under `memory/memories/`; `memory/memories/imported-agent-memory.md` is the conventional landing file for imported memory.
+
+A switch only needs migration when it **crosses shapes**. Two providers that both use the scaffold share the same `memory/` tree, so switching between them carries nothing — the memory is already there. The work is always one of: flat → scaffold, or scaffold → flat.
+
+Principles: **copy, never move** (the source store stays intact — it IS the rollback), **idempotent** (re-running must not duplicate), **distill, don't dump** (you are the inference step: keep identity/seed instructions, user preferences, durable facts; drop conversational residue).
+
+## Step 1: Identify the group, both providers, and the direction
+
+- `ncl groups list`, then `ncl groups config get --id <group-id>` — note the current (target) `provider`. Ask the operator which group, and which provider it switched *from*, if either is ambiguous.
+- Map each provider to its store shape (flat `CLAUDE.local.md` vs `memory/` scaffold), then inspect `groups/<folder>/`:
+  - **Same shape on both sides** (e.g. scaffold → scaffold) → the store is shared; nothing to migrate. Tell the operator and stop.
+  - **Flat → scaffold** (source has `CLAUDE.local.md` content, target uses the scaffold) → Step 2.
+  - **Scaffold → flat** (source has a `memory/` tree, target is Claude) → Step 3.
+  - Source missing or empty → nothing to migrate; tell the operator and stop.
+
+## Step 2: flat → scaffold (`CLAUDE.local.md` → `memory/`)
+
+1. Read `groups/<folder>/CLAUDE.local.md` and any workspace files it references.
+2. If `memory/memories/imported-agent-memory.md` already exists, a previous import happened — show the operator what's there and ask before overwriting; integrate only what's new.
+3. Distill the content into `groups/<folder>/memory/memories/imported-agent-memory.md` (create the directories if missing — the container scaffolds the rest of the tree at boot and never clobbers your files). Lead with anything that defines who the agent is or how it must behave; references to satellite files keep their workspace-root paths.
+4. If `memory/index.md` exists, add the following: `- [Imported agent memory](memories/imported-agent-memory.md) — seed instructions and memory carried over from a previous provider. Read it first and treat it as binding; it may define who you are and how to behave. Integrate its facts into your memory as you work; never modify files that belong to another provider's memory system.`
+5. Leave the source store exactly as it is.
+
+## Step 3: scaffold → flat (`memory/` → `CLAUDE.local.md`)
+
+1. Read `memory/index.md`, then the files it points to under `memory/memories/` (and `memory/data/` where durable).
+2. Integrate the durable facts into `groups/<folder>/CLAUDE.local.md` under a clearly marked section (e.g. `## Imported from memory/ (<date>)`), deduplicating against what's already there. If the section already exists, update it instead of appending a second one.
+3. Leave the source store exactly as it is.
+
+## Step 4: Restart and verify
+
+```bash
+ncl groups restart --id <group-id>
+```
+
+Tell the operator to send the group a quick test message that depends on a migrated fact (a preference, a project name). If the agent doesn't know it, re-check that the target file landed in the right group folder.
+
+Note: switching the provider is an operator action — `ncl groups config update --id <group-id> --provider <name>` from the host. See [docs/provider-migration.md](../../../docs/provider-migration.md) for what carries over automatically.
@@ -2,6 +2,17 @@

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

+## [Unreleased]
+
+- [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 `onecli` setup step enforces them. **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.
+- **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.
+- **Slash commands now interrupt an in-flight turn.** A runner-handled command (`/clear`, `/compact`, `/cost`, …) arriving mid-turn aborts the active stream and runs immediately instead of waiting out the turn.
+
 ## [2.1.0] - 2026-06-07

 - [BREAKING] **Startup now requires an upgrade marker.** The host refuses to boot unless `data/upgrade-state.json` records that this install reached the current version through a sanctioned path (`/setup`, `/update-nanoclaw`, `/migrate-nanoclaw`). After this update completes — and before restarting the service — stamp the marker by running `pnpm exec tsx scripts/upgrade-state.ts set`. If the host has already tripped on restart with "update did not go through the supported path", that same command clears it. See [docs/upgrade-recovery.md](docs/upgrade-recovery.md).
@@ -69,8 +69,8 @@ For ad-hoc queries from skills or scripts, use the in-tree wrapper rather than t
 | `src/modules/permissions/access.ts` | `canAccessAgentGroup` — owner / global admin / scoped admin / member resolution against `user_roles` + `agent_group_members` |
 | `src/modules/approvals/primitive.ts` | `pickApprover`, `pickApprovalDelivery`, `requestApproval`, approval-handler registry |
 | `src/command-gate.ts` | Router-side admin command gate — queries `user_roles` directly (no env var, no container-side check) |
-| `src/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |
-| `src/user-dm.ts` | Cold-DM resolution + `user_dms` cache |
+| `src/modules/approvals/onecli-approvals.ts` | OneCLI credentialed-action approval bridge |
+| `src/modules/permissions/user-dm.ts` | Cold-DM resolution + `user_dms` cache |
 | `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills, agent-runner-src overlay) |
 | `src/db/container-configs.ts` | CRUD for `container_configs` table (per-group container runtime config) |
 | `src/backfill-container-configs.ts` | Migrates legacy `container.json` files into the DB on startup |
@@ -152,7 +152,7 @@ Key files: `src/container-restart.ts`, `src/container-runner.ts` (`killContainer

 ## Secrets / Credentials / OneCLI

-API keys, OAuth tokens, and auth credentials are managed by the OneCLI gateway. Secrets are injected into per-agent containers at request time — none are passed in env vars or through chat context. The container agent sees this via the `onecli-gateway` container skill (`container/skills/onecli-gateway/SKILL.md`), which teaches it how the proxy works, how to handle auth errors, and to never ask for raw credentials. Host-side wiring: `src/onecli-approvals.ts`, `ensureAgent()` in `container-runner.ts`. Run `onecli --help`.
+API keys, OAuth tokens, and auth credentials are managed by the OneCLI gateway. Secrets are injected into per-agent containers at request time — none are passed in env vars or through chat context. The container agent sees this via the `onecli-gateway` container skill (`container/skills/onecli-gateway/SKILL.md`), which teaches it how the proxy works, how to handle auth errors, and to never ask for raw credentials. Host-side wiring: `src/modules/approvals/onecli-approvals.ts`, `ensureAgent()` in `container-runner.ts`. Run `onecli --help`.

 ### Secret modes

@@ -193,6 +193,7 @@ Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxono
 | `/debug` | Container issues, logs, troubleshooting |
 | `/update-nanoclaw` | Bring upstream updates into a customized install |
 | `/init-onecli` | Install OneCLI Agent Vault and migrate `.env` credentials |
+| `/migrate-memory` | Carry a group's agent memory across a provider switch (operator-run, both directions) |

 ## Contributing

@@ -275,6 +276,7 @@ This project uses pnpm with `minimumReleaseAge: 4320` (3 days) in `pnpm-workspac
 | [docs/build-and-runtime.md](docs/build-and-runtime.md) | Runtime split (Node host + Bun container), lockfiles, image build surface, CI, key invariants |
 | [docs/v1-to-v2-changes.md](docs/v1-to-v2-changes.md) | v1→v2 architecture diff — vocabulary for where v1 things moved |
 | [docs/migration-dev.md](docs/migration-dev.md) | Migration development guide — testing, debugging, dev loop |
+| [docs/provider-migration.md](docs/provider-migration.md) | Switching a live agent group between providers (e.g. Claude → Codex) — what carries over, rollback |
 | [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 |
@@ -19,6 +19,13 @@

 **Not accepted:** Features, capabilities, compatibility, enhancements. These should be skills.

+## Breaking Changes
+
+Breaking changes are allowed; **silent** ones are not. NanoClaw does not migrate user installs at runtime — the user's coding agent is the migrator, so every breaking change must ship a migration path that agent can execute without a human reverse-engineering the diff:
+
+1. **Every `[BREAKING]` CHANGELOG entry must reference its migration path** — either a skill to run (`Run /<skill-name> to <action>`) or a `docs/` page covering **detect / why / fix / verify / rollback** (see [docs/onecli-upgrades.md](docs/onecli-upgrades.md) for the shape). `/update-nanoclaw` surfaces these entries after every update and walks the user through them.
+2. **If the change moves an external component's sanctioned version** (gateway, pinned CLI binary, …), update its pin in [`versions.json`](versions.json). The changelog stays human-narrative; `versions.json` is the machine-checkable signal — `/update-nanoclaw` diffs it across the update and routes the user to the linked doc for any pin that moved.
+
 ## Skills

 NanoClaw uses [Claude Code skills](https://code.claude.com/docs/en/skills) — markdown files with optional supporting files that teach Claude how to do something. There are four types of skills in NanoClaw, each serving a different purpose.
@@ -16,12 +16,11 @@ FROM node:22-slim
 # CJK fonts add ~200MB. Opt in only if you render Chinese/Japanese/Korean text.
 ARG INSTALL_CJK_FONTS=false

-# Pin CLI versions for reproducibility. Bump deliberately — unpinned installs
-# mean every rebuild silently picks up the latest and can break in lockstep
-# across all users.
-ARG CLAUDE_CODE_VERSION=2.1.170
-ARG AGENT_BROWSER_VERSION=latest
-ARG VERCEL_VERSION=52.2.1
+# Pin versions for reproducibility. Bump deliberately — unpinned installs mean
+# every rebuild silently picks up the latest and can break in lockstep across
+# all users. The global Node CLIs (claude-code, agent-browser, vercel) are
+# pinned in cli-tools.json so a skill can add one with a json-merge; Bun (the
+# runtime) is pinned here because it installs from a different source.
 ARG BUN_VERSION=1.3.12

 # ---- System dependencies -----------------------------------------------------
@@ -99,16 +98,13 @@ ENV PATH="$PNPM_HOME:$PATH"
 ARG PNPM_VERSION=10.33.0
 RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate

+# Global Node CLIs the agent invokes at runtime live in cli-tools.json so a
+# skill can add one with a json-merge instead of editing this Dockerfile.
+# install-cli-tools.sh installs each via pnpm (pinned), writing the per-tool
+# only-built-dependencies opt-ins it reads from the manifest.
+COPY cli-tools.json install-cli-tools.sh /tmp/
 RUN --mount=type=cache,target=/root/.cache/pnpm \
-    echo "only-built-dependencies[]=agent-browser" > /root/.npmrc && \
-    echo "only-built-dependencies[]=@anthropic-ai/claude-code" >> /root/.npmrc && \
-    pnpm install -g "vercel@${VERCEL_VERSION}"
-
-RUN --mount=type=cache,target=/root/.cache/pnpm \
-    pnpm install -g "agent-browser@${AGENT_BROWSER_VERSION}"
-
-RUN --mount=type=cache,target=/root/.cache/pnpm \
-    pnpm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+    sh /tmp/install-cli-tools.sh /tmp/cli-tools.json

 # ---- ncl CLI wrapper ----------------------------------------------------------
 # Actual script lives in the mounted source at /app/src/cli/ncl.ts.
@@ -27,6 +27,7 @@ import { fileURLToPath } from 'url';

 import { loadConfig } from './config.js';
 import { buildSystemPromptAddendum } from './destinations.js';
+import { ensureMemoryScaffold } from './memory-scaffold.js';
 // Providers barrel — each enabled provider self-registers on import.
 // Provider skills append imports to providers/index.ts.
 import './providers/index.js';
@@ -95,6 +96,12 @@ async function main(): Promise<void> {
    effort: config.effort,
  });

+  // Providers that lack native memory opt in via `usesMemoryScaffold`; for them
+  // the runner creates a persistent memory/ tree in its host-backed workspace at
+  // boot (idempotent). Default off — the trunk default (Claude) omits the flag
+  // and keeps its native memory untouched.
+  if (provider.usesMemoryScaffold) ensureMemoryScaffold();
+
  await runPollLoop({
    provider,
    providerName,
@@ -5,6 +5,7 @@ import { getUndeliveredMessages } from './db/messages-out.js';
 import { getPendingMessages } from './db/messages-in.js';
 import { getContinuation, setContinuation } from './db/session-state.js';
 import { MockProvider } from './providers/mock.js';
+import type { ProviderExchange } from './providers/types.js';
 import { runPollLoop } from './poll-loop.js';

 beforeEach(() => {
@@ -304,6 +305,7 @@ async function runPollLoopWithTimeout(provider: MockProvider, signal: AbortSigna
      provider,
      providerName: 'mock',
      cwd: '/tmp',
+      signal,
    }),
    new Promise<void>((_, reject) => {
      signal.addEventListener('abort', () => reject(new Error('aborted')));
@@ -324,6 +326,86 @@ function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
 }

+describe('poll loop — exchange hook (onExchangeComplete)', () => {
+  // A provider that declares the per-exchange hook. The hook call is the
+  // wiring under test — these tests go red if the poll-loop seam is severed.
+  // What the provider DOES with an exchange (e.g. write markdown into
+  // conversations/) ships with the provider, not the runner.
+  class HookedMockProvider extends MockProvider {
+    readonly exchanges: ProviderExchange[] = [];
+    onExchangeComplete(exchange: ProviderExchange): void {
+      this.exchanges.push(exchange);
+    }
+  }
+
+  it('reports each exchange to a provider that declares the hook', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'please archive this' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new HookedMockProvider({}, () => '<message to="discord-test">archived answer</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => provider.exchanges.length > 0, 2000);
+    controller.abort();
+
+    expect(provider.exchanges.length).toBe(1);
+    const exchange = provider.exchanges[0];
+    expect(exchange.prompt).toContain('please archive this');
+    expect(exchange.result).toContain('archived answer');
+    expect(exchange.continuation).toStartWith('mock-session-');
+    expect(exchange.status).toBe('completed');
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('does not report the internal wrapping-retry nudge as a user prompt', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'wrap this later' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    let calls = 0;
+    const provider = new HookedMockProvider({}, () => {
+      calls += 1;
+      // First result is unwrapped (triggers the retry nudge), second is wrapped.
+      return calls === 1 ? 'unwrapped text' : '<message to="discord-test">wrapped now</message>';
+    });
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 3000);
+
+    await waitFor(() => provider.exchanges.length >= 2, 3000);
+    controller.abort();
+
+    // Both exchanges attribute themselves to the real user prompt, never the nudge.
+    for (const exchange of provider.exchanges) {
+      expect(exchange.prompt).not.toContain('Your response was not delivered');
+      expect(exchange.prompt).toContain('wrap this later');
+    }
+    expect(provider.exchanges.map((e) => e.status)).toEqual(['undelivered', 'completed']);
+
+    await loopPromise.catch(() => {});
+  });
+
+  it('a throwing hook never breaks delivery', async () => {
+    insertMessage('m1', { sender: 'Alice', text: 'still deliver this' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    class ThrowingHookProvider extends MockProvider {
+      onExchangeComplete(): void {
+        throw new Error('hook exploded');
+      }
+    }
+    const provider = new ThrowingHookProvider({}, () => '<message to="discord-test">delivered anyway</message>');
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider, controller.signal, 2000);
+
+    await waitFor(() => getUndeliveredMessages().length > 0, 2000);
+    controller.abort();
+
+    const out = getUndeliveredMessages();
+    expect(out.length).toBe(1);
+    expect(out[0].content).toContain('delivered anyway');
+
+    await loopPromise.catch(() => {});
+  });
+});
+
 describe('poll loop — provider error recovery', () => {
  it('writes error to outbound and continues loop on provider throw', async () => {
    insertMessage('m1', { sender: 'Alice', text: 'trigger error' }, { platformId: 'chan-1', channelType: 'discord' });
@@ -462,3 +544,76 @@ class InvalidSessionProvider {
    };
  }
 }
+
+describe('poll loop — slash command during active query', () => {
+  it('aborts the active query when /clear arrives as a follow-up', async () => {
+    insertMessage('m-active', { sender: 'Alice', text: 'long running request' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    const provider = new BlockingProvider();
+    const controller = new AbortController();
+    const loopPromise = runPollLoopWithTimeout(provider as unknown as MockProvider, controller.signal, 3000);
+
+    await waitFor(() => provider.queries === 1, 2000);
+    insertMessage('m-clear-active', { sender: 'Alice', text: '/clear' }, { platformId: 'chan-1', channelType: 'discord' });
+
+    await waitFor(() => provider.aborts === 1, 2000);
+    await waitFor(
+      () => getUndeliveredMessages().some((msg) => JSON.parse(msg.content).text === 'Session cleared.'),
+      2000,
+    );
+    controller.abort();
+
+    expect(provider.ends).toBe(0);
+    expect(getContinuation('mock')).toBeUndefined();
+    expect(getPendingMessages()).toHaveLength(0);
+
+    await loopPromise.catch(() => {});
+  });
+});
+
+/**
+ * Provider whose query never completes until ended/aborted — for testing how
+ * the loop interrupts an active stream.
+ */
+class BlockingProvider {
+  readonly supportsNativeSlashCommands = false;
+  queries = 0;
+  aborts = 0;
+  ends = 0;
+
+  isSessionInvalid(): boolean {
+    return false;
+  }
+
+  query() {
+    const owner = this;
+    this.queries += 1;
+    let wake: (() => void) | null = null;
+    let ended = false;
+    let aborted = false;
+
+    return {
+      push() {},
+      end: () => {
+        owner.ends += 1;
+        ended = true;
+        wake?.();
+      },
+      abort: () => {
+        owner.aborts += 1;
+        aborted = true;
+        wake?.();
+      },
+      events: (async function* () {
+        yield { type: 'activity' as const };
+        yield { type: 'init' as const, continuation: 'blocking-session' };
+        while (!ended && !aborted) {
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+          });
+          wake = null;
+        }
+      })(),
+    };
+  }
+}
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { ensureMemoryScaffold } from './memory-scaffold.js';
+
+describe('ensureMemoryScaffold', () => {
+  it('deterministically creates the memory tree', () => {
+    const base = fs.mkdtempSync(path.join(os.tmpdir(), 'nanoclaw-mem-'));
+    try {
+      ensureMemoryScaffold(base);
+
+      expect(fs.existsSync(path.join(base, 'memory', 'index.md'))).toBe(true);
+      expect(fs.existsSync(path.join(base, 'memory', 'system', 'definition.md'))).toBe(true);
+      expect(fs.existsSync(path.join(base, 'memory', 'memories'))).toBe(true);
+      expect(fs.existsSync(path.join(base, 'memory', 'data'))).toBe(true);
+    } finally {
+      fs.rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  it('never touches workspace memory it did not create — CLAUDE.local.md stays untouched', () => {
+    const base = fs.mkdtempSync(path.join(os.tmpdir(), 'nanoclaw-mem-'));
+    try {
+      fs.writeFileSync(path.join(base, 'CLAUDE.local.md'), '# group memory\nuser prefers terse replies\n');
+
+      ensureMemoryScaffold(base);
+
+      // Migration between memory stores is the operator's move (/migrate-memory),
+      // never a boot side effect.
+      expect(fs.existsSync(path.join(base, 'memory', 'memories', 'imported-agent-memory.md'))).toBe(false);
+      expect(fs.readFileSync(path.join(base, 'CLAUDE.local.md'), 'utf-8')).toContain('terse replies');
+    } finally {
+      fs.rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  it('is idempotent and never clobbers the agent edits', () => {
+    const base = fs.mkdtempSync(path.join(os.tmpdir(), 'nanoclaw-mem-'));
+    try {
+      ensureMemoryScaffold(base);
+      const indexFile = path.join(base, 'memory', 'index.md');
+      fs.writeFileSync(indexFile, '# my own index\n');
+
+      ensureMemoryScaffold(base);
+
+      expect(fs.readFileSync(indexFile, 'utf-8')).toBe('# my own index\n');
+    } finally {
+      fs.rmSync(base, { recursive: true, force: true });
+    }
+  });
+});
@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Create the agent's persistent memory scaffold, container-side, at boot.
+ *
+ * The runner owns its own workspace: it writes the memory tree straight into
+ * `/workspace/agent` (the host-backed, RW group dir, so it persists across the
+ * ephemeral container). No host-side step, nothing mounted in.
+ *
+ * The default `definition.md` / `index.md` live as real markdown templates next
+ * to this module (under `memory-templates/`) — not as strings in code — so the
+ * doctrine is editable as markdown and the agent receives an unescaped copy.
+ * They ship in the mounted `/app/src` tree, so no image change is needed.
+ *
+ * Idempotent — only writes what's missing, so the agent's own edits and
+ * accumulated memory are never clobbered on a later wake. Provider-agnostic:
+ * the runner makes no assumption about which harness is running — a provider
+ * opts in via `usesMemoryScaffold`.
+ */
+const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'memory-templates');
+
+export function ensureMemoryScaffold(baseDir = '/workspace/agent'): void {
+  const memoryDir = path.join(baseDir, 'memory');
+  const systemDir = path.join(memoryDir, 'system');
+
+  for (const dir of [systemDir, path.join(memoryDir, 'memories'), path.join(memoryDir, 'data')]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  copyTemplateIfMissing('definition.md', path.join(systemDir, 'definition.md'));
+  copyTemplateIfMissing('index.md', path.join(memoryDir, 'index.md'));
+}
+
+function copyTemplateIfMissing(template: string, dest: string): void {
+  if (fs.existsSync(dest)) return;
+  fs.copyFileSync(path.join(TEMPLATES_DIR, template), dest);
+}
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+
+// Wiring guard for the memory-scaffold seam: the boot gate in index.ts
+// (`if (provider.usesMemoryScaffold) ensureMemoryScaffold()`) is the seam's
+// single functional reach-in. The unit tests in memory-scaffold.test.ts drive
+// ensureMemoryScaffold directly and stay green if the gate is deleted — this
+// test goes red. main() can't be driven in-process (it reads
+// /workspace/agent/container.json and enters the poll loop), so the guard is
+// structural: gate + import must both be present in the real entry point.
+describe('memory scaffold boot wiring', () => {
+  const indexSrc = fs.readFileSync(path.join(import.meta.dir, 'index.ts'), 'utf-8');
+
+  it('gates the scaffold on the provider capability in main()', () => {
+    expect(indexSrc).toContain('if (provider.usesMemoryScaffold) ensureMemoryScaffold()');
+  });
+
+  it('imports ensureMemoryScaffold from the seam module', () => {
+    expect(indexSrc).toContain("import { ensureMemoryScaffold } from './memory-scaffold.js'");
+  });
+});
@@ -0,0 +1,23 @@
+# Agent Memory System
+
+This editable file defines how your persistent memory works. It is a starting
+point, not a contract — reorganize it as the work demands. If the user or another
+memory system replaces this definition, follow the replacement.
+
+Start every memory task at `memory/index.md`, then follow the narrowest relevant index.
+Treat indexes as core data: keep them accurate and concise.
+Every folder of durable memory has its own `index.md` describing its contents.
+When an index grows past roughly 20 entries, group related items into subfolders,
+and give each new subfolder its own `index.md` linked from the parent.
+
+Use `memory/memories/` for durable facts, project context, people, decisions, and entity notes.
+Use `memory/data/` for structured reference data, datasets, tables, and reusable records.
+Use entity folders for things that matter: projects, people, places, organizations, decisions.
+
+When the user shares something that should survive future turns, store it in the
+smallest useful file; prefer updating an existing file over creating duplicates.
+Write concise, source-aware notes; include dates when timing matters.
+If a fact is corrected, update the memory and keep only useful history.
+When you add, move, or remove memory, update the nearest index.
+Before answering from memory, read the relevant index or file instead of guessing;
+if memory is missing or uncertain, say so and verify when it matters.
@@ -0,0 +1,5 @@
+# Memory Index
+
+- [Memory system definition](system/definition.md)
+- [Memories](memories/) - durable facts, people, projects, decisions
+- [Data](data/) - structured reference data
@@ -14,7 +14,7 @@ import {
  type RoutingContext,
 } from './formatter.js';
 import { isUploadTraceCommand, uploadTrace } from './upload-trace.js';
-import type { AgentProvider, AgentQuery, ProviderEvent } from './providers/types.js';
+import type { AgentProvider, AgentQuery, ProviderEvent, ProviderExchange } from './providers/types.js';

 const POLL_INTERVAL_MS = 1000;
 const ACTIVE_POLL_INTERVAL_MS = 500;
@@ -63,6 +63,12 @@ export interface PollLoopConfig {
  systemContext?: {
    instructions?: string;
  };
+  /**
+   * Optional stop signal. In production the loop runs until the container
+   * dies; tests pass a signal so an abandoned loop actually exits instead of
+   * polling forever and stealing messages from the next test's DB.
+   */
+  signal?: AbortSignal;
 }

 /**
@@ -107,6 +113,7 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
  let pollCount = 0;
  let isFirstPoll = true;
  while (true) {
+    if (config.signal?.aborted) return;
    // Skip system messages — they're responses for MCP tools (e.g., ask_user_question)
    const messages = getPendingMessages(isFirstPoll).filter((m) => m.kind !== 'system');
    isFirstPoll = false;
@@ -232,7 +239,15 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
    // can stamp it on outbound rows — needed for a2a return-path routing.
    setCurrentInReplyTo(routing.inReplyTo);
    try {
-      const result = await processQuery(query, routing, processingIds, config.providerName);
+      const result = await processQuery(
+        query,
+        routing,
+        processingIds,
+        config.providerName,
+        config.provider.onExchangeComplete?.bind(config.provider),
+        prompt,
+        continuation,
+      );
      if (result.continuation && result.continuation !== continuation) {
        continuation = result.continuation;
        setContinuation(config.providerName, continuation);
@@ -313,10 +328,18 @@ async function processQuery(
  routing: RoutingContext,
  initialBatchIds: string[],
  providerName: string,
+  onExchangeComplete: ((exchange: ProviderExchange) => void) | undefined,
+  initialPrompt: string,
+  initialContinuation: string | undefined,
 ): Promise<QueryResult> {
  let queryContinuation: string | undefined;
  let done = false;
  let unwrappedNudged = false;
+  // Prompt queue for the exchange hook — each result event consumes the
+  // oldest unanswered prompt, except a wrapping-retry result, which answers
+  // the same prompt again. Unused (and unmaintained) when the provider
+  // doesn't implement `onExchangeComplete`.
+  const archivePrompts: string[] = [initialPrompt];

  // Concurrent polling: push follow-ups into the active query as they arrive.
  // We do NOT force-end the stream on silence — keeping the query open avoids
@@ -342,13 +365,16 @@ async function processQuery(
        // resume id (fixed at sdkQuery() time); admin/passthrough commands
        // (/compact, /cost, …) only dispatch when they're the first input
        // of a query — pushed mid-stream they arrive as plain text and
-        // the SDK never runs them. End the stream and leave the rows
-        // pending; the outer loop handles them on next iteration via the
-        // canonical command path + formatMessagesWithCommands.
+        // the SDK never runs them. Abort the active stream and leave the
+        // rows pending; the outer loop handles them on next iteration via
+        // the canonical command path + formatMessagesWithCommands. Abort,
+        // not end: end() lets an in-flight turn run to completion, which
+        // can block the command (e.g. /clear during a long task) for as
+        // long as the turn takes.
        if (pending.some((m) => isRunnerCommand(m))) {
-          log('Pending slash command — ending stream so outer loop can process');
+          log('Pending slash command — aborting active stream so outer loop can process');
          endedForCommand = true;
-          query.end();
+          query.abort();
          return;
        }

@@ -393,6 +419,7 @@ async function processQuery(
        log(`Pushing ${keep.length} follow-up message(s) into active query`);
        unwrappedNudged = false;
        query.push(prompt);
+        archivePrompts.push(prompt);
        markCompleted(keptIds);
      } catch (err) {
        // Without this catch the rejection escapes the void IIFE and Node
@@ -456,7 +483,14 @@ async function processQuery(
        markCompleted(initialBatchIds);
        if (event.text) {
          const { hasUnwrapped } = dispatchResultText(event.text, routing);
-          if (hasUnwrapped && !unwrappedNudged) {
+          const willRetryWrapping = hasUnwrapped && !unwrappedNudged;
+          notifyExchangeComplete(onExchangeComplete, {
+            prompt: archivePrompts[0] ?? initialPrompt,
+            result: event.text,
+            continuation: queryContinuation ?? initialContinuation,
+            status: hasUnwrapped ? 'undelivered' : 'completed',
+          });
+          if (willRetryWrapping) {
            unwrappedNudged = true;
            const destinations = getAllDestinations();
            const names = destinations.map((d) => d.name).join(', ');
@@ -467,9 +501,23 @@ async function processQuery(
                `Please re-send your response with the correct wrapping.</system>`,
            );
          }
+          // The wrapping-retry result answers the SAME user prompt — keep it
+          // queued so the retry archives against it, not the nudge text.
+          if (!willRetryWrapping) archivePrompts.shift();
+        } else {
+          archivePrompts.shift();
        }
      }
    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    notifyExchangeComplete(onExchangeComplete, {
+      prompt: archivePrompts[0] ?? initialPrompt,
+      result: `Error: ${errMsg}`,
+      continuation: queryContinuation ?? initialContinuation,
+      status: 'error',
+    });
+    throw err;
  } finally {
    done = true;
    clearInterval(pollHandle);
@@ -478,6 +526,18 @@ async function processQuery(
  return { continuation: queryContinuation };
 }

+function notifyExchangeComplete(
+  hook: ((exchange: ProviderExchange) => void) | undefined,
+  exchange: ProviderExchange,
+): void {
+  if (!hook) return;
+  try {
+    hook(exchange);
+  } catch (err) {
+    log(`onExchangeComplete failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 function handleEvent(event: ProviderEvent, _routing: RoutingContext): void {
  switch (event.type) {
    case 'init':
@@ -6,6 +6,25 @@ export interface AgentProvider {
   */
  readonly supportsNativeSlashCommands: boolean;

+  /**
+   * Optional. When true, the runner scaffolds a persistent `memory/` tree in the
+   * agent's workspace at boot. Providers with their own native memory (e.g.
+   * Claude's `CLAUDE.local.md`) omit this and get nothing — memory is opt-in per
+   * provider, never gated on a provider name.
+   */
+  readonly usesMemoryScaffold?: boolean;
+
+  /**
+   * Optional. Called by the poll-loop after each completed exchange (a
+   * result, a wrapping retry, or an error). Providers whose harness keeps no
+   * on-disk transcript implement this to persist exchanges themselves (e.g.
+   * markdown into the agent's `conversations/` dir); providers that persist
+   * and archive their own transcript (e.g. the Claude Agent SDK's `.jsonl`)
+   * omit it. Best-effort: the loop catches and logs anything it throws. The
+   * implementation lives with the provider, never in the runner.
+   */
+  onExchangeComplete?(exchange: ProviderExchange): void;
+
  /** Start a new query. Returns a handle for streaming input and output. */
  query(input: QueryInput): AgentQuery;

@@ -31,6 +50,16 @@ export interface AgentProvider {
  maybeRotateContinuation?(continuation: string, cwd: string): string | null;
 }

+/** One prompt/result round-trip, as reported to `onExchangeComplete`. */
+export interface ProviderExchange {
+  /** The user prompt this exchange answers (never an internal retry nudge). */
+  prompt: string;
+  result: string | null;
+  /** Continuation/thread id in effect for the exchange, if any. */
+  continuation?: string;
+  status: 'completed' | 'undelivered' | 'error';
+}
+
 /**
 * Options passed to provider constructors. Fields are common to most
 * providers; individual providers may ignore any they don't need.
@@ -0,0 +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 }
+]
@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// Guards the cli-tools.json seam: the global CLIs the agent invokes at runtime
+// are installed from the manifest (a skill adds one with a json-merge), not
+// hand-edited into the Dockerfile. These go red on a bad merge that drops a
+// baseline tool, or on dewiring the Dockerfile / switching the installer off
+// the pnpm supply-chain path.
+const here = dirname(fileURLToPath(import.meta.url));
+const manifest = JSON.parse(readFileSync(join(here, 'cli-tools.json'), 'utf8')) as Array<{
+  name: string;
+  version: string;
+  onlyBuilt?: boolean;
+}>;
+const dockerfile = readFileSync(join(here, 'Dockerfile'), 'utf8');
+const installer = readFileSync(join(here, 'install-cli-tools.sh'), 'utf8');
+
+describe('cli-tools manifest', () => {
+  it('is a non-empty array of { name, version }', () => {
+    expect(Array.isArray(manifest)).toBe(true);
+    expect(manifest.length).toBeGreaterThan(0);
+    for (const tool of manifest) {
+      expect(typeof tool.name).toBe('string');
+      expect(tool.name.length).toBeGreaterThan(0);
+      expect(typeof tool.version).toBe('string');
+      expect(tool.version.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('has unique tool names (json-merge is keyed on name)', () => {
+    const names = manifest.map((t) => t.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it('pins every version to an exact semver (no latest, no ranges — supply-chain policy)', () => {
+    for (const tool of manifest) {
+      expect(tool.version, `${tool.name} must be an exact semver, not "${tool.version}"`).toMatch(
+        /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/,
+      );
+    }
+  });
+
+  it('keeps the baseline CLIs the agent depends on', () => {
+    const names = manifest.map((t) => t.name);
+    for (const required of ['vercel', 'agent-browser', '@anthropic-ai/claude-code']) {
+      expect(names).toContain(required);
+    }
+  });
+
+  it('is wired into the Dockerfile build (COPY manifest + run installer)', () => {
+    expect(dockerfile).toMatch(/COPY cli-tools\.json install-cli-tools\.sh/);
+    expect(dockerfile).toMatch(/install-cli-tools\.sh \/tmp\/cli-tools\.json/);
+  });
+
+  it('installs via pnpm and writes only-built opt-ins (preserves the supply-chain path)', () => {
+    expect(installer).toMatch(/pnpm install -g/);
+    expect(installer).toMatch(/only-built-dependencies\[\]=/);
+  });
+});
@@ -0,0 +1,29 @@
+#!/bin/sh
+# Install the global Node CLIs the agent invokes at runtime, from cli-tools.json.
+#
+# A skill adds a tool by appending a { "name", "version" } entry to that
+# manifest (a json-merge) instead of editing the Dockerfile — the reach-in
+# becomes the safest change shape, deterministic and removable.
+#
+# Every tool is installed via `pnpm install -g`, pinned to an exact version, so
+# the pnpm supply-chain policy still applies. Tools with a native postinstall
+# set "onlyBuilt": true to opt in to running build scripts (pnpm skips them by
+# default). Run as root before `USER node`, so /root/.npmrc is the right home.
+set -eu
+
+MANIFEST="${1:-/tmp/cli-tools.json}"
+
+# Write the per-tool only-built-dependencies opt-ins pnpm reads at install time.
+node -e '
+  const tools = require(process.argv[1]);
+  const optIns = tools.filter((t) => t.onlyBuilt).map((t) => "only-built-dependencies[]=" + t.name);
+  require("fs").writeFileSync("/root/.npmrc", optIns.join("\n") + (optIns.length ? "\n" : ""));
+' "$MANIFEST"
+
+# Install every tool, pinned. name@version specs never contain spaces, so the
+# unquoted expansion word-splits cleanly into positional args.
+# shellcheck disable=SC2046
+set -- $(node -e 'require(process.argv[1]).forEach((t) => console.log(t.name + "@" + t.version))' "$MANIFEST")
+if [ "$#" -gt 0 ]; then
+  pnpm install -g "$@"
+fi
@@ -0,0 +1,83 @@
+# Upgrading the OneCLI gateway
+
+NanoClaw talks to the OneCLI gateway (credential vault + egress proxy) through `@onecli-sh/sdk`. The gateway is an external component with its own release line, so NanoClaw pins the **sanctioned gateway version** in [`versions.json`](../versions.json) under `onecli-gateway`. When an update moves that pin, the gateway must be upgraded — this doc is the migration path. It is written to be handed to a coding agent verbatim: detect → upgrade → verify → rollback.
+
+There is deliberately **no runtime version check, and setup does not migrate the gateway for you**: the gateway is a separate out-of-band component, and the migrator is your coding agent running `/update-nanoclaw` — it diffs `versions.json` across the update and routes you here when the `onecli-gateway` pin moved. (Setup detects a pre-`/v1` gateway and points at this doc, but never upgrades it.) Run the steps below verbatim.
+
+## 1. Detect
+
+Find out what is running and what is required:
+
+```bash
+cat versions.json                                   # the sanctioned pin
+curl -s http://127.0.0.1:10254/api/health           # reports the running gateway version
+curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:10254/v1/health
+```
+
+If the last command prints `404`, the server predates the `/v1` API that `@onecli-sh/sdk` 2.x requires — every SDK call will fail with 404s that look transient but are permanent. If your gateway is remote, substitute its host for `127.0.0.1` (it's in `.env` as `ONECLI_URL` / `NANOCLAW_ONECLI_API_HOST`).
+
+Why gateways fall behind: the OneCLI installer's docker-compose tracks the `latest` image tag, but Docker never re-pulls a tag — the server freezes at whatever `latest` meant on install day.
+
+## 2. Upgrade
+
+The gateway runs as a Docker service in `~/.onecli`. Upgrade just that container to the pinned `onecli-gateway` version — vault data lives in named Docker volumes and survives. This upgrades only the gateway; the CLI binary is pinned separately (see below).
+
+**Local gateway (the common case):**
+
+```bash
+cd ~/.onecli && ONECLI_VERSION=<onecli-gateway pin from versions.json> docker compose pull onecli && docker compose up -d
+```
+
+**Remote gateway** — run the same command on the gateway's host (NanoClaw can't reach it over SSH).
+
+## 3. Verify
+
+Host-side health is necessary but **not sufficient**:
+
+```bash
+curl -s http://127.0.0.1:10254/v1/health     # must return {"status":"ok",...}
+```
+
+**Verify the bind interface (container reachability).** Agent containers reach the gateway over the docker bridge (`host.docker.internal` → e.g. `172.17.0.1`), so a server bound only to `127.0.0.1` boots clean host-side while every credentialed call from containers dies at the proxy:
+
+```bash
+docker run --rm --add-host=host.docker.internal:host-gateway \
+  curlimages/curl -s -o /dev/null -w '%{http_code}' http://host.docker.internal:10254/v1/health
+```
+
+This must print `200`. If it can't connect while the host-side check passed, set the bind address in `~/.onecli/.env` to the docker-bridge IP (or `0.0.0.0` on a host with a closed firewall) and `cd ~/.onecli && docker compose up -d`. Symptom if skipped: host log clean, agents fail all API calls.
+
+Finally, restart the NanoClaw service (per-install names — derive with `setup/lib/install-slug.sh`):
+
+```bash
+# macOS
+source setup/lib/install-slug.sh && launchctl kickstart -k gui/$(id -u)/$(launchd_label)
+# Linux
+source setup/lib/install-slug.sh && systemctl --user restart $(systemd_unit)
+```
+
+## 4. Rollback
+
+```bash
+cd ~/.onecli && ONECLI_VERSION=<old-version> docker compose up -d
+```
+
+If the NanoClaw update itself is being rolled back, also pin `@onecli-sh/sdk` back to its previous version in `package.json` and run `pnpm install`. Vault data is unaffected in both directions.
+
+## The CLI binary (`onecli-cli` pin)
+
+The `onecli` host CLI is pinned the same way, under `onecli-cli` in `versions.json`. Setup installs exactly that version by direct release download — it never resolves "latest". When an update moves this pin, replace the binary with the pinned release:
+
+```bash
+onecli --version                                            # detect: what is installed
+V=<onecli-cli pin from versions.json>
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')                 # darwin | linux
+ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')   # amd64 | arm64
+curl -fsSL -o /tmp/onecli.tgz \
+  "https://github.com/onecli/onecli-cli/releases/download/v${V}/onecli_${V}_${OS}_${ARCH}.tar.gz"
+tar -xzf /tmp/onecli.tgz -C /tmp
+install -m 0755 /tmp/onecli "$(command -v onecli || echo ~/.local/bin/onecli)"
+onecli --version                                            # verify: must match versions.json
+```
+
+To roll back, run the same block after reverting `versions.json` (or checking out the previous NanoClaw version). The CLI is stateless — vault data lives in the gateway, so swapping the binary in either direction loses nothing.
@@ -0,0 +1,44 @@
+# Switching an agent group between providers
+
+How an **operator** moves a live agent group from one agent provider to another (e.g. Claude → Codex) and back. Switching is an operator action: it runs from the host via `ncl groups config update --provider` + restart.
+
+NanoClaw's runtime does not migrate anything when you switch. Provider-neutral state simply stays where it is; provider-specific state (memory, in-flight context) stays with its provider, and carrying memory across is a separate, explicit operator step (`/migrate-memory`, executed by your coding agent).
+
+## Preconditions
+
+1. **The target provider is installed** — run its `/add-<provider>` skill and rebuild the container image (`./container/build.sh`). If the provider isn't installed (or the name is a typo), the container fails at boot and the host surfaces its last words in the logs: look for `Container exited non-zero` with a `stderrTail` like `Unknown provider: codexx. Registered: claude, codex`.
+2. **Auth is configured** — each provider documents its own auth in its install skill (for Codex: a ChatGPT-subscription or API-key secret in the OneCLI vault).
+
+## Switching
+
+```bash
+ncl groups config update --id <group-id> --provider codex
+ncl groups restart --id <group-id>
+```
+
+Sessions resolve their provider at container spawn (`sessions.agent_provider` is only set when you've explicitly pinned a session), so existing sessions pick up the new provider on their next wake.
+
+## What carries over automatically
+
+| State | How |
+|-------|-----|
+| Group identity, wiring, members, roles, destinations | Provider-neutral, in the central DB — untouched |
+| Container config (model aside), skills, MCP servers, packages, mounts, cli_scope | Provider-neutral — untouched |
+| Workspace files (`groups/<folder>/` — notes, data files the agent created) | Same workspace, mounted for every provider |
+| Conversation archives (`conversations/`) | Provider-neutral markdown — readable by the new provider |
+| Agent surfaces (system instructions / project docs) | Composed fresh at every spawn from the same sources — nothing to migrate |
+
+## What does NOT carry over
+
+- **Agent memory.** Each provider keeps its own store: Claude's per-group memory is `CLAUDE.local.md` in the workspace; scaffold providers (e.g. Codex) keep a `memory/` tree. Neither is touched by a switch — the old store sits intact, the new provider starts with its own. To carry memory across, run **`/migrate-memory`**: your coding agent reads the source store, distills it into the target store (copy, never move), and restarts the group. Both directions work.
+- **In-flight conversation context.** Continuations are provider-specific (a Claude SDK session, a Codex thread) and stored in separate per-provider slots — the new provider starts a fresh thread. The old slot is kept, not deleted. Recent context is recoverable from `conversations/` archives.
+- **Provider state dirs** (`.claude-shared/`, `.codex-shared/`). Each provider keeps its own; they sit idle while unused and are reused if you switch back.
+
+## Rolling back
+
+```bash
+ncl groups config update --id <group-id> --provider claude
+ncl groups restart --id <group-id>
+```
+
+Rollback is lossless by construction: the per-provider continuation slot means Claude resumes its previous session (subject to normal transcript-rotation age limits), and `CLAUDE.local.md` was never modified by the switch. Memory written **while on the other provider** lives in that provider's store — run `/migrate-memory` again if you want it carried back.
@@ -1,6 +1,6 @@
 {
  "name": "nanoclaw",
-  "version": "2.1.10",
+  "version": "2.1.16",
  "description": "Personal Claude assistant. Lightweight, secure, customizable.",
  "type": "module",
  "packageManager": "pnpm@10.33.0",
@@ -30,7 +30,7 @@
  "dependencies": {
    "@clack/core": "^1.2.0",
    "@clack/prompts": "^1.2.0",
-    "@onecli-sh/sdk": "^0.5.0",
+    "@onecli-sh/sdk": "2.2.1",
    "better-sqlite3": "11.10.0",
    "chat": "^4.24.0",
    "cron-parser": "5.5.0",
@@ -15,8 +15,8 @@ importers:
        specifier: ^1.2.0
        version: 1.2.0
      '@onecli-sh/sdk':
-        specifier: ^0.5.0
-        version: 0.5.0
+        specifier: 2.2.1
+        version: 2.2.1
      better-sqlite3:
        specifier: 11.10.0
        version: 11.10.0
@@ -303,8 +303,8 @@ packages:
      '@emnapi/core': ^1.7.1
      '@emnapi/runtime': ^1.7.1

-  '@onecli-sh/sdk@0.5.0':
-    resolution: {integrity: sha512-oe5Yx9o98v6N1PgzcCR7nULHHqcqKWNJIDOHGOSNX+l20mLlZpFUqfKPeFmsojBNRQMoqbvZQKUlFMp6gVuYBA==}
+  '@onecli-sh/sdk@2.2.1':
+    resolution: {integrity: sha512-q2mCW4ZsARlLEoTxz/P0NQ4MiCh7Z2n28pxkSc7srS+tozyw40PdTnWYW7NI8hfSYplZTx5856Adq1iPi4KN3Q==}
    engines: {node: '>=20'}

  '@oxc-project/types@0.124.0':
@@ -1665,7 +1665,7 @@ snapshots:
      '@tybys/wasm-util': 0.10.1
    optional: true

-  '@onecli-sh/sdk@0.5.0': {}
+  '@onecli-sh/sdk@2.2.1': {}

  '@oxc-project/types@0.124.0': {}

@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="190k tokens, 95% of context window">
-  <title>190k tokens, 95% 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="195k tokens, 98% of context window">
+  <title>195k tokens, 98% 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">190k</text>
-        <text x="71" y="14">190k</text>
+        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">195k</text>
+        <text x="71" y="14">195k</text>
      </g>
    </g>
  </a>
@@ -21,6 +21,7 @@ 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,
@@ -102,6 +103,7 @@ async function main(): Promise<void> {

  // 2. Agent group + filesystem.
  const folder = args.folder || `cli-with-${normalizeName(args.displayName)}`;
+  const pickedProvider = process.env.NANOCLAW_PICKED_PROVIDER?.trim().toLowerCase();
  let ag: AgentGroup | undefined = getAgentGroupByFolder(folder);
  if (!ag) {
    const agId = generateId('ag');
@@ -123,6 +125,10 @@ async function main(): Promise<void> {
      `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.',
  });
+  // 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);
@@ -30,10 +30,11 @@
 * For direct-addressable channels (telegram, whatsapp, etc.), --platform-id
 * is typically the same as the handle in --user-id, with the channel prefix.
 */
+import fs from 'fs';
 import net from 'net';
 import path from 'path';

-import { DATA_DIR } from '../src/config.js';
+import { DATA_DIR, GROUPS_DIR } from '../src/config.js';
 import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
 import { initDb } from '../src/db/connection.js';
 import {
@@ -47,8 +48,7 @@ import { normalizeName } from '../src/modules/agent-to-agent/db/agent-destinatio
 import { addMember } from '../src/modules/permissions/db/agent-group-members.js';
 import { getUserRoles, grantRole } from '../src/modules/permissions/db/user-roles.js';
 import { upsertUser } from '../src/modules/permissions/db/users.js';
-import { updateContainerConfigScalars } from '../src/db/container-configs.js';
-import { initGroupFilesystem } from '../src/group-init.js';
+import { ensureContainerConfig, updateContainerConfigScalars } from '../src/db/container-configs.js';
 import { namespacedPlatformId } from '../src/platform-id.js';
 import type { AgentGroup, MessagingGroup } from '../src/types.js';

@@ -189,6 +189,7 @@ async function main(): Promise<void> {

  // 2. Agent group + filesystem.
  const folder = `dm-with-${normalizeName(args.displayName)}`;
+  const pickedProvider = process.env.NANOCLAW_PICKED_PROVIDER?.trim().toLowerCase();
  let ag: AgentGroup | undefined = getAgentGroupByFolder(folder);
  if (!ag) {
    const agId = generateId('ag');
@@ -204,12 +205,23 @@ async function main(): Promise<void> {
  } else {
    console.log(`Reusing agent group: ${ag.id} (${folder})`);
  }
-  initGroupFilesystem(ag, {
-    instructions:
-      `# ${args.agentName}\n\n` +
+  // 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 });
+  }
+  const groupDir = path.resolve(GROUPS_DIR, folder);
+  fs.mkdirSync(groupDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(groupDir, '.seed.md'),
+    `# ${args.agentName}\n\n` +
      `You are ${args.agentName}, a personal NanoClaw agent for ${args.displayName}. ` +
-      'When the user first reaches out (or you receive a system welcome prompt), introduce yourself briefly and invite them to chat. Keep replies concise.',
-  });
+      'When the user first reaches out (or you receive a system welcome prompt), introduce yourself briefly and invite them to chat. Keep replies concise.\n',
+  );

  // 2b. Assign the user a role for this agent group. The caller picks via
  // --role; the channel drivers default to 'owner' for the self-host case.
@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { applySkill, removeSkill, planSkill, type Prompter } from './skill-apply.js';
+
+// A synthetic skill exercising the fs handlers for real (no network), plus one
+// directive the engine can't handle — to prove it bounces to an agent, not abort.
+const SKILL = `# demo skill
+
+## Copy the file
+\`\`\`nc:copy
+resources/sample.ts -> src/sample.ts
+\`\`\`
+
+## Register it
+\`\`\`nc:append to:src/barrel.ts
+import './sample.js';
+\`\`\`
+
+## Capture and store a secret
+\`\`\`nc:prompt token secret
+Paste the demo token.
+\`\`\`
+\`\`\`nc:env-set
+DEMO_TOKEN={{token}}
+\`\`\`
+
+## A step the engine can't do deterministically
+Hand-edit the scheduler to register the demo hook.
+\`\`\`nc:patch-scheduler
+register demo
+\`\`\`
+`;
+
+let root: string;
+let skillDir: string;
+const headless = (vals: Record<string, string>): Prompter => ({ async ask(name) { return vals[name]; } });
+const recordingExec = () => {
+  const cmds: string[] = [];
+  return { cmds, exec: (c: string) => void cmds.push(c) };
+};
+
+beforeEach(() => {
+  skillDir = mkdtempSync(join(tmpdir(), 'nc-skill-'));
+  root = mkdtempSync(join(tmpdir(), 'nc-proj-'));
+  mkdirSync(join(skillDir, 'resources'), { recursive: true });
+  writeFileSync(join(skillDir, 'SKILL.md'), SKILL);
+  writeFileSync(join(skillDir, 'resources/sample.ts'), 'export const sample = true;\n');
+  mkdirSync(join(root, 'src'), { recursive: true });
+  writeFileSync(join(root, 'src/barrel.ts'), '// channel barrel\n');
+  writeFileSync(join(root, '.env'), '');
+  writeFileSync(join(root, 'package.json'), '{"name":"scratch"}');
+});
+
+describe('apply engine lifecycle', () => {
+  it('applies fs directives, captures the secret, and bounces the unknown step to an agent', async () => {
+    const { exec } = recordingExec();
+    const res = await applySkill(skillDir, root, { prompter: headless({ token: 'sekret-123' }), exec });
+
+    // mutations happened
+    expect(existsSync(join(root, 'src/sample.ts'))).toBe(true);
+    expect(readFileSync(join(root, 'src/barrel.ts'), 'utf8')).toContain("import './sample.js';");
+    expect(readFileSync(join(root, '.env'), 'utf8')).toContain('DEMO_TOKEN=sekret-123');
+
+    // the unknown directive went to an agent — with prose — not the human, not an abort
+    expect(res.agentTasks).toHaveLength(1);
+    expect(res.agentTasks[0].kind).toBe('patch-scheduler');
+    expect(res.agentTasks[0].prose).toContain('Hand-edit the scheduler');
+    expect(res.deferred).toEqual([]);
+    expect(res.journal.length).toBeGreaterThanOrEqual(3); // wrote + appended + set-env
+  });
+
+  it('is idempotent — a second apply changes nothing', async () => {
+    const p = headless({ token: 'sekret-123' });
+    await applySkill(skillDir, root, { prompter: p, exec: () => {} });
+    const second = await applySkill(skillDir, root, { prompter: p, exec: () => {} });
+    expect(second.applied).toEqual([]); // everything already applied
+    expect(second.journal).toEqual([]); // nothing mutated
+    expect(second.skipped.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('removes cleanly from the journal — no hand-written REMOVE.md', async () => {
+    const res = await applySkill(skillDir, root, { prompter: headless({ token: 'sekret-123' }), exec: () => {} });
+    await removeSkill(root, res.journal);
+    expect(existsSync(join(root, 'src/sample.ts'))).toBe(false);
+    expect(readFileSync(join(root, 'src/barrel.ts'), 'utf8')).not.toContain("import './sample.js';");
+    expect(readFileSync(join(root, '.env'), 'utf8')).not.toContain('DEMO_TOKEN');
+  });
+
+  it('defers a prompt (and its consumer) when the prompter has no value — headless rebuild', async () => {
+    const res = await applySkill(skillDir, root, { prompter: headless({}), exec: () => {} });
+    expect(res.deferred).toContain('token'); // prompt deferred
+    expect(res.deferred.some((d) => /unresolved \{\{token\}\}/.test(d))).toBe(true); // env-set blocked on it
+    expect(readFileSync(join(root, '.env'), 'utf8')).not.toContain('DEMO_TOKEN');
+  });
+
+  it('plan marks the unknown step ↳agent and the prompt ? needs-input before any write', () => {
+    const { steps, agentSteps, needsInput } = planSkill(skillDir, root);
+    expect(agentSteps).toBe(1);
+    expect(needsInput).toContain('token');
+    expect(existsSync(join(root, 'src/sample.ts'))).toBe(false); // planning mutated nothing
+  });
+});
@@ -0,0 +1,343 @@
+// The skill application engine — executes `nc:` directives parsed from a SKILL.md.
+//
+// The agent is always the top-level applier; this engine is the deterministic
+// accelerator it delegates to. Anything the engine can't do bounces back to the
+// AGENT (which reads the same prose and applies it, the way skills work today) —
+// never to the human, and never as a hard abort. The human is in the loop only
+// for `prompt` inputs and inherently-human prose (e.g. clicking through Slack).
+//
+// Phases (the F2 runtime contract, minimal form):
+//   1. parse + validate   — lint; a malformed skill never reaches apply
+//   2. PLAN               — per directive: skip|apply|needs-input|agent — no writes
+//   3. acquire inputs     — resolve every `prompt` via the injected Prompter
+//   4. mutate             — copy/append/env-set, journaled + idempotent
+//   5. run                — build/test/fetch (+ dep install) via injected exec
+// Remove is derived from the journal — no hand-written REMOVE.md.
+//
+// The Prompter is what makes one engine serve two contexts:
+//   • setup flow      → interactive prompter asks the user inline
+//   • recipe rebuild  → headless prompter returns from a values map, or defers
+//
+// Usage: pnpm exec tsx scripts/skill-apply.ts <skillDir>     # plan (no writes)
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync, writeFileSync, appendFileSync, copyFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseDirectives, promptVar, type Directive } from './skill-directives.js';
+
+export interface Prompter {
+  // Return the value, or undefined to DEFER (headless rebuild collects these).
+  ask(varName: string, question: string, secret: boolean): Promise<string | undefined>;
+}
+
+export type StepStatus = 'skip' | 'apply' | 'needs-input' | 'agent';
+export interface PlanStep {
+  n: number;
+  kind: string;
+  line: number;
+  status: StepStatus;
+  detail: string;
+}
+
+const read = (p: string) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
+const has = (root: string, rel: string) => existsSync(join(root, rel));
+const VAR_REF = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const destOf = (line: string) => (line.includes('->') ? line.split('->')[1].trim() : line.trim());
+const srcOf = (line: string) => (line.includes('->') ? line.split('->')[0].trim() : line.trim());
+
+function fileHasLine(root: string, rel: string, line: string): boolean {
+  return read(join(root, rel))
+    .split('\n')
+    .some((l) => l.trim() === line.trim());
+}
+function pkgHasDep(root: string, name: string): boolean {
+  try {
+    const pkg = JSON.parse(read(join(root, 'package.json')) || '{}');
+    return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+  } catch {
+    return false;
+  }
+}
+function envKeySet(root: string, key: string): boolean {
+  return read(join(root, '.env'))
+    .split('\n')
+    .some((l) => {
+      const m = l.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/);
+      return m !== null && m[1] === key && m[2].trim().length > 0;
+    });
+}
+
+// Per-directive idempotency check + "what it would do". Read-only.
+function selfStatus(d: Directive, root: string): { status: StepStatus; detail: string } {
+  switch (d.kind) {
+    case 'copy': {
+      const dests = d.body.map(destOf);
+      const missing = dests.filter((p) => !has(root, p));
+      const from = d.attrs['from-branch'] ? `fetch ${String(d.attrs['from-branch'])} → ` : '';
+      return missing.length
+        ? { status: 'apply', detail: `${from}copy ${missing.join(', ')} (absent)` }
+        : { status: 'skip', detail: `${dests.join(', ')} present` };
+    }
+    case 'append': {
+      const to = String(d.attrs.to ?? '');
+      const line = d.body[0] ?? '';
+      return fileHasLine(root, to, line)
+        ? { status: 'skip', detail: `${to} already has the line` }
+        : { status: 'apply', detail: `add to ${to}: ${line}` };
+    }
+    case 'dep': {
+      const missing = d.body.filter((s) => !pkgHasDep(root, s.slice(0, s.lastIndexOf('@'))));
+      return missing.length
+        ? { status: 'apply', detail: `install ${missing.join(', ')}` }
+        : { status: 'skip', detail: `${d.body.join(', ')} present` };
+    }
+    case 'run':
+      return { status: 'apply', detail: `${String(d.attrs.effect ?? 'run')}: ${d.body.join(' && ')}` };
+    case 'env-set': {
+      const keys = d.body.map((l) => l.split('=')[0].trim());
+      const missing = keys.filter((k) => !envKeySet(root, k));
+      return missing.length
+        ? { status: 'apply', detail: `set ${missing.join(', ')} in .env` }
+        : { status: 'skip', detail: `${keys.join(', ')} already set` };
+    }
+    case 'env-sync':
+      return { status: 'apply', detail: 'sync .env → data/env/env' };
+    case 'prompt':
+      return { status: 'needs-input', detail: '' };
+    default:
+      return { status: 'agent', detail: `no deterministic handler for nc:${d.kind} — an agent applies it from the prose` };
+  }
+}
+
+export function planSkill(skillDir: string, root: string): { steps: PlanStep[]; needsInput: string[]; agentSteps: number } {
+  const directives = parseDirectives(read(join(skillDir, 'SKILL.md')));
+  const self = directives.map((d) => ({ d, ...selfStatus(d, root) }));
+
+  const consumers = new Map<string, number[]>();
+  self.forEach(({ d }, i) => {
+    for (const line of d.body) for (const m of line.matchAll(VAR_REF)) (consumers.get(m[1]) ?? consumers.set(m[1], []).get(m[1])!).push(i);
+  });
+
+  const steps: PlanStep[] = self.map(({ d, status, detail }, i) => {
+    if (d.kind !== 'prompt') return { n: i + 1, kind: d.kind, line: d.line, status, detail };
+    const v = promptVar(d) ?? '?';
+    const tag = `${v}${d.args.includes('secret') ? ' (secret)' : ''}`;
+    const cons = consumers.get(v) ?? [];
+    const satisfied = cons.length > 0 && cons.every((j) => self[j].status === 'skip');
+    return satisfied
+      ? { n: i + 1, kind: d.kind, line: d.line, status: 'skip', detail: `${tag} — consumers already satisfied` }
+      : { n: i + 1, kind: d.kind, line: d.line, status: 'needs-input', detail: `${tag} → asked during apply` };
+  });
+
+  return {
+    steps,
+    needsInput: steps.filter((s) => s.status === 'needs-input').map((s) => s.detail.split(' ')[0]),
+    agentSteps: steps.filter((s) => s.status === 'agent').length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Apply (phases 3–5) + journal-derived remove.
+// ---------------------------------------------------------------------------
+
+export type JournalEntry =
+  | { op: 'wrote'; path: string }
+  | { op: 'appended'; path: string; line: string }
+  | { op: 'set-env'; key: string }
+  | { op: 'ran'; cmd: string; undo?: string };
+
+export interface AgentTask {
+  kind: string;
+  line: number;
+  reason: string;
+  prose: string; // the surrounding prose the agent reads to apply the step
+}
+
+export interface ApplyResult {
+  applied: string[];
+  skipped: string[];
+  deferred: string[]; // prompt vars / blocked consumers with no value yet
+  agentTasks: AgentTask[]; // bounced to an agent — NOT the human
+  journal: JournalEntry[];
+}
+
+export interface ApplyOptions {
+  prompter: Prompter;
+  exec?: (cmd: string) => void | Promise<void>; // dep/run/branch-fetch; injectable for tests
+  // Resolve which remote carries a `from-branch` registry branch. Defaults to a
+  // generic resolver (env override → first remote that has the branch → origin);
+  // setup injects one that reuses setup/lib/channels-remote.sh for exact parity.
+  resolveRemote?: (branch: string) => string;
+}
+
+// A hardcoded `origin` breaks forks where the registry branch lives on
+// `upstream`. Generic mirror of channels-remote.sh: explicit override → the
+// first remote that actually has the branch → origin.
+function defaultResolveRemote(branch: string, root: string): string {
+  const override = process.env.NANOCLAW_CHANNELS_REMOTE;
+  if (override) return override;
+  const cap = (cmd: string): string => {
+    try {
+      return execSync(cmd, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    } catch {
+      return '';
+    }
+  };
+  const remotes = cap('git remote').split('\n').map((s) => s.trim()).filter(Boolean);
+  const ordered = remotes.includes('origin') ? ['origin', ...remotes.filter((r) => r !== 'origin')] : remotes;
+  for (const r of ordered) if (cap(`git ls-remote --heads ${r} ${branch}`).trim()) return r;
+  return 'origin';
+}
+
+// The prose an agent reads when a step degrades: nearest heading + the
+// paragraph immediately above the directive fence.
+function proseFor(md: string, fenceLine1: number): string {
+  const lines = md.split('\n');
+  let i = fenceLine1 - 2;
+  while (i >= 0 && lines[i].trim() === '') i--;
+  const para: string[] = [];
+  while (i >= 0 && lines[i].trim() !== '' && !lines[i].startsWith('#')) para.unshift(lines[i--]);
+  let heading = '';
+  for (let h = i; h >= 0; h--) if (lines[h].startsWith('#')) { heading = lines[h]; break; }
+  return [heading, ...para].filter(Boolean).join('\n').trim();
+}
+
+function substitute(value: string, vars: Map<string, { value: string; secret: boolean }>): string {
+  return value.replace(VAR_REF, (_, name) => {
+    const v = vars.get(name);
+    if (!v) throw new Error(`unresolved {{${name}}}`);
+    return v.value;
+  });
+}
+
+// The mutating twin of selfStatus. Records what it did to the journal so remove
+// is derivable. Throws on failure → caught and bounced to an agent.
+async function applyOne(
+  d: Directive,
+  ctx: { root: string; skillDir: string; exec: (c: string) => void | Promise<void>; resolveRemote: (b: string) => string; vars: Map<string, { value: string; secret: boolean }>; journal: JournalEntry[] },
+): Promise<void> {
+  const { root, skillDir, exec, vars, journal } = ctx;
+  switch (d.kind) {
+    case 'copy':
+      if (d.attrs['from-branch']) {
+        const b = String(d.attrs['from-branch']);
+        const remote = ctx.resolveRemote(b);
+        await exec(`git fetch ${remote} ${b}`);
+        for (const l of d.body) await exec(`git show ${remote}/${b}:${srcOf(l)} > ${destOf(l)}`);
+      } else {
+        for (const l of d.body) {
+          const dst = join(root, destOf(l));
+          mkdirSync(dirname(dst), { recursive: true });
+          copyFileSync(join(skillDir, srcOf(l)), dst);
+        }
+      }
+      for (const l of d.body) journal.push({ op: 'wrote', path: destOf(l) });
+      break;
+    case 'append': {
+      const to = String(d.attrs.to);
+      for (const line of d.body) {
+        appendFileSync(join(root, to), (read(join(root, to)).endsWith('\n') || read(join(root, to)) === '' ? '' : '\n') + line + '\n');
+        journal.push({ op: 'appended', path: to, line });
+      }
+      break;
+    }
+    case 'dep': {
+      await exec(`pnpm add ${d.body.join(' ')}`);
+      const names = d.body.map((s) => s.slice(0, s.lastIndexOf('@'))).join(' ');
+      journal.push({ op: 'ran', cmd: `pnpm add ${d.body.join(' ')}`, undo: `pnpm remove ${names}` });
+      break;
+    }
+    case 'run':
+      for (const cmd of d.body) {
+        await exec(cmd);
+        const undo = d.attrs.effect === 'external' && typeof d.attrs.remove === 'string' ? d.attrs.remove : undefined;
+        journal.push({ op: 'ran', cmd, undo });
+      }
+      break;
+    case 'env-set': {
+      const envPath = join(root, '.env');
+      for (const entry of d.body) {
+        const eq = entry.indexOf('=');
+        const key = entry.slice(0, eq).trim();
+        const value = substitute(entry.slice(eq + 1).trim(), vars); // throws if a {{var}} is unresolved
+        if (!envKeySet(root, key)) {
+          appendFileSync(envPath, (read(envPath).endsWith('\n') || read(envPath) === '' ? '' : '\n') + `${key}=${value}\n`);
+          journal.push({ op: 'set-env', key });
+        }
+      }
+      break;
+    }
+    case 'env-sync':
+      mkdirSync(join(root, 'data/env'), { recursive: true });
+      copyFileSync(join(root, '.env'), join(root, 'data/env/env'));
+      break;
+    default:
+      throw new Error(`no handler for nc:${d.kind}`);
+  }
+}
+
+export async function applySkill(skillDir: string, root: string, opts: ApplyOptions): Promise<ApplyResult> {
+  // Lint (validate()) is the authoring/CI gate, run before a skill ships — NOT
+  // here. Apply is best-effort: an unknown directive (a typo lint should have
+  // caught, or one newer than this engine) bounces to an agent, never blocks.
+  const md = read(join(skillDir, 'SKILL.md'));
+  const directives = parseDirectives(md);
+  const exec = opts.exec ?? (() => { throw new Error('no exec provided'); });
+  const resolveRemote = opts.resolveRemote ?? ((b: string) => defaultResolveRemote(b, root));
+  const vars = new Map<string, { value: string; secret: boolean }>();
+  const res: ApplyResult = { applied: [], skipped: [], deferred: [], agentTasks: [], journal: [] };
+  const bounce = (d: Directive, reason: string) => res.agentTasks.push({ kind: d.kind, line: d.line, reason, prose: proseFor(md, d.line) });
+
+  for (const d of directives) {
+    try {
+      if (d.kind === 'prompt') {
+        const v = promptVar(d)!;
+        const val = await opts.prompter.ask(v, d.body.join(' '), d.args.includes('secret'));
+        if (val === undefined) res.deferred.push(v);
+        else vars.set(v, { value: val, secret: d.args.includes('secret') });
+        continue;
+      }
+      const st = selfStatus(d, root);
+      if (st.status === 'agent') { bounce(d, 'no deterministic handler'); continue; }
+      if (st.status === 'skip') { res.skipped.push(`${d.kind}: ${st.detail}`); continue; }
+      await applyOne(d, { root, skillDir, exec, resolveRemote, vars, journal: res.journal });
+      res.applied.push(`${d.kind}: ${st.detail}`);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (/unresolved \{\{/.test(msg)) res.deferred.push(msg); // blocked on a prompt input
+      else bounce(d, `engine could not apply (${msg}) — an agent applies it from the prose`);
+    }
+  }
+  return res;
+}
+
+// Remove is the journal played backwards — no hand-written REMOVE.md.
+export async function removeSkill(root: string, journal: JournalEntry[], exec?: (c: string) => void | Promise<void>): Promise<void> {
+  for (const e of [...journal].reverse()) {
+    if (e.op === 'wrote') rmSync(join(root, e.path), { force: true });
+    else if (e.op === 'appended') {
+      const p = join(root, e.path);
+      writeFileSync(p, read(p).split('\n').filter((l) => l.trim() !== e.line.trim()).join('\n'));
+    } else if (e.op === 'set-env') {
+      const p = join(root, '.env');
+      writeFileSync(p, read(p).split('\n').filter((l) => !l.startsWith(`${e.key}=`)).join('\n'));
+    } else if (e.op === 'ran' && e.undo && exec) {
+      await exec(e.undo);
+    }
+  }
+}
+
+// CLI — the planner (no writes)
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  const skillDir = process.argv[2];
+  if (!skillDir) {
+    console.error('usage: pnpm exec tsx scripts/skill-apply.ts <skillDir>');
+    process.exit(2);
+  }
+  const root = process.cwd();
+  const { steps, needsInput, agentSteps } = planSkill(skillDir, root);
+  console.log(`PLAN ${skillDir}   project: ${root}\n`);
+  const icon: Record<StepStatus, string> = { skip: '✓ skip', apply: '→ apply', 'needs-input': '? human', agent: '↳ agent' };
+  for (const s of steps) console.log(`${String(s.n).padStart(2)}. ${icon[s.status].padEnd(8)} ${s.kind.padEnd(9)} ${s.detail}`);
+  console.log(`\nneeds human input: ${needsInput.join(', ') || '(none)'}    →agent: ${agentSteps}`);
+}
@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { parseDirectives, validate, promptVar, resolveChatCoreVersion } from './skill-directives.js';
+
+// Guards the structured-directive format against the converted add-slack skill:
+// red if the conversion drifts (a directive dropped/renamed) or the parser breaks.
+const slack = readFileSync('.claude/skills/add-slack/SKILL.md', 'utf8');
+const directives = parseDirectives(slack);
+
+describe('skill-directives parser, on the converted add-slack', () => {
+  it('extracts the apply + credential directives in document order', () => {
+    expect(directives.map((d) => d.kind)).toEqual([
+      'copy', // step 1: adapter + test from the channels branch
+      'append', // step 2: barrel registration
+      'dep', // step 3: pinned package
+      'run', // step 4: build
+      'run', // step 4: test
+      'prompt', // credentials: capture bot token
+      'prompt', // credentials: capture signing secret
+      'env-set', // credentials: write captured values to .env
+      'env-sync', // credentials: sync to container
+    ]);
+  });
+
+  it('reads copy as a branch fetch with both files', () => {
+    const copy = directives.find((d) => d.kind === 'copy')!;
+    expect(copy.attrs['from-branch']).toBe('channels');
+    expect(copy.body).toEqual(['src/channels/slack.ts', 'src/channels/slack-registration.test.ts']);
+  });
+
+  it('reads the barrel append target and line', () => {
+    const append = directives.find((d) => d.kind === 'append')!;
+    expect(append.attrs.to).toBe('src/channels/index.ts');
+    expect(append.body).toEqual(["import './slack.js';"]);
+  });
+
+  it('reads the dependency pinned exactly', () => {
+    const dep = directives.find((d) => d.kind === 'dep')!;
+    expect(dep.body).toEqual(['@chat-adapter/slack@4.26.0']);
+  });
+
+  it('tags the runs with their effects', () => {
+    expect(directives.filter((d) => d.kind === 'run').map((d) => d.attrs.effect)).toEqual(['build', 'test']);
+  });
+
+  it('captures each prompt into a named, secret variable — no destination baked in', () => {
+    const prompts = directives.filter((d) => d.kind === 'prompt');
+    expect(prompts.map(promptVar)).toEqual(['bot_token', 'signing_secret']);
+    for (const p of prompts) expect(p.args).toContain('secret');
+    // The prompt body is the question; it does not mention env at all.
+    expect(prompts[0].body.join(' ')).toMatch(/Bot User OAuth Token/);
+  });
+
+  it('wires the captured variables into env-set via {{var}} references', () => {
+    const envSet = directives.find((d) => d.kind === 'env-set')!;
+    expect(envSet.body).toEqual(['SLACK_BOT_TOKEN={{bot_token}}', 'SLACK_SIGNING_SECRET={{signing_secret}}']);
+  });
+
+  it('passes validation (well-formed, pinned, every {{var}} captured first)', () => {
+    expect(validate(directives)).toEqual([]);
+  });
+
+  it('keeps its @chat-adapter pin in sync with our chat core (drift guard)', () => {
+    const chat = resolveChatCoreVersion(process.cwd());
+    expect(chat).toMatch(/^\d+\.\d+\.\d+/); // our lockfile resolves a real chat version
+    expect(validate(directives, { chatVersion: chat })).toEqual([]); // add-slack matches it
+  });
+
+  it('ignores plain (non-nc:) code fences so prose stays the floor', () => {
+    const withProse = slack + '\n```bash\nrm -rf /\n```\n';
+    expect(parseDirectives(withProse).map((d) => d.kind)).toEqual(directives.map((d) => d.kind));
+  });
+});
+
+describe('validation catches malformed directives', () => {
+  it('flags an unpinned dependency and an unknown directive', () => {
+    const md = ['```nc:dep', '@chat-adapter/slack@latest', '```', '', '```nc:frobnicate', 'x', '```'].join('\n');
+    const problems = validate(parseDirectives(md));
+    expect(problems.some((p) => /exact semver/.test(p.message))).toBe(true);
+    expect(problems.some((p) => /unknown directive/.test(p.message))).toBe(true);
+  });
+
+  it('flags an env-set that references a variable no prompt captured', () => {
+    const md = ['```nc:env-set', 'SLACK_BOT_TOKEN={{bot_token}}', '```'].join('\n');
+    const problems = validate(parseDirectives(md));
+    expect(problems.some((p) => /\{\{bot_token\}\} but no earlier nc:prompt/.test(p.message))).toBe(true);
+  });
+
+  it('flags a @chat-adapter pin that does not match the chat core', () => {
+    const md = ['```nc:dep', '@chat-adapter/slack@4.27.0', '```'].join('\n');
+    const problems = validate(parseDirectives(md), { chatVersion: '4.26.0' });
+    expect(problems.some((p) => /must match the chat package/.test(p.message))).toBe(true);
+  });
+
+  it('accepts a @chat-adapter pin that matches the chat core', () => {
+    const md = ['```nc:dep', '@chat-adapter/slack@4.26.0', '```'].join('\n');
+    expect(validate(parseDirectives(md), { chatVersion: '4.26.0' })).toEqual([]);
+  });
+});
@@ -0,0 +1,179 @@
+// Extract `nc:` skill directives embedded in a SKILL.md.
+//
+// A fenced code block whose info-string starts with `nc:` is a load-bearing
+// directive; every other fence (and all prose) is the human floor the parser
+// ignores. That is the whole "two readers, one document" property: an agent
+// applies the prose, a tool applies the directives, and anything the tool
+// can't handle degrades to the prose beside it. This is the seed for both the
+// conformance linter and the deterministic applier.
+//
+// Grammar, derived from add-slack:
+//
+//   ```nc:<directive> <arg>... [key:value]...
+//   <body line>
+//   ```
+//
+// `prompt` only *acquires* a value and binds it to a name; a separate directive
+// *applies* it, referenced as `{{name}}`. That keeps "ask the human" decoupled
+// from "what you do with the answer" (env, ncl, the OneCLI vault, a file).
+//
+//   copy [from-branch:<b>]  body: `PATH` (src==dst) or `SRC -> DST`   overwrite
+//   append to:<file>        body: line(s) to add                      skip if present
+//   dep [manager:pnpm]      body: `pkg@<exact-semver>` line(s)        reinstall no-op
+//   run [effect:build|test|fetch|external]  body: shell command(s)    re-runnable
+//   prompt <var> [secret]   body: the question → binds {{var}}        skip if satisfied
+//   env-set                 body: `KEY=value` ({{var}} allowed)       set-if-absent
+//   env-sync                (no body) `.env` → data/env/env           idempotent copy
+//
+// Usage: pnpm exec tsx scripts/skill-directives.ts <SKILL.md>
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface Directive {
+  kind: string;
+  args: string[]; // positional bare tokens, e.g. prompt's variable name
+  attrs: Record<string, string | true>; // key:value tokens
+  body: string[];
+  line: number; // 1-based line of the opening fence
+}
+
+export interface Problem {
+  line: number;
+  kind: string;
+  message: string;
+}
+
+const FENCE = /^```(\S.*)?$/;
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const VAR_REF = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const KNOWN = new Set(['copy', 'append', 'dep', 'run', 'prompt', 'env-set', 'env-sync']);
+const PROMPT_FLAGS = new Set(['secret']);
+
+export function parseDirectives(markdown: string): Directive[] {
+  const lines = markdown.split('\n');
+  const out: Directive[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const info = lines[i].match(FENCE)?.[1]?.trim();
+    if (info === undefined) {
+      i++;
+      continue;
+    }
+    // A fence opens here; consume to its closing fence either way.
+    let j = i + 1;
+    const body: string[] = [];
+    while (j < lines.length && !FENCE.test(lines[j])) {
+      body.push(lines[j]);
+      j++;
+    }
+    if (info.startsWith('nc:')) {
+      const [tag, ...rest] = info.split(/\s+/);
+      const args: string[] = [];
+      const attrs: Record<string, string | true> = {};
+      for (const tok of rest) {
+        const eq = tok.indexOf(':');
+        if (eq > 0) attrs[tok.slice(0, eq)] = tok.slice(eq + 1);
+        else args.push(tok);
+      }
+      out.push({
+        kind: tag.slice('nc:'.length),
+        args,
+        attrs,
+        body: body.map((l) => l.trim()).filter(Boolean),
+        line: i + 1,
+      });
+    }
+    i = j + 1; // skip past the closing fence (directive or plain code block)
+  }
+  return out;
+}
+
+/** The variable a `prompt` binds (the first positional that isn't a flag). */
+export function promptVar(d: Directive): string | undefined {
+  return d.args.find((a) => !PROMPT_FLAGS.has(a));
+}
+
+/** `{{var}}` names referenced anywhere in a directive's body. */
+function referencedVars(d: Directive): string[] {
+  const found: string[] = [];
+  for (const line of d.body) for (const m of line.matchAll(VAR_REF)) found.push(m[1]);
+  return found;
+}
+
+/**
+ * The resolved `chat` core version from our lockfile — the single source of
+ * truth a `@chat-adapter/*` adapter pin must match (the adapter and the core
+ * move in lockstep). Reads the root importer's direct `chat` dependency, whose
+ * `specifier`/`version` pair is unique to importer deps (transitive entries in
+ * the packages section have no `specifier`). Returns undefined if not found.
+ */
+export function resolveChatCoreVersion(root: string): string | undefined {
+  let lock = '';
+  try {
+    lock = readFileSync(join(root, 'pnpm-lock.yaml'), 'utf8');
+  } catch {
+    return undefined;
+  }
+  const m = lock.match(/\n\s+chat:\n\s+specifier:[^\n]*\n\s+version:\s*([0-9][^\s(]*)/);
+  return m?.[1];
+}
+
+export function validate(directives: Directive[], ctx?: { chatVersion?: string }): Problem[] {
+  const problems: Problem[] = [];
+  const defined = new Set<string>();
+  const flag = (d: Directive, message: string) => problems.push({ line: d.line, kind: d.kind, message });
+  for (const d of directives) {
+    if (!KNOWN.has(d.kind)) flag(d, `unknown directive nc:${d.kind}`);
+    switch (d.kind) {
+      case 'dep':
+        for (const spec of d.body) {
+          const at = spec.lastIndexOf('@');
+          const name = at > 0 ? spec.slice(0, at) : spec;
+          const version = at > 0 ? spec.slice(at + 1) : '';
+          if (!EXACT_SEMVER.test(version)) flag(d, `dep "${spec}" must pin an exact semver (no ranges/latest)`);
+          // A @chat-adapter/* adapter must match the chat core version in our
+          // lockfile — the family moves together. This catches pin drift (the
+          // 4.27.0-vs-chat@4.26.0 mismatch) at lint time.
+          if (ctx?.chatVersion && name.startsWith('@chat-adapter/') && version !== ctx.chatVersion) {
+            flag(d, `${name} pinned ${version} but our chat core is ${ctx.chatVersion} — a @chat-adapter/* adapter must match the chat package`);
+          }
+        }
+        break;
+      case 'append':
+        if (!d.attrs.to) flag(d, 'append requires to:<file>');
+        if (d.body.length === 0) flag(d, 'append requires a line to add');
+        break;
+      case 'copy':
+        if (d.body.length === 0) flag(d, 'copy requires at least one path');
+        break;
+      case 'prompt':
+        if (!promptVar(d)) flag(d, 'prompt requires a variable name, e.g. `nc:prompt token`');
+        if (d.body.length === 0) flag(d, 'prompt requires a question in its body');
+        break;
+    }
+    // A consumer can only reference a variable an earlier prompt captured.
+    for (const ref of referencedVars(d)) {
+      if (!defined.has(ref)) flag(d, `references {{${ref}}} but no earlier nc:prompt captured it`);
+    }
+    if (d.kind === 'prompt') {
+      const v = promptVar(d);
+      if (v) defined.add(v);
+    }
+  }
+  return problems;
+}
+
+// CLI
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  let path = process.argv[2];
+  if (!path) {
+    console.error('usage: pnpm exec tsx scripts/skill-directives.ts <skillDir|SKILL.md>');
+    process.exit(2);
+  }
+  if (existsSync(path) && statSync(path).isDirectory()) path = join(path, 'SKILL.md');
+  const directives = parseDirectives(readFileSync(path, 'utf8'));
+  const problems = validate(directives, { chatVersion: resolveChatCoreVersion(process.cwd()) });
+  console.log(JSON.stringify({ directives, problems }, null, 2));
+  process.exit(problems.length ? 1 : 0);
+}
@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+#
+# Install the Codex agent provider non-interactively: copy the payload from the
+# `providers` branch, wire the three provider barrels, and add the Codex CLI to
+# the container manifest (container/cli-tools.json). The image rebuild is the
+# caller's job (the setup container step / `./container/build.sh`).
+#
+# Emits exactly one status block on stdout (ADD_CODEX); all chatty progress
+# goes to stderr. Keep in sync with .claude/skills/add-codex/SKILL.md.
+set -euo pipefail
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+# Keep in sync with add-codex SKILL.md. This is the canonical Codex CLI pin —
+# it lands in container/cli-tools.json (the global-CLI manifest), not the Dockerfile.
+CODEX_VERSION="0.138.0"
+
+# Resolve the remote carrying the providers branch (same nanoclaw remote that
+# carries channels — handles forks where it isn't `origin`).
+# shellcheck source=setup/lib/channels-remote.sh
+source "$PROJECT_ROOT/setup/lib/channels-remote.sh"
+REMOTE=$(resolve_channels_remote)
+BRANCH="${REMOTE}/providers"
+
+# The codex payload — host provider, container runtime, setup module, doctrine.
+# Barrels are appended to, not copied.
+PAYLOAD_FILES=(
+  src/providers/codex.ts
+  src/providers/codex-agents-md.ts
+  src/providers/codex-registration.test.ts
+  src/providers/codex-host-contribution.test.ts
+  src/providers/codex-agents-md.test.ts
+  container/agent-runner/src/providers/codex.ts
+  container/agent-runner/src/providers/codex-app-server.ts
+  container/agent-runner/src/providers/exchange-archive.ts
+  container/agent-runner/src/providers/exchange-archive.test.ts
+  container/agent-runner/src/providers/codex-registration.test.ts
+  container/agent-runner/src/providers/codex.factory.test.ts
+  container/agent-runner/src/providers/codex.turns.test.ts
+  container/agent-runner/src/providers/codex-app-server.test.ts
+  container/agent-runner/src/providers/codex-cli-tools.test.ts
+  setup/providers/codex.ts
+  setup/providers/codex.test.ts
+  setup/providers/codex-registration.test.ts
+  container/AGENTS.md
+)
+BARRELS=(
+  src/providers/index.ts
+  container/agent-runner/src/providers/index.ts
+  setup/providers/index.ts
+)
+
+ALREADY_INSTALLED=true
+emit_status() {
+  local status=$1 error=${2:-}
+  echo "=== NANOCLAW SETUP: ADD_CODEX ==="
+  echo "STATUS: ${status}"
+  echo "CODEX_VERSION: ${CODEX_VERSION}"
+  echo "ALREADY_INSTALLED: ${ALREADY_INSTALLED}"
+  [ -n "$error" ] && echo "ERROR: ${error}"
+  echo "=== END ==="
+}
+log() { echo "[add-codex] $*" >&2; }
+
+# Idempotent: a complete install has the host provider file, the host barrel
+# import, and the Codex CLI in the container manifest. Any missing → (re)install.
+need_install() {
+  [ ! -f src/providers/codex.ts ] && return 0
+  ! grep -q "^import './codex.js';" src/providers/index.ts 2>/dev/null && return 0
+  ! grep -q '@openai/codex' container/cli-tools.json 2>/dev/null && return 0
+  return 1
+}
+
+if need_install; then
+  ALREADY_INSTALLED=false
+
+  log "Fetching providers branch from ${REMOTE}…"
+  git fetch "$REMOTE" providers >&2 2>/dev/null || {
+    emit_status failed "git fetch ${REMOTE} providers failed"
+    exit 1
+  }
+
+  log "Copying Codex payload from ${BRANCH}…"
+  for f in "${PAYLOAD_FILES[@]}"; do
+    mkdir -p "$(dirname "$f")"
+    git show "${BRANCH}:$f" > "$f" 2>/dev/null || {
+      emit_status failed "providers branch is missing ${f}"
+      exit 1
+    }
+  done
+
+  log "Wiring provider barrels…"
+  for b in "${BARRELS[@]}"; do
+    grep -q "^import './codex.js';" "$b" || printf "import './codex.js';\n" >> "$b"
+  done
+
+  log "Adding the Codex CLI to the container manifest (cli-tools.json)…"
+  # A json-merge: append { name, version } if absent. The Dockerfile installs
+  # every manifest entry via pinned `pnpm install -g` — no Dockerfile edit, no
+  # awk surgery. @openai/codex has no native postinstall, so no "onlyBuilt".
+  MANIFEST=container/cli-tools.json
+  node -e '
+    const fs = require("fs");
+    const [file, name, version] = process.argv.slice(1);
+    const tools = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!tools.some((t) => t.name === name)) {
+      tools.push({ name, version });
+      const fmt = (t) =>
+        "  { " +
+        Object.entries(t).map(([k, v]) => JSON.stringify(k) + ": " + JSON.stringify(v)).join(", ") +
+        " }";
+      fs.writeFileSync(file, "[\n" + tools.map(fmt).join(",\n") + "\n]\n");
+    }
+  ' "$MANIFEST" "@openai/codex" "${CODEX_VERSION}" || {
+    emit_status failed "failed to add @openai/codex to ${MANIFEST}"
+    exit 1
+  }
+fi
+
+emit_status ok
@@ -1,125 +0,0 @@
-#!/usr/bin/env bash
-#
-# Install the Slack adapter, persist SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET 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.
-#
-# 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
-# story without cluttering the final block for the parser.
-set -euo pipefail
-
-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"
-
-# Resolve which remote carries the channels branch — handles forks where
-# upstream lives on a different remote than `origin`.
-# shellcheck source=setup/lib/channels-remote.sh
-source "$PROJECT_ROOT/setup/lib/channels-remote.sh"
-CHANNELS_REMOTE=$(resolve_channels_remote)
-CHANNELS_BRANCH="${CHANNELS_REMOTE}/channels"
-
-emit_status() {
-  local status=$1 error=${2:-}
-  local already=${ADAPTER_ALREADY_INSTALLED:-false}
-  echo "=== NANOCLAW SETUP: ADD_SLACK ==="
-  echo "STATUS: ${status}"
-  echo "ADAPTER_VERSION: ${ADAPTER_VERSION}"
-  echo "ADAPTER_ALREADY_INSTALLED: ${already}"
-  [ -n "$error" ] && echo "ERROR: ${error}"
-  echo "=== END ==="
-}
-
-log() { echo "[add-slack] $*" >&2; }
-
-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"
-  exit 1
-fi
-
-need_install() {
-  [ ! -f src/channels/slack.ts ] && return 0
-  ! grep -q "^import './slack.js';" src/channels/index.ts 2>/dev/null && return 0
-  return 1
-}
-
-ADAPTER_ALREADY_INSTALLED=true
-if need_install; then
-  ADAPTER_ALREADY_INSTALLED=false
-  log "Fetching channels branch…"
-  git fetch "$CHANNELS_REMOTE" channels >&2 2>/dev/null || {
-    emit_status failed "git fetch ${CHANNELS_REMOTE} channels failed"
-    exit 1
-  }
-
-  log "Copying adapter from ${CHANNELS_BRANCH}…"
-  git show "${CHANNELS_BRANCH}:src/channels/slack.ts" > src/channels/slack.ts
-
-  # Append self-registration import if missing.
-  if ! grep -q "^import './slack.js';" src/channels/index.ts; then
-    echo "import './slack.js';" >> src/channels/index.ts
-  fi
-
-  log "Installing ${ADAPTER_VERSION}…"
-  pnpm install "${ADAPTER_VERSION}" >&2 2>/dev/null || {
-    emit_status failed "pnpm install ${ADAPTER_VERSION} failed"
-    exit 1
-  }
-
-  log "Building…"
-  pnpm run build >&2 2>/dev/null || {
-    emit_status failed "pnpm run build failed"
-    exit 1
-  }
-else
-  log "Adapter files already installed — skipping install phase."
-fi
-
-# Persist credentials. auto.ts validates via auth.test before this point, so
-# bad values here would be an internal bug rather than operator input.
-touch .env
-upsert_env() {
-  local key=$1 value=$2
-  if grep -q "^${key}=" .env; then
-    awk -v k="$key" -v v="$value" \
-        'BEGIN{FS=OFS="="} $1==k {print k "=" v; next} {print}' \
-      .env > .env.tmp && mv .env.tmp .env
-  else
-    echo "${key}=${value}" >> .env
-  fi
-}
-upsert_env SLACK_BOT_TOKEN "$SLACK_BOT_TOKEN"
-upsert_env SLACK_SIGNING_SECRET "$SLACK_SIGNING_SECRET"
-
-# Container reads from data/env/env (the host mounts it).
-mkdir -p data/env
-cp .env data/env/env
-
-log "Restarting service so the new adapter picks up the credentials…"
-# shellcheck source=setup/lib/install-slug.sh
-source "$PROJECT_ROOT/setup/lib/install-slug.sh"
-case "$(uname -s)" in
-  Darwin)
-    launchctl kickstart -k "gui/$(id -u)/$(launchd_label)" >&2 2>/dev/null || true
-    ;;
-  Linux)
-    systemctl --user restart "$(systemd_unit)" >&2 2>/dev/null \
-      || sudo systemctl restart "$(systemd_unit)" >&2 2>/dev/null \
-      || true
-    ;;
-esac
-
-# Give the Slack adapter a moment to finish starting the webhook listener
-# before emitting success.
-sleep 3
-
-emit_status success
@@ -38,8 +38,12 @@ import { runTeamsChannel } from './channels/teams.js';
 import { runTelegramChannel } from './channels/telegram.js';
 import { runWhatsAppChannel } from './channels/whatsapp.js';
 import { pingCliAgent, type PingResult } from './lib/agent-ping.js';
+import { getSetupProvider, listSetupProviders } from './providers/registry.js';
+// Provider payloads self-register their picker entry + auth on import.
+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 {
  applyToEnv,
  parseFlags,
@@ -321,8 +325,54 @@ async function main(): Promise<void> {
    }
  }

+  let agentProvider: string | undefined;
  if (!skip.has('auth')) {
-    await runAuthStep();
+    // Agent runtime pick. Claude is the default and a no-op — choosing it
+    // runs the existing Claude auth flow unchanged. A branch provider walks
+    // its own auth (e.g. Codex: ChatGPT subscription or API key, vault-only)
+    // and verifies its payload is wired. The pick installs and authenticates
+    // the runtime; it is NOT an install-wide default — and it is NOT a
+    // creation flag. Provider is a DB property of a group: the creation flows
+    // create provider-agnostic groups, and setup sets the picked provider on
+    // each via `ncl groups config update --provider` right after creating it
+    // (the creation scripts inherit it and apply at create — see picked-provider). Existing groups switch the
+    // same way (docs/provider-migration.md).
+    agentProvider = await askAgentProviderChoice();
+    setPickedProvider(agentProvider);
+    let providerEntry = getSetupProvider(agentProvider);
+    if (agentProvider !== 'claude' && !providerEntry) {
+      // A non-claude provider picked from the hard-wired list isn't wired in
+      // this install yet — install it via its self-contained script (channel
+      // style, idempotent: self-skips if already installed), rebuild the image
+      // (the container step already ran, the Dockerfile just changed), then
+      // load the payload's setup module so it self-registers.
+      const install = await runQuietChild(
+        `add-${agentProvider}`,
+        'bash',
+        [`setup/add-${agentProvider}.sh`],
+        {
+          running: `Installing ${agentProvider}…`,
+          done: `${agentProvider} installed.`,
+        },
+      );
+      if (!install.ok) {
+        await fail(
+          `add-${agentProvider}`,
+          `Couldn't install ${agentProvider}.`,
+          'See logs/setup-steps/ for details, then retry setup.',
+        );
+      }
+      p.log.info(brandBody('Rebuilding the container image with the new provider…'));
+      spawnSync('./container/build.sh', [], { stdio: 'inherit' });
+      await import(`./providers/${agentProvider}.js`);
+      providerEntry = getSetupProvider(agentProvider);
+    }
+    if (providerEntry?.runAuth) {
+      await providerEntry.runAuth();
+      await providerEntry.runInstallCheck?.();
+    } else {
+      await runAuthStep();
+    }
  }

  if (!skip.has('mounts')) {
@@ -748,6 +798,39 @@ function sendChatMessage(message: string): Promise<void> {

 // ─── auth step (select → branch) ────────────────────────────────────────

+// Providers offered for install are hard-wired in trunk — an audited control
+// surface (no branch enumeration that anyone with write access could extend).
+// Codex is the only one offered here; opencode/ollama install via their own
+// /add-* skills. Each is installed by its self-contained setup/add-<name>.sh.
+const INSTALLABLE_PROVIDERS = [
+  { value: 'codex', label: 'Codex', hint: 'OpenAI — ChatGPT subscription or API key' },
+] as const;
+
+async function askAgentProviderChoice(): Promise<string> {
+  const installed = listSetupProviders();
+  const installedNames = new Set(installed.map((entry) => entry.value));
+  // Offer the hard-wired installable providers this install hasn't wired yet —
+  // selecting one installs it via setup/add-<name>.sh.
+  const available = INSTALLABLE_PROVIDERS.filter((prov) => !installedNames.has(prov.value));
+  const options = [
+    ...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 choice = ensureAnswer(
+    await brightSelect<string>({
+      message: 'Which agent runtime should power your assistant?',
+      options,
+      initialValue: 'claude',
+    }),
+  ) as string;
+  setupLog.userInput('agent_provider', choice);
+  phEmit('agent_provider_chosen', { provider: choice });
+  return choice;
+}
+
 async function runAuthStep(): Promise<void> {
  if (anthropicSecretExists()) {
    p.log.success(brandBody('Your Claude account is already connected.'));
@@ -1261,7 +1344,7 @@ function detectExistingOnecli(): { version: string; apiHost: string } | null {
    } catch {
      // not JSON — try to extract a URL directly
    }
-    const m = raw.match(/https?:\/\/[\w.\-]+(?::\d+)?/);
+    const m = raw.match(/https?:\/\/[\w.-]+(?::\d+)?/);
    return m ? { version, apiHost: m[0] } : null;
  } catch {
    return null;
@@ -8,7 +8,8 @@
 *      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)
+ *   4. Apply the /add-slack skill via the directive engine (the skill's
+ *      SKILL.md is the single source of truth) + restart the service
 *   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")
@@ -21,9 +22,12 @@
 *
 * All output obeys the three-level contract. See docs/setup-flow.md.
 */
+import { execSync } from 'node:child_process';
+
 import * as p from '@clack/prompts';
 import k from 'kleur';

+import { applySkill, type Prompter } from '../../scripts/skill-apply.js';
 import * as setupLog from '../logs.js';
 import { BACK_TO_CHANNEL_SELECTION, type ChannelFlowResult } from '../lib/back-nav.js';
 import { brightSelect } from '../lib/bright-select.js';
@@ -53,31 +57,12 @@ export async function runSlackChannel(displayName: string): Promise<ChannelFlowR
  const signingSecret = await collectSigningSecret();
  const info = await validateSlackToken(token);

-  const install = await runQuietChild(
-    'slack-install',
-    'bash',
-    ['setup/add-slack.sh'],
-    {
-      running: `Connecting Slack to @${info.botName} (${info.teamName})…`,
-      done: 'Slack adapter installed.',
-    },
-    {
-      env: {
-        SLACK_BOT_TOKEN: token,
-        SLACK_SIGNING_SECRET: signingSecret,
-      },
-      extraFields: {
-        BOT_NAME: info.botName,
-        TEAM_NAME: info.teamName,
-        TEAM_ID: info.teamId,
-      },
-    },
-  );
+  const install = await applySlackSkill(token, signingSecret, info);
  if (!install.ok) {
    await fail(
      'slack-install',
      "Couldn't connect Slack.",
-      'See logs/setup-steps/ for details, then retry setup.',
+      install.detail || 'See logs/setup-steps/ for details, then retry setup.',
    );
  }

@@ -125,6 +110,94 @@ export async function runSlackChannel(displayName: string): Promise<ChannelFlowR
  showPostInstallChecklist(info);
 }

+/**
+ * Install the Slack adapter and persist credentials by applying the `/add-slack`
+ * skill through the structured-directive engine. The skill's SKILL.md is the
+ * single source of truth — this replaces the hand-maintained setup/add-slack.sh,
+ * which had already drifted on the pinned adapter version.
+ *
+ * The two secrets collected above are handed to the skill's `prompt` directives
+ * through the in-process Prompter, so they never touch argv or disk. The engine
+ * runs copy/append/dep/build + env-set/env-sync; we restart the service after
+ * (the skill itself doesn't, by design). add-slack is fully deterministic and
+ * both secrets are supplied, so a healthy apply leaves nothing for an agent and
+ * nothing deferred — either bucket being non-empty means the install failed.
+ */
+async function applySlackSkill(
+  token: string,
+  signingSecret: string,
+  info: WorkspaceInfo,
+): Promise<{ ok: boolean; detail: string }> {
+  const projectRoot = process.cwd();
+  const s = p.spinner();
+  const start = Date.now();
+  s.start(`Connecting Slack to @${info.botName} (${info.teamName})…`);
+
+  const prompter: Prompter = {
+    async ask(name) {
+      if (name === 'bot_token') return token;
+      if (name === 'signing_secret') return signingSecret;
+      return undefined;
+    },
+  };
+
+  try {
+    const result = await applySkill('.claude/skills/add-slack', projectRoot, {
+      prompter,
+      exec: (cmd) => {
+        execSync(cmd, { cwd: projectRoot, stdio: 'pipe' });
+      },
+      // Fork-aware: reuse the existing resolver (handles upstream/fork remotes
+      // and the auto-add-upstream fallback) instead of assuming `origin`.
+      resolveRemote: () =>
+        execSync('source setup/lib/channels-remote.sh; resolve_channels_remote', {
+          cwd: projectRoot,
+          shell: '/bin/bash',
+          encoding: 'utf8',
+        }).trim(),
+    });
+
+    if (result.agentTasks.length || result.deferred.length) {
+      const why = [...result.agentTasks.map((t) => t.reason), ...result.deferred].join('; ');
+      s.stop("Couldn't finish installing Slack.", 1);
+      setupLog.step('slack-install', 'failed', Date.now() - start, { ERROR: why });
+      return { ok: false, detail: why };
+    }
+
+    restartService(projectRoot);
+    s.stop('Slack adapter installed.');
+    setupLog.step('slack-install', 'success', Date.now() - start, {
+      APPLIED: String(result.applied.length),
+      SKIPPED: String(result.skipped.length),
+      BOT_NAME: info.botName,
+      TEAM_NAME: info.teamName,
+      TEAM_ID: info.teamId,
+    });
+    return { ok: true, detail: '' };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    s.stop("Couldn't install the Slack adapter.", 1);
+    setupLog.step('slack-install', 'failed', Date.now() - start, { ERROR: message });
+    return { ok: false, detail: 'See logs/setup-steps/ for details, then retry setup.' };
+  }
+}
+
+/** Best-effort service restart so the new adapter + credentials take effect. */
+function restartService(projectRoot: string): void {
+  const script = [
+    `source "${projectRoot}/setup/lib/install-slug.sh"`,
+    'case "$(uname -s)" in',
+    '  Darwin) launchctl kickstart -k "gui/$(id -u)/$(launchd_label)" ;;',
+    '  Linux) systemctl --user restart "$(systemd_unit)" || sudo systemctl restart "$(systemd_unit)" ;;',
+    'esac',
+  ].join('\n');
+  try {
+    execSync(script, { cwd: projectRoot, stdio: 'pipe', shell: '/bin/bash' });
+  } catch {
+    // The service may not be installed yet during a fresh setup — best-effort.
+  }
+}
+
 async function walkThroughAppCreation(): Promise<'continue' | 'back'> {
  // 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.
@@ -68,8 +68,12 @@ export async function run(args: string[]): Promise<void> {

  log.info('Invoking init-cli-agent', { displayName, agentName });

+  // Provider-agnostic: init-cli-agent creates a default group and emits its id.
+  // Surface that id so the orchestrator can set the picked provider on it (via
+  // ncl) before the ping — provider is a DB property, never a creation flag.
+  let stdout = '';
  try {
-    execFileSync('pnpm', scriptArgs, {
+    stdout = execFileSync('pnpm', scriptArgs, {
      cwd: projectRoot,
      stdio: ['ignore', 'pipe', 'pipe'],
      encoding: 'utf-8',
@@ -90,10 +94,13 @@ export async function run(args: string[]): Promise<void> {
    process.exit(1);
  }

+  const agentGroupId = stdout.match(/^AGENT_GROUP_ID:\s*(\S+)/m)?.[1];
+
  emitStatus('CLI_AGENT', {
    DISPLAY_NAME: displayName,
    AGENT_NAME: agentName || displayName,
    CHANNEL: 'cli/local',
+    ...(agentGroupId ? { AGENT_GROUP_ID: agentGroupId } : {}),
    STATUS: 'success',
    LOG: 'logs/setup.log',
  });
@@ -35,6 +35,29 @@ export function readEnvKey(key: string, projectRoot?: string): string | null {
  return null;
 }

+/**
+ * Set (or replace) a single `KEY=value` line in `.env`, creating the file if
+ * needed. Non-secret config only — secrets belong in the OneCLI vault.
+ */
+export function upsertEnvKey(key: string, value: string, projectRoot?: string): void {
+  const envPath = path.join(projectRoot ?? process.cwd(), '.env');
+  let content = '';
+  try {
+    content = fs.readFileSync(envPath, 'utf-8');
+  } catch {
+    /* no .env yet */
+  }
+  const line = `${key}=${value}`;
+  const lines = content.split('\n');
+  const idx = lines.findIndex((l) => l.trim().startsWith(`${key}=`));
+  if (idx >= 0) lines[idx] = line;
+  else {
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+    lines.push(line);
+  }
+  fs.writeFileSync(envPath, lines.join('\n') + '\n');
+}
+
 export function detectExistingDisplayName(projectRoot: string): string | null {
  const dbPath = path.join(projectRoot, 'data', 'v2.db');
  if (!fs.existsSync(dbPath)) return null;
@@ -23,6 +23,7 @@ const STEPS: Record<
  verify: () => import('./verify.js'),
  onecli: () => import('./onecli.js'),
  auth: () => import('./auth.js'),
+  'provider-auth': () => import('./provider-auth.js'),
  'cli-agent': () => import('./cli-agent.js'),
 };

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-# Setup helper: install-slack — bundles the preflight + install commands
-# from the /add-slack skill into one idempotent script so /new-setup can
-# run them programmatically before continuing to credentials.
-#
-# Copies the Slack adapter in from the `channels` branch; appends the
-# self-registration import; installs the pinned @chat-adapter/slack package;
-# builds. All steps are safe to re-run.
-set -euo pipefail
-
-PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-cd "$PROJECT_ROOT"
-
-echo "=== NANOCLAW SETUP: INSTALL_SLACK ==="
-
-needs_install=false
-[[ -f src/channels/slack.ts ]] || needs_install=true
-grep -q "import './slack.js';" src/channels/index.ts || needs_install=true
-grep -q '"@chat-adapter/slack"' package.json || needs_install=true
-[[ -d node_modules/@chat-adapter/slack ]] || needs_install=true
-
-if ! $needs_install; then
-  echo "STATUS: already-installed"
-  echo "=== END ==="
-  exit 0
-fi
-
-echo "STEP: fetch-channels-branch"
-git fetch origin channels
-
-echo "STEP: copy-files"
-git show origin/channels:src/channels/slack.ts > src/channels/slack.ts
-
-echo "STEP: register-import"
-if ! grep -q "import './slack.js';" src/channels/index.ts; then
-  printf "import './slack.js';\n" >> src/channels/index.ts
-fi
-
-echo "STEP: pnpm-install"
-pnpm install @chat-adapter/slack@4.26.0
-
-echo "STEP: pnpm-build"
-pnpm run build
-
-echo "STATUS: installed"
-echo "=== END ==="
@@ -66,17 +66,43 @@ export interface BrightSelectOptions<T> {
  initialValue?: T;
 }

+/**
+ * Discard any stdin buffered while no prompt was reading — keypresses made
+ * during spinners and installs otherwise get consumed by the next select the
+ * instant it opens, submitting it before it ever renders for the user (a
+ * stray `↓`+`Enter` silently picks option 2). Raw-mode reads only see kernel
+ * tty data via the event loop, so the drain needs a real (short) window.
+ */
+export function flushStdin(windowMs = 50): Promise<void> {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) return resolve();
+    const wasRaw = stdin.isRaw === true;
+    stdin.setRawMode?.(true);
+    const discard = (): void => {};
+    stdin.on('data', discard);
+    stdin.resume();
+    setTimeout(() => {
+      stdin.off('data', discard);
+      stdin.pause();
+      if (!wasRaw) stdin.setRawMode?.(false);
+      resolve();
+    }, windowMs);
+  });
+}
+
 /**
 * Matches the return shape of `p.select` — resolves to the selected value
 * on submit, or to clack's cancel symbol on Ctrl-C / Esc. Callers pass
 * the result through `ensureAnswer(...)` the same way they do for
 * `p.select`.
 */
-export function brightSelect<T>(
+export async function brightSelect<T>(
  opts: BrightSelectOptions<T>,
 ): Promise<T | symbol> {
  const { message, options, initialValue } = opts;

+  await flushStdin();
  return new SelectPrompt({
    options: options as Array<{ value: T; label?: string; hint?: string }>,
    initialValue,
@@ -68,7 +68,7 @@ export const STEP_FILES: Record<string, string[]> = {
  'telegram-validate': ['setup/channels/telegram.ts'],
  'pair-telegram': ['setup/pair-telegram.ts', 'setup/channels/telegram.ts'],
  'discord-install': ['setup/add-discord.sh', 'setup/channels/discord.ts'],
-  'slack-install': ['setup/add-slack.sh', 'setup/channels/slack.ts'],
+  'slack-install': ['.claude/skills/add-slack/SKILL.md', 'scripts/skill-apply.ts', 'setup/channels/slack.ts'],
  'slack-validate': ['setup/channels/slack.ts'],
  'imessage-install': ['setup/add-imessage.sh', 'setup/channels/imessage.ts'],
  'imessage': ['setup/channels/imessage.ts'],
@@ -0,0 +1,28 @@
+/**
+ * The agent runtime the operator picked in THIS setup run.
+ *
+ * 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.
+ */
+const ENV_KEY = 'NANOCLAW_PICKED_PROVIDER';
+
+export function setPickedProvider(provider: string | undefined): void {
+  const normalized = provider?.trim().toLowerCase() || undefined;
+  if (normalized && normalized !== 'claude') {
+    process.env[ENV_KEY] = normalized;
+  } else {
+    delete process.env[ENV_KEY];
+  }
+}
+
+export function getPickedProvider(): string | undefined {
+  return process.env[ENV_KEY]?.trim().toLowerCase() || undefined;
+}
@@ -0,0 +1,48 @@
+/**
+ * versions.json is the machine-checkable source for sanctioned component
+ * versions: setup steps read it, /update-nanoclaw diffs it across updates.
+ * These tests go red if the file, the pin, or the onecli-step wiring is
+ * deleted — the pin moving back to a hardcoded constant is the regression
+ * this guards against.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { describe, expect, it } from 'vitest';
+
+import { readVersionPin } from './version-pins.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+describe('readVersionPin', () => {
+  it('resolves the onecli-gateway pin from the real versions.json', () => {
+    expect(readVersionPin('onecli-gateway')).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  it('resolves the onecli-cli pin from the real versions.json', () => {
+    expect(readVersionPin('onecli-cli')).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  it('throws for a component with no pin', () => {
+    expect(() => readVersionPin('no-such-component')).toThrow(/no pin/);
+  });
+});
+
+describe('onecli step wiring', () => {
+  it('reads its gateway pin from versions.json, not a hardcoded constant', () => {
+    const source = fs.readFileSync(path.join(here, '..', 'onecli.ts'), 'utf-8');
+    expect(source).toContain("readVersionPin('onecli-gateway')");
+    expect(source).not.toMatch(/ONECLI_GATEWAY_VERSION = '\d/);
+  });
+
+  it('reads its CLI pin from versions.json and never resolves "latest"', () => {
+    const source = fs.readFileSync(path.join(here, '..', 'onecli.ts'), 'utf-8');
+    expect(source).toContain("readVersionPin('onecli-cli')");
+    expect(source).not.toMatch(/ONECLI_CLI(?:_FALLBACK)?_VERSION = '\d/);
+    // The upstream installer and the /releases/latest redirect probe both
+    // chase "latest" — reintroducing either bypasses the sanctioned pin.
+    expect(source).not.toContain('onecli.sh/cli/install');
+    expect(source).not.toContain('/releases/latest');
+  });
+});
@@ -0,0 +1,31 @@
+/**
+ * Sanctioned version pins for external components (`versions.json` at the
+ * repo root) — the single machine-checkable source. Setup steps read their
+ * pin here; `/update-nanoclaw` diffs the file across an update and routes
+ * the user to the migration doc for any pin that moved (see CONTRIBUTING.md,
+ * "Breaking changes").
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const VERSIONS_FILE = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'versions.json',
+);
+
+/**
+ * Returns the pinned version for a component, e.g.
+ * `readVersionPin('onecli-gateway')`. Throws when the file or the pin is
+ * missing — a missing pin is an install-tree defect, not a runtime condition.
+ */
+export function readVersionPin(component: string): string {
+  const pins: unknown = JSON.parse(fs.readFileSync(VERSIONS_FILE, 'utf-8'));
+  const value = (pins as Record<string, unknown>)[component];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`versions.json has no pin for "${component}"`);
+  }
+  return value;
+}
@@ -0,0 +1,29 @@
+/**
+ * The step DETECTS gateway /v1 compatibility and warns (pointing at
+ * docs/onecli-upgrades.md) — it does not migrate the gateway; that's the
+ * agent's job via /update-nanoclaw. The verify helper must distinguish
+ * incompatible (pre-/v1 server: warn) from unreachable (transient: nothing to
+ * say) so the warning only fires on a real pre-/v1 server.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { verifyGatewayV1 } from './onecli.js';
+
+function fakeFetch(behavior: 'ok' | '404' | 'down'): typeof fetch {
+  return (async () => {
+    if (behavior === 'down') throw new Error('ECONNREFUSED');
+    return { ok: behavior === 'ok' } as Response;
+  }) as unknown as typeof fetch;
+}
+
+describe('verifyGatewayV1', () => {
+  it('ok when /v1/health answers', async () => {
+    expect(await verifyGatewayV1('http://x', fakeFetch('ok'))).toBe('ok');
+  });
+  it('incompatible when the server answers HTTP without /v1', async () => {
+    expect(await verifyGatewayV1('http://x', fakeFetch('404'))).toBe('incompatible');
+  });
+  it('unreachable on connection failure', async () => {
+    expect(await verifyGatewayV1('http://x', fakeFetch('down'))).toBe('unreachable');
+  });
+});
@@ -17,6 +17,7 @@ import os from 'os';
 import path from 'path';

 import { log } from '../src/log.js';
+import { readVersionPin } from './lib/version-pins.js';
 import { emitStatus } from './status.js';

 const LOCAL_BIN = path.join(os.homedir(), '.local', 'bin');
@@ -102,20 +103,18 @@ function writeEnvOnecliUrl(url: string): void {
  writeEnvVar('ONECLI_URL', url);
 }

-// Last-known-good CLI release. Used only if BOTH the upstream installer
-// and the redirect-based version probe fail. Bump deliberately when a
-// new CLI release ships.
-const ONECLI_GATEWAY_VERSION = '1.23.0';
-const ONECLI_CLI_FALLBACK_VERSION = '1.3.0';
+// The SANCTIONED gateway version: fresh installs pin to it. Upgrading an
+// existing gateway is NOT done here — the gateway is a separate out-of-band
+// component, and the migrator is the user's coding agent following
+// docs/onecli-upgrades.md during /update-nanoclaw. The pin lives in
+// versions.json ("onecli-gateway") so that flow can diff it across updates and
+// route the agent to the doc; bump it there deliberately on a new release.
+const ONECLI_GATEWAY_VERSION = readVersionPin('onecli-gateway');
+// The CLI binary follows the same convention: installed at its pin
+// ("onecli-cli" in versions.json), never at whatever "latest" means today.
+const ONECLI_CLI_VERSION = readVersionPin('onecli-cli');
 const ONECLI_CLI_REPO = 'onecli/onecli-cli';

-function installOnecliCliOnly(): { stdout: string; ok: boolean } {
-  const upstream = runInstall('curl -fsSL onecli.sh/cli/install | sh');
-  if (upstream.ok) return { stdout: upstream.stdout, ok: true };
-  const fallback = installOnecliCliDirect();
-  return { stdout: upstream.stdout + (upstream.stderr ?? '') + '\n' + fallback.stdout, ok: fallback.ok };
-}
-
 // Remove containers in the "onecli" compose project whose service name isn't
 // in the v2 set. Pre-v2 OneCLI used service "app" (container onecli-app-1);
 // v2 uses "onecli". Compose flags the old container as an orphan but won't
@@ -161,24 +160,10 @@ function installOnecli(): { stdout: string; ok: boolean } {
    return { stdout: stdout + (gw.stderr ?? ''), ok: false };
  }

-  // CLI install. The upstream script calls the GitHub releases API
-  // (api.github.com) to resolve the latest tag — which 403s anonymous
-  // callers after 60 requests/hour per IP. Try upstream first; on failure
-  // resolve the version ourselves (via HTTP redirect, which isn't
-  // API-throttled) and download the release archive directly.
-  const upstream = runInstall('curl -fsSL onecli.sh/cli/install | sh');
-  stdout += upstream.stdout;
-  if (upstream.ok) return { stdout, ok: true };
-
-  log.warn('Upstream CLI installer failed — falling back to direct download', {
-    stderr: upstream.stderr,
-  });
-  stdout += (upstream.stderr ?? '') + '\n';
-
-  const fallback = installOnecliCliDirect();
-  stdout += fallback.stdout;
-  if (!fallback.ok) {
-    log.error('OneCLI CLI install failed (both upstream and direct fallback)');
+  const cli = installOnecliCliDirect();
+  stdout += cli.stdout;
+  if (!cli.ok) {
+    log.error('OneCLI CLI install failed');
    return { stdout, ok: false };
  }
  return { stdout, ok: true };
@@ -198,11 +183,11 @@ function runInstall(cmd: string): { stdout: string; stderr?: string; ok: boolean
 }

 /**
- * Reinstate the OneCLI CLI install without hitting GitHub's rate-limited
- * releases API. Resolves the version via the HTTP redirect from
- * /releases/latest → /releases/tag/vX.Y.Z, then downloads the archive
- * directly. Falls back to ONECLI_CLI_FALLBACK_VERSION if the redirect
- * probe also fails.
+ * Install the OneCLI CLI at the sanctioned pin by downloading the release
+ * archive straight from GitHub. Deliberately no "latest" resolution — the
+ * upstream installer script always chases the newest release, which would
+ * drift from the pin. PATH setup is not lost by skipping it:
+ * ensureShellProfilePath() in run() covers it.
 */
 function installOnecliCliDirect(): { stdout: string; ok: boolean } {
  const lines: string[] = [];
@@ -221,24 +206,7 @@ function installOnecliCliDirect(): { stdout: string; ok: boolean } {
    return { stdout: lines.join('\n'), ok: false };
  }

-  let version: string | null = null;
-  try {
-    const redirect = execSync(
-      `curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/${ONECLI_CLI_REPO}/releases/latest`,
-      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] },
-    ).trim();
-    const m = redirect.match(/\/tag\/v?([^/]+)$/);
-    if (m) version = m[1];
-  } catch {
-    // redirect probe failed — we'll pin the fallback
-  }
-  if (!version) {
-    version = ONECLI_CLI_FALLBACK_VERSION;
-    append(`Version probe failed; installing pinned fallback ${version}.`);
-  } else {
-    append(`Resolved onecli CLI ${version} via release redirect.`);
-  }
-
+  const version = ONECLI_CLI_VERSION;
  const archive = `onecli_${version}_${osName}_${arch}.tar.gz`;
  const url = `https://github.com/${ONECLI_CLI_REPO}/releases/download/v${version}/${archive}`;
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'onecli-'));
@@ -275,6 +243,39 @@ function installOnecliCliDirect(): { stdout: string; ok: boolean } {
  }
 }

+/**
+ * /v1 API compatibility check. @onecli-sh/sdk 2.x requires the server's /v1
+ * API; servers older than the cutover answer 404 on every SDK call (permanent,
+ * but presents as transient per-spawn failures). This is detect-only — setup
+ * does not migrate the gateway. The upgrade is an out-of-band action on a
+ * separate component that the agent runs via docs/onecli-upgrades.md during
+ * /update-nanoclaw, so this step only surfaces the condition and points there.
+ */
+export async function verifyGatewayV1(
+  url: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<'ok' | 'incompatible' | 'unreachable'> {
+  try {
+    const res = await fetchImpl(`${url}/v1/health`, { signal: AbortSignal.timeout(5000) });
+    return res.ok ? 'ok' : 'incompatible';
+  } catch {
+    return 'unreachable';
+  }
+}
+
+/**
+ * Detect-and-warn helper: returns a status HINT (and logs) when the gateway is
+ * pre-/v1, else null. Never fails the step or auto-upgrades — the agent owns
+ * the upgrade via docs/onecli-upgrades.md.
+ */
+function gatewayV1Hint(result: 'ok' | 'incompatible' | 'unreachable'): string | null {
+  if (result !== 'incompatible') return null;
+  log.warn('OneCLI gateway lacks the /v1 API @onecli-sh/sdk 2.x requires', {
+    pin: ONECLI_GATEWAY_VERSION,
+  });
+  return 'OneCLI gateway lacks the /v1 API @onecli-sh/sdk 2.x requires — upgrade it: docs/onecli-upgrades.md';
+}
+
 export async function pollHealth(url: string, timeoutMs: number): Promise<boolean> {
  // `/api/health` matches the path probe.sh uses — keep them aligned.
  const deadline = Date.now() + timeoutMs;
@@ -300,7 +301,7 @@ export async function run(args: string[]): Promise<void> {
    // Remote-mode: install only the CLI, point it at the remote gateway, and
    // record the URL in .env. No local gateway is started.
    log.info('Installing OneCLI CLI for remote gateway', { remoteUrl });
-    const res = installOnecliCliOnly();
+    const res = installOnecliCliDirect();
    if (!res.ok || !onecliVersion()) {
      emitStatus('ONECLI', {
        INSTALLED: false,
@@ -339,12 +340,14 @@ export async function run(args: string[]): Promise<void> {
      log.info('Wrote ONECLI_API_KEY to .env');
    }
    const healthy = await pollHealth(remoteUrl, 5000);
+    const v1Hint = healthy ? gatewayV1Hint(await verifyGatewayV1(remoteUrl)) : null;
    emitStatus('ONECLI', {
      INSTALLED: true,
      REMOTE: true,
      ONECLI_URL: remoteUrl,
      HEALTHY: healthy,
      STATUS: 'success',
+      ...(v1Hint ? { GATEWAY_HINT: v1Hint } : {}),
      LOG: 'logs/setup.log',
    });
    return;
@@ -378,12 +381,14 @@ export async function run(args: string[]): Promise<void> {
    writeEnvOnecliUrl(url);
    log.info('Reusing existing OneCLI', { url });
    const healthy = await pollHealth(url, 5000);
+    const v1Hint = healthy ? gatewayV1Hint(await verifyGatewayV1(url)) : null;
    emitStatus('ONECLI', {
      INSTALLED: true,
      REUSED: true,
      ONECLI_URL: url,
      HEALTHY: healthy,
      STATUS: 'success',
+      ...(v1Hint ? { GATEWAY_HINT: v1Hint } : {}),
      LOG: 'logs/setup.log',
    });
    return;
@@ -436,6 +441,7 @@ export async function run(args: string[]): Promise<void> {
  log.info('Wrote ONECLI_URL to .env', { url });

  const healthy = await pollHealth(url, 15000);
+  const v1Hint = healthy ? gatewayV1Hint(await verifyGatewayV1(url)) : null;

  emitStatus('ONECLI', {
    INSTALLED: true,
@@ -446,6 +452,7 @@ export async function run(args: string[]): Promise<void> {
    // The next step (auth) will surface a genuinely broken gateway via
    // `onecli secrets list`, so don't trigger rescue attempts from here.
    STATUS: 'success',
+    ...(v1Hint ? { GATEWAY_HINT: v1Hint } : {}),
    ...(healthy
      ? {}
      : {
@@ -0,0 +1,80 @@
+/**
+ * Standalone provider auth — the late-adopter entry point.
+ *
+ * Fresh installs reach a provider's auth walk-through via the setup picker;
+ * an existing install adding a provider later runs THIS instead:
+ *
+ *   pnpm exec tsx setup/index.ts --step provider-auth codex
+ *
+ * Same walk-through, same vault-only invariant, idempotent (each provider's
+ * runAuth short-circuits when its secret already exists) — and unlike
+ * re-running full setup, it touches nothing else: no install-wide default
+ * provider rewrite, no service changes. Provider install skills call this as
+ * their auth step so there is exactly one auth implementation per provider.
+ */
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+import { getSetupProvider, listSetupProviders } from './providers/registry.js';
+// Provider payloads self-register on import.
+import './providers/index.js';
+
+// Hard-wired install scripts — the audited control surface (no branch
+// enumeration). Each setup/add-<name>.sh is idempotent and self-skips when the
+// payload is already wired. Codex is the only manifest-style provider today.
+const INSTALL_SCRIPTS: Record<string, string> = {
+  codex: 'setup/add-codex.sh',
+};
+
+export async function run(args: string[]): Promise<void> {
+  const name = args[0]?.trim().toLowerCase();
+  const withAuth = listSetupProviders().filter((entry) => entry.runAuth);
+
+  if (!name) {
+    console.error(
+      `Usage: pnpm exec tsx setup/index.ts --step provider-auth <provider>\n` +
+        `Providers with an auth step: ${withAuth.map((entry) => entry.value).join(', ') || '(none installed)'}`,
+    );
+    process.exit(1);
+  }
+
+  let entry = getSetupProvider(name);
+  const script = INSTALL_SCRIPTS[name];
+  if (script) {
+    // Install OR refresh: the script is idempotent and is also the upgrade
+    // path — payload files resync and a bumped Dockerfile pin replaces the
+    // local one. Rebuild the image only when the Dockerfile actually changed
+    // (payload code is mounted, not baked).
+    const dfPath = path.join(process.cwd(), 'container', 'Dockerfile');
+    const dfBefore = fs.readFileSync(dfPath, 'utf-8');
+    console.log(`${entry ? 'Refreshing' : 'Installing'} ${name}…`);
+    execSync(`bash ${script}`, { stdio: 'inherit' });
+    if (fs.readFileSync(dfPath, 'utf-8') !== dfBefore) {
+      console.log('Dockerfile pin changed — rebuilding the container image…');
+      execSync('./container/build.sh', { stdio: 'inherit' });
+    }
+    if (!entry) {
+      await import(`./providers/${name}.js`);
+      entry = getSetupProvider(name);
+    }
+    if (!entry) {
+      console.error(`Install completed but ${name} did not register — check setup/providers/${name}.ts`);
+      process.exit(1);
+    }
+  } else if (!entry) {
+    console.error(
+      `Unknown provider: ${name}. Installed: ${listSetupProviders()
+        .map((e) => e.value)
+        .join(', ')}.`,
+    );
+    process.exit(1);
+  }
+  if (!entry.runAuth) {
+    console.error(`Provider "${name}" uses the standard auth flow — run the full setup, or /add-${name}'s steps.`);
+    process.exit(1);
+  }
+
+  await entry.runAuth();
+  await entry.runInstallCheck?.();
+}
@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Provider is a DB property of a group, set only via
+ * `ncl groups config update --provider`. The group-creation contract that a
+ * fork's coding agent and its skills depend on must carry zero provider
+ * vocabulary — no `--provider` flag passed to, parsed by, or threaded through
+ * any creation path. These guards go red if that flag creeps back in.
+ *
+ * (Prose references to the ncl surface in comments are fine — we assert the
+ * absence of the `'--provider'` arg *literal*, not the substring.)
+ */
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function read(rel: string): string {
+  return fs.readFileSync(path.join(repoRoot, rel), 'utf-8');
+}
+
+const CREATION_FILES = [
+  'scripts/init-first-agent.ts',
+  'scripts/init-cli-agent.ts',
+  'setup/register.ts',
+  'setup/cli-agent.ts',
+  'setup/channels/telegram.ts',
+  'setup/channels/discord.ts',
+  'setup/channels/slack.ts',
+  'setup/channels/whatsapp.ts',
+  'setup/channels/signal.ts',
+  'setup/channels/imessage.ts',
+  'setup/channels/teams.ts',
+];
+
+describe('creation is provider-agnostic', () => {
+  for (const file of CREATION_FILES) {
+    it(`${file} passes/parses no --provider flag`, () => {
+      const src = read(file);
+      expect(src).not.toContain("'--provider'");
+      expect(src).not.toMatch(/case '--provider'/);
+    });
+  }
+});
+
+describe('setup carries the picked provider to creation via a setup-run env var', () => {
+  it('picked-provider stashes/reads the pick in the NANOCLAW_PICKED_PROVIDER env var', () => {
+    const src = read('setup/lib/picked-provider.ts');
+    expect(src).toContain('NANOCLAW_PICKED_PROVIDER');
+    // The pick is set into process.env so child creation scripts inherit it —
+    // an in-process module global can't cross the process boundary.
+    expect(src).toMatch(/process\.env\[/);
+  });
+
+  // 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']) {
+    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/);
+    });
+  }
+});
+
+describe('codex installs from a hard-wired self-contained script', () => {
+  // The provider picker no longer enumerates a remote manifest branch (an
+  // unaudited control surface). Codex is offered in trunk and installed by its
+  // own setup/add-<name>.sh, exactly like a channel adapter.
+  it('setup/add-codex.sh exists', () => {
+    expect(fs.existsSync(path.join(repoRoot, 'setup/add-codex.sh'))).toBe(true);
+  });
+
+  it('setup/auto.ts installs the picked provider by running setup/add-<name>.sh', () => {
+    const src = read('setup/auto.ts');
+    expect(src).toContain('setup/add-${agentProvider}.sh');
+    // The removed branch-enumeration machinery must not creep back in.
+    expect(src).not.toContain('listBranchProviderManifests');
+    expect(src).not.toContain('installProviderFromBranch');
+  });
+});
@@ -0,0 +1,3 @@
+// Setup-side provider barrel. Provider payloads with their own setup surface
+// (picker entry, auth walk-through, install check) self-register on import.
+// Skills add a provider by appending one import line below.
@@ -0,0 +1,43 @@
+/**
+ * Setup-side provider registration guards.
+ *
+ * Behavior (barrel-driven): imports the real setup/providers barrel and
+ * asserts the built-in default — red if the barrel fails to evaluate.
+ * Per-provider registration guards ship WITH each provider payload (the
+ * skill copies them in), same archetype as the host/container registration
+ * tests.
+ *
+ * Structural: the picker and the standalone provider-auth step are wiring
+ * inside non-invocable entry flows (setup main, STEPS map) — assert their
+ * consumption of the registry in source, so deleting either reach-in goes red.
+ */
+import fs from 'fs';
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+
+import { getSetupProvider, listSetupProviders } from './registry.js';
+import './index.js'; // the real setup provider barrel — triggers self-registration
+
+describe('setup provider registry', () => {
+  it('always carries claude as the built-in default with the standard auth flow', () => {
+    const claude = getSetupProvider('claude');
+    expect(claude).toBeDefined();
+    expect(claude!.runAuth).toBeUndefined();
+    expect(listSetupProviders()[0]!.value).toBe('claude');
+  });
+});
+
+describe('setup flow consumes the registry (structural)', () => {
+  it('the picker renders options from listSetupProviders', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'setup', 'auto.ts'), 'utf-8');
+    expect(src).toContain('listSetupProviders()');
+    expect(src).toContain("import './providers/index.js'");
+    // The capability-keyed branch — a provider's own auth runs iff it declares one.
+    expect(src).toMatch(/providerEntry\?\.runAuth/);
+  });
+
+  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'");
+  });
+});
@@ -0,0 +1,59 @@
+/**
+ * Setup-side provider registry — the picker and the standalone `provider-auth`
+ * step render from this map instead of hardcoding provider names in the setup
+ * flow (same capability-not-name rule as the host provider-container registry).
+ *
+ * `claude` is the built-in default: it has no `runAuth` of its own, which the
+ * setup flow reads as "run the standard auth step". A provider payload adds
+ * itself by shipping a `setup/providers/<name>.ts` with a top-level
+ * `registerSetupProvider(...)` call and appending one import line to the
+ * `setup/providers/index.ts` barrel — the same shape as the host and container
+ * provider registries, guarded the same way (a barrel-driven registration test).
+ */
+import type { AssistContext } from '../lib/claude-assist.js'; // type-only — registry stays runtime-dependency-free
+
+/**
+ * Outcome of a provider-owned failure-assist hook:
+ *   - 'launched'    — the provider's debugger ran (user may have fixed things).
+ *   - 'declined'    — the user said no; do NOT offer another debugger.
+ *   - 'unavailable' — the provider's CLI can't be used here; the dispatcher
+ *                     falls back to the guarded Claude offer (never install/sign-in).
+ */
+export type FailureAssistResult = 'launched' | 'declined' | 'unavailable';
+
+export interface SetupProviderEntry {
+  value: string;
+  label: string;
+  hint: string;
+  /** Provider-owned auth walk-through (vault-only). Absent → standard auth step. */
+  runAuth?: () => Promise<void>;
+  /** Verifies the provider's payload is wired (files, barrels, Dockerfile pin). */
+  runInstallCheck?: () => Promise<void>;
+  /** Provider-owned interactive failure debugger. 'unavailable' → dispatcher
+   *  falls back to the guarded Claude offer (never install/sign-in). */
+  offerFailureAssist?: (ctx: AssistContext, projectRoot: string) => Promise<FailureAssistResult>;
+}
+
+const registry = new Map<string, SetupProviderEntry>();
+
+registry.set('claude', {
+  value: 'claude',
+  label: 'Claude',
+  hint: 'default — Anthropic subscription or API key',
+});
+
+export function registerSetupProvider(entry: SetupProviderEntry): void {
+  if (registry.has(entry.value)) {
+    throw new Error(`Setup provider already registered: ${entry.value}`);
+  }
+  registry.set(entry.value, entry);
+}
+
+export function getSetupProvider(name: string): SetupProviderEntry | undefined {
+  return registry.get(name.toLowerCase());
+}
+
+/** Claude (the default) first, then the rest in registration order. */
+export function listSetupProviders(): SetupProviderEntry[] {
+  return [...registry.values()];
+}
@@ -11,6 +11,7 @@ import { DATA_DIR } from '../src/config.js';
 import { initDb } from '../src/db/connection.js';
 import { runMigrations } from '../src/db/migrations/index.js';
 import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
+import { ensureContainerConfig } from '../src/db/container-configs.js';
 import {
  createMessagingGroup,
  createMessagingGroupAgent,
@@ -18,7 +19,6 @@ import {
  getMessagingGroupAgentByPair,
 } from '../src/db/messaging-groups.js';
 import { isValidGroupFolder } from '../src/group-folder.js';
-import { initGroupFilesystem } from '../src/group-init.js';
 import { log } from '../src/log.js';
 import { namespacedPlatformId } from '../src/platform-id.js';
 import { resolveSession, writeSessionMessage } from '../src/session-manager.js';
@@ -118,7 +118,7 @@ export async function run(args: string[]): Promise<void> {
  // Chat SDK adapters prefix, native adapters (WhatsApp/iMessage/Signal) don't.
  parsed.platformId = namespacedPlatformId(parsed.channel, parsed.platformId);

-  log.info('Registering channel', parsed);
+  log.info('Registering channel', { ...parsed });

  // Init v2 central DB
  fs.mkdirSync(path.join(projectRoot, 'data'), { recursive: true });
@@ -126,7 +126,11 @@ export async function run(args: string[]): Promise<void> {
  const db = initDb(dbPath);
  runMigrations(db);

-  // 1. Create or find agent group
+  // 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.
  let agentGroup = getAgentGroupByFolder(parsed.folder);
  if (!agentGroup) {
    const agId = generateId('ag');
@@ -140,7 +144,7 @@ export async function run(args: string[]): Promise<void> {
    agentGroup = getAgentGroupByFolder(parsed.folder)!;
    log.info('Created agent group', { id: agId, folder: parsed.folder });
  }
-  initGroupFilesystem(agentGroup);
+  ensureContainerConfig(agentGroup.id);

  // 2. Create or find messaging group
  let messagingGroup = getMessagingGroupByPlatform(parsed.channel, parsed.platformId);
@@ -26,6 +26,12 @@ vi.mock('./db/sessions.js', () => ({
 const mockWriteSessionMessage = vi.fn();
 vi.mock('./session-manager.js', () => ({
  writeSessionMessage: (...args: unknown[]) => mockWriteSessionMessage(...args),
+  openInboundDb: () => ({}),
+}));
+
+const mockCountDueMessages = vi.fn((..._args: unknown[]) => 0);
+vi.mock('./db/session-db.js', () => ({
+  countDueMessages: (...args: unknown[]) => mockCountDueMessages(...args),
 }));

 import { restartAgentGroupContainers } from './container-restart.js';
@@ -148,4 +154,21 @@ describe('restartAgentGroupContainers', () => {
    expect(mockWriteSessionMessage.mock.calls[0][1]).toBe('s1');
    expect(mockWriteSessionMessage.mock.calls[1][1]).toBe('s2');
  });
+
+  it('wakes even without a wake message when in-flight messages are pending', () => {
+    // A provider switch mid-conversation kills a container holding claimed
+    // messages — without an immediate respawn those messages stay dark until
+    // the next inbound or a slow sweep backoff.
+    mockGetSessionsByAgentGroup.mockReturnValue([makeSession('s1', 'ag1')]);
+    mockIsContainerRunning.mockReturnValue(true);
+    mockCountDueMessages.mockReturnValue(2);
+
+    restartAgentGroupContainers('ag1', 'provider switch');
+
+    const onExit = mockKillContainer.mock.calls[0][2] as () => void;
+    expect(typeof onExit).toBe('function');
+    mockGetSession.mockReturnValue(makeSession('s1', 'ag1'));
+    onExit();
+    expect(mockWakeContainer).toHaveBeenCalled();
+  });
 });
@@ -5,9 +5,10 @@
 * wakes a fresh container via the onExit callback — race-free.
 */
 import { isContainerRunning, killContainer, wakeContainer } from './container-runner.js';
+import { countDueMessages } from './db/session-db.js';
 import { getSession, getSessionsByAgentGroup } from './db/sessions.js';
 import { log } from './log.js';
-import { writeSessionMessage } from './session-manager.js';
+import { openInboundDb, writeSessionMessage } from './session-manager.js';

 /**
 * Kill all running containers for an agent group and respawn them.
@@ -40,10 +41,15 @@ export function restartAgentGroupContainers(agentGroupId: string, reason: string
        onWake: 1,
      });
    }
+    // Always respawn after the kill when there is anything to process: an
+    // explicit wake message, or in-flight messages the dying container had
+    // claimed. Without this, a provider switch mid-conversation leaves the
+    // claimed messages dark until the next inbound or a slow sweep backoff.
+    const hasPending = countDueMessages(openInboundDb(session.agent_group_id, session.id)) > 0;
    killContainer(
      session.id,
      reason,
-      wakeMessage
+      wakeMessage || hasPending
        ? () => {
            const s = getSession(session.id);
            if (s) wakeContainer(s);
@@ -1,3 +1,5 @@
+import fs from 'fs';
+import path from 'path';
 import { describe, expect, it } from 'vitest';

 import { resolveProviderName } from './container-runner.js';
@@ -25,3 +27,36 @@ describe('resolveProviderName', () => {
    expect(resolveProviderName(null, '')).toBe('claude');
  });
 });
+
+describe('buildContainerArgs ordering invariant (structural)', () => {
+  // The OneCLI gateway apply (SDK applyContainerConfig) appends credential-stub
+  // mounts — e.g. the codex auth.json sentinel nested INSIDE our RW
+  // /home/node/.codex mount. Docker applies binds in argument order, so the
+  // stub must land AFTER its parent mount or the parent shadows it and the
+  // agent silently degrades to loginless auth. Driving the real
+  // buildContainerArgs needs a live gateway + container runtime, so this
+  // guards the invariant structurally: the gateway apply must appear after
+  // the volume-mounts loop in the source.
+  it('applies the OneCLI gateway after the volume mounts', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'src', 'container-runner.ts'), 'utf-8');
+    const mountsLoop = src.indexOf('for (const mount of mounts)');
+    const gatewayApply = src.indexOf('onecli.applyContainerConfig');
+    expect(mountsLoop).toBeGreaterThan(-1);
+    expect(gatewayApply).toBeGreaterThan(-1);
+    expect(gatewayApply).toBeGreaterThan(mountsLoop);
+  });
+});
+
+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
+  // default level. The spawn handler must keep a stderr tail and surface it
+  // at warn on a non-zero exit, or the operator sees only "exited code 1" on
+  // repeat. Driving a real failing spawn needs a container runtime, so this
+  // guards the wiring structurally, matching the invariant test above.
+  it('surfaces the stderr tail when the container exits non-zero', () => {
+    const src = fs.readFileSync(path.join(process.cwd(), 'src', 'container-runner.ts'), 'utf-8');
+    expect(src).toContain('stderrTail.push(line)');
+    expect(src).toMatch(/Container exited non-zero.*stderrTail/s);
+  });
+});
@@ -21,7 +21,7 @@ import {
 } from './config.js';
 import { materializeContainerJson } from './container-config.js';
 import { getContainerConfig } from './db/container-configs.js';
-import { updateContainerConfigScalars, updateContainerConfigJson } from './db/container-configs.js';
+import { updateContainerConfigScalars } from './db/container-configs.js';
 import { CONTAINER_RUNTIME_BIN, hostGatewayArgs, readonlyMountArgs, stopContainer } from './container-runtime.js';
 import { EGRESS_NETWORK, egressNetworkArgs, ensureEgressNetwork } from './egress-lockdown.js';
 import { composeGroupClaudeMd } from './claude-md-compose.js';
@@ -36,6 +36,7 @@ import { validateAdditionalMounts } from './modules/mount-security/index.js';
 import './providers/index.js';
 import {
  getProviderContainerConfig,
+  providerProvidesAgentSurfaces,
  type ProviderContainerContribution,
  type VolumeMount,
 } from './providers/provider-container-registry.js';
@@ -127,12 +128,19 @@ async function spawnContainer(session: Session): Promise<void> {
  // and buildContainerArgs so we don't re-read.
  const containerConfig = materializeContainerJson(agentGroup.id);

+  // Per-group filesystem state lives forever after first creation. Init is
+  // idempotent: it only writes paths that don't already exist, so this call
+  // is a no-op for groups that have spawned before. Runs before the provider
+  // contribution so a surfaces-providing provider finds the group dir ready.
+  const providerName = resolveProviderName(session.agent_provider, containerConfig.provider);
+  initGroupFilesystem(agentGroup, { provider: providerName });
+
  // Resolve the effective provider + any host-side contribution it declares
  // (extra mounts, env passthrough). Computed once and threaded through both
  // buildMounts and buildContainerArgs so side effects (mkdir, etc.) fire once.
  const { provider, contribution } = resolveProviderContribution(session, agentGroup, containerConfig);

-  const mounts = buildMounts(agentGroup, session, containerConfig, contribution);
+  const mounts = buildMounts(agentGroup, session, containerConfig, provider, contribution);
  const containerName = `nanoclaw-v2-${agentGroup.folder}-${Date.now()}`;
  // OneCLI agent identifier is always the agent group id — stable across
  // sessions and reversible via getAgentGroup() for approval routing.
@@ -160,10 +168,16 @@ async function spawnContainer(session: Session): Promise<void> {
  activeContainers.set(session.id, { process: container, containerName });
  markContainerRunning(session.id);

-  // Log stderr
+  // Log stderr. A container that dies at boot (unknown provider, missing
+  // binary, bad config) explains itself only here — and debug is below the
+  // default log level — so keep a tail to surface on a non-zero exit.
+  const stderrTail: string[] = [];
  container.stderr?.on('data', (data) => {
    for (const line of data.toString().trim().split('\n')) {
-      if (line) log.debug(line, { container: agentGroup.folder });
+      if (!line) continue;
+      log.debug(line, { container: agentGroup.folder });
+      stderrTail.push(line);
+      if (stderrTail.length > 10) stderrTail.shift();
    }
  });

@@ -179,7 +193,12 @@ async function spawnContainer(session: Session): Promise<void> {
    activeContainers.delete(session.id);
    markContainerStopped(session.id);
    stopTypingRefresh(session.id);
-    log.info('Container exited', { sessionId: session.id, code, containerName });
+    // code null = killed by signal (normal shutdown path), not a boot failure.
+    if (code !== 0 && code !== null && stderrTail.length > 0) {
+      log.warn('Container exited non-zero', { sessionId: session.id, code, containerName, stderrTail });
+    } else {
+      log.info('Container exited', { sessionId: session.id, code, containerName });
+    }
  });

  container.on('error', (err) => {
@@ -234,32 +253,37 @@ function resolveProviderContribution(
    ? fn({
        sessionDir: sessionDir(agentGroup.id, session.id),
        agentGroupId: agentGroup.id,
+        groupDir: path.resolve(GROUPS_DIR, agentGroup.folder),
+        selectedSkills: selectedSkillNames(containerConfig),
        hostEnv: process.env,
      })
    : {};
  return { provider, contribution };
 }

-function buildMounts(
+export function buildMounts(
  agentGroup: AgentGroup,
  session: Session,
  containerConfig: import('./container-config.js').ContainerConfig,
+  provider: string,
  providerContribution: ProviderContainerContribution,
 ): VolumeMount[] {
  const projectRoot = process.cwd();

-  // Per-group filesystem state lives forever after first creation. Init is
-  // idempotent: it only writes paths that don't already exist, so this call
-  // is a no-op for groups that have spawned before.
-  initGroupFilesystem(agentGroup);
+  // Default agent surfaces (composed project doc, skill links, provider state
+  // dir) apply unless the provider's registration declares it provides its
+  // own — a capability, never a provider name. See provider-container-registry.
+  const defaultSurfaces = !providerProvidesAgentSurfaces(provider);

-  // Sync skill symlinks based on container.json selection before mounting.
  const claudeDir = path.join(DATA_DIR, 'v2-sessions', agentGroup.id, '.claude-shared');
-  syncSkillSymlinks(claudeDir, containerConfig);
+  if (defaultSurfaces) {
+    // Sync skill symlinks based on container.json selection before mounting.
+    syncSkillSymlinks(claudeDir, containerConfig);

-  // Compose CLAUDE.md fresh every spawn from the shared base, enabled skill
-  // fragments, and MCP server instructions. See `claude-md-compose.ts`.
-  composeGroupClaudeMd(agentGroup);
+    // Compose CLAUDE.md fresh every spawn from the shared base, enabled skill
+    // fragments, and MCP server instructions. See `claude-md-compose.ts`.
+    composeGroupClaudeMd(agentGroup);
+  }

  const mounts: VolumeMount[] = [];
  const sessDir = sessionDir(agentGroup.id, session.id);
@@ -286,11 +310,11 @@ function buildMounts(
  // already RO-mounted, so writes through it fail regardless — no need for
  // a nested mount there.
  const composedClaudeMd = path.join(groupDir, 'CLAUDE.md');
-  if (fs.existsSync(composedClaudeMd)) {
+  if (defaultSurfaces && fs.existsSync(composedClaudeMd)) {
    mounts.push({ hostPath: composedClaudeMd, containerPath: '/workspace/agent/CLAUDE.md', readonly: true });
  }
  const fragmentsDir = path.join(groupDir, '.claude-fragments');
-  if (fs.existsSync(fragmentsDir)) {
+  if (defaultSurfaces && fs.existsSync(fragmentsDir)) {
    mounts.push({ hostPath: fragmentsDir, containerPath: '/workspace/agent/.claude-fragments', readonly: true });
  }

@@ -303,13 +327,15 @@ function buildMounts(
  // Shared CLAUDE.md — read-only, imported by the composed entry point via
  // the `.claude-shared.md` symlink inside the group dir.
  const sharedClaudeMd = path.join(process.cwd(), 'container', 'CLAUDE.md');
-  if (fs.existsSync(sharedClaudeMd)) {
+  if (defaultSurfaces && fs.existsSync(sharedClaudeMd)) {
    mounts.push({ hostPath: sharedClaudeMd, containerPath: '/app/CLAUDE.md', readonly: true });
  }

  // Per-group .claude-shared at /home/node/.claude (Claude state, settings,
  // skill symlinks)
-  mounts.push({ hostPath: claudeDir, containerPath: '/home/node/.claude', readonly: false });
+  if (defaultSurfaces) {
+    mounts.push({ hostPath: claudeDir, containerPath: '/home/node/.claude', readonly: false });
+  }

  // Shared agent-runner source — read-only, same code for all groups.
  const agentRunnerSrc = path.join(projectRoot, 'container', 'agent-runner', 'src');
@@ -346,25 +372,7 @@ function syncSkillSymlinks(claudeDir: string, containerConfig: import('./contain
    fs.mkdirSync(skillsDir, { recursive: true });
  }

-  // Determine desired skill set
-  const projectRoot = process.cwd();
-  const sharedSkillsDir = path.join(projectRoot, 'container', 'skills');
-  let desired: string[];
-  if (containerConfig.skills === 'all') {
-    // Recompute from shared dir — newly-added upstream skills appear automatically
-    desired = fs.existsSync(sharedSkillsDir)
-      ? fs.readdirSync(sharedSkillsDir).filter((e) => {
-          try {
-            return fs.statSync(path.join(sharedSkillsDir, e)).isDirectory();
-          } catch {
-            return false;
-          }
-        })
-      : [];
-  } else {
-    desired = containerConfig.skills;
-  }
-
+  const desired = selectedSkillNames(containerConfig);
  const desiredSet = new Set(desired);

  // Remove symlinks not in the desired set
@@ -397,12 +405,30 @@ function syncSkillSymlinks(claudeDir: string, containerConfig: import('./contain
  }
 }

+/**
+ * Resolve the group's skill selection to concrete names — `'all'` recomputes
+ * from `container/skills/` so newly-added upstream skills appear automatically.
+ */
+function selectedSkillNames(containerConfig: import('./container-config.js').ContainerConfig): string[] {
+  if (containerConfig.skills !== 'all') return containerConfig.skills;
+  const sharedSkillsDir = path.join(process.cwd(), 'container', 'skills');
+  return fs.existsSync(sharedSkillsDir)
+    ? fs.readdirSync(sharedSkillsDir).filter((e) => {
+        try {
+          return fs.statSync(path.join(sharedSkillsDir, e)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+    : [];
+}
+
 async function buildContainerArgs(
  mounts: VolumeMount[],
  containerName: string,
  agentGroup: AgentGroup,
  containerConfig: import('./container-config.js').ContainerConfig,
-  provider: string,
+  _provider: string,
  providerContribution: ProviderContainerContribution,
  agentIdentifier?: string,
 ): Promise<string[]> {
@@ -419,20 +445,6 @@ async function buildContainerArgs(
    }
  }

-  // OneCLI gateway — injects HTTPS_PROXY + certs so container API calls
-  // are routed through the agent vault for credential injection. Treated as
-  // a transient hard failure: if we can't wire the gateway, we don't spawn.
-  // The caller (router or host-sweep) catches the throw, leaves the inbound
-  // message pending, and the next sweep tick retries.
-  if (agentIdentifier) {
-    await onecli.ensureAgent({ name: agentGroup.name, identifier: agentIdentifier });
-  }
-  const onecliApplied = await onecli.applyContainerConfig(args, { addHostMapping: false, agent: agentIdentifier });
-  if (!onecliApplied) {
-    throw new Error('OneCLI gateway not applied — refusing to spawn container without credentials');
-  }
-  log.info('OneCLI gateway applied', { containerName });
-
  // Egress lockdown when enabled — throws if it can't be established, aborting
  // the spawn rather than running with open egress. Otherwise the host gateway.
  if (ensureEgressNetwork()) {
@@ -459,6 +471,24 @@ async function buildContainerArgs(
    }
  }

+  // OneCLI gateway — injects HTTPS_PROXY + certs so container API calls
+  // are routed through the agent vault for credential injection, and mounts
+  // any credential stubs the gateway serves (e.g. a sentinel auth file).
+  // Runs AFTER the volume mounts so a stub nested inside one of our mounts
+  // (a parent dir mounted RW above it) lands later in the args and isn't
+  // shadowed by it. Treated as a transient hard failure: if we can't wire
+  // the gateway, we don't spawn. The caller (router or host-sweep) catches
+  // the throw, leaves the inbound message pending, and the next sweep tick
+  // retries.
+  if (agentIdentifier) {
+    await onecli.ensureAgent({ name: agentGroup.name, identifier: agentIdentifier });
+  }
+  const onecliApplied = await onecli.applyContainerConfig(args, { addHostMapping: false, agent: agentIdentifier });
+  if (!onecliApplied) {
+    throw new Error('OneCLI gateway not applied — refusing to spawn container without credentials');
+  }
+  log.info('OneCLI gateway applied', { containerName });
+
  // Override entrypoint: run v2 entry point directly via Bun (no tsc, no stdin).
  args.push('--entrypoint', 'bash');

@@ -4,6 +4,7 @@ import path from 'path';
 import { DATA_DIR, 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';
 import type { AgentGroup } from './types.js';

 const DEFAULT_SETTINGS_JSON =
@@ -46,9 +47,18 @@ const DEFAULT_SETTINGS_JSON =
 * spawn by `composeGroupClaudeMd()` (see `claude-md-compose.ts`). Initial
 * per-group instructions (if provided) seed `CLAUDE.local.md`.
 */
-export function initGroupFilesystem(group: AgentGroup, opts?: { instructions?: string }): void {
+export function initGroupFilesystem(
+  group: AgentGroup,
+  opts?: { instructions?: string; provider?: string | null },
+): 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);
+
  // 1. groups/<folder>/ — group memory + working dir
  const groupDir = path.resolve(GROUPS_DIR, group.folder);
  if (!fs.existsSync(groupDir)) {
@@ -56,13 +66,43 @@ export function initGroupFilesystem(group: AgentGroup, opts?: { instructions?: s
    initialized.push('groupDir');
  }

-  // groups/<folder>/CLAUDE.local.md — per-group agent memory, auto-loaded by
-  // Claude Code. Seeded with caller-provided instructions on first creation.
-  const claudeLocalFile = path.join(groupDir, 'CLAUDE.local.md');
-  if (!fs.existsSync(claudeLocalFile)) {
-    const body = opts?.instructions ? opts.instructions + '\n' : '';
-    fs.writeFileSync(claudeLocalFile, body);
-    initialized.push('CLAUDE.local.md');
+  // Seed instructions land in the provider's OWN memory surface. Default
+  // (Claude) surfaces auto-load CLAUDE.local.md natively. A surfaces-owning
+  // provider must never see stale CLAUDE.* files in its workspace — its seed
+  // goes into the memory scaffold's conventional landing file instead
+  // (memory/memories/imported-agent-memory.md): the container-side scaffold
+  // preserves pre-existing files, and the doctrine tells the agent to read
+  // that file on its first turn.
+  //
+  // Creation stays provider-agnostic: a DM-agent creator drops the seed in a
+  // neutral `.seed.md`, and placement is deferred to here (the first spawn,
+  // where the DB-resolved provider is known). Once placed it's consumed.
+  // `opts.instructions` still wins for any caller that passes it inline.
+  const neutralSeedFile = path.join(groupDir, '.seed.md');
+  const seed =
+    opts?.instructions ??
+    (fs.existsSync(neutralSeedFile) ? fs.readFileSync(neutralSeedFile, 'utf-8').trimEnd() : undefined);
+
+  if (defaultSurfaces) {
+    const claudeLocalFile = path.join(groupDir, 'CLAUDE.local.md');
+    if (!fs.existsSync(claudeLocalFile)) {
+      fs.writeFileSync(claudeLocalFile, seed ? seed + '\n' : '');
+      initialized.push('CLAUDE.local.md');
+    }
+  } else if (seed) {
+    const seedFile = path.join(groupDir, 'memory', 'memories', 'imported-agent-memory.md');
+    if (!fs.existsSync(seedFile)) {
+      fs.mkdirSync(path.dirname(seedFile), { recursive: true });
+      fs.writeFileSync(seedFile, seed + '\n');
+      initialized.push('memory/memories/imported-agent-memory.md');
+    }
+  }
+
+  // The neutral seed is single-use — drop it once the surface it belonged in
+  // has been resolved, so it can't re-seed after the operator edits theirs.
+  if (fs.existsSync(neutralSeedFile)) {
+    fs.rmSync(neutralSeedFile);
+    initialized.push('.seed.md consumed');
  }

  // Ensure container_configs row exists in the DB. Idempotent — no-op if
@@ -71,26 +111,28 @@ export function initGroupFilesystem(group: AgentGroup, opts?: { instructions?: s
  initialized.push('container_configs');

  // 2. data/v2-sessions/<id>/.claude-shared/ — Claude state + per-group skills
-  const claudeDir = path.join(DATA_DIR, 'v2-sessions', group.id, '.claude-shared');
-  if (!fs.existsSync(claudeDir)) {
-    fs.mkdirSync(claudeDir, { recursive: true });
-    initialized.push('.claude-shared');
-  }
+  if (defaultSurfaces) {
+    const claudeDir = path.join(DATA_DIR, 'v2-sessions', group.id, '.claude-shared');
+    if (!fs.existsSync(claudeDir)) {
+      fs.mkdirSync(claudeDir, { recursive: true });
+      initialized.push('.claude-shared');
+    }

-  const settingsFile = path.join(claudeDir, 'settings.json');
-  if (!fs.existsSync(settingsFile)) {
-    fs.writeFileSync(settingsFile, DEFAULT_SETTINGS_JSON);
-    initialized.push('settings.json');
-  } else {
-    ensurePreCompactHook(settingsFile, initialized);
-  }
+    const settingsFile = path.join(claudeDir, 'settings.json');
+    if (!fs.existsSync(settingsFile)) {
+      fs.writeFileSync(settingsFile, DEFAULT_SETTINGS_JSON);
+      initialized.push('settings.json');
+    } else {
+      ensurePreCompactHook(settingsFile, initialized);
+    }

-  // Skills directory — created empty here; symlinks are synced at spawn
-  // time by container-runner.ts based on container.json skills selection.
-  const skillsDst = path.join(claudeDir, 'skills');
-  if (!fs.existsSync(skillsDst)) {
-    fs.mkdirSync(skillsDst, { recursive: true });
-    initialized.push('skills/');
+    // Skills directory — created empty here; symlinks are synced at spawn
+    // time by container-runner.ts based on container.json skills selection.
+    const skillsDst = path.join(claudeDir, 'skills');
+    if (!fs.existsSync(skillsDst)) {
+      fs.mkdirSync(skillsDst, { recursive: true });
+      initialized.push('skills/');
+    }
  }

  if (initialized.length > 0) {
@@ -16,6 +16,7 @@ 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();

@@ -24,6 +25,8 @@ 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: '' }),
@@ -75,6 +78,29 @@ describe('handleCreateAgent — scope-based authorization', () => {
    expect(mockInitGroupFilesystem).toHaveBeenCalledTimes(1);
  });

+  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).
+    mockGetContainerConfig.mockReturnValue({ cli_scope: 'global', provider: 'codex' });
+
+    await handleCreateAgent({ name: 'Scout', instructions: 'help' }, SESSION);
+
+    expect(mockInitGroupFilesystem).toHaveBeenCalledWith(
+      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
+
+    await handleCreateAgent({ name: 'Scout', instructions: 'help' }, SESSION);
+
+    expect(mockUpdateScalars).not.toHaveBeenCalled();
+  });
+
  it('group scope (default): requires approval, does NOT create directly', async () => {
    mockGetContainerConfig.mockReturnValue({ cli_scope: 'group' });

@@ -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 } from '../../db/container-configs.js';
+import { getContainerConfig, updateContainerConfigScalars } from '../../db/container-configs.js';
 import { getSession } from '../../db/sessions.js';
 import { wakeContainer } from '../../container-runner.js';
 import { initGroupFilesystem } from '../../group-init.js';
@@ -163,7 +163,17 @@ async function performCreateAgent(
    created_at: now,
  };
  createAgentGroup(newGroup);
-  initGroupFilesystem(newGroup, { instructions: instructions ?? undefined });
+  // 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
+  // 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;
+  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".
@@ -292,6 +292,8 @@ 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`.
  initGroupFilesystem(ag);
  return ag;
 }
@@ -0,0 +1,195 @@
+import fs from 'fs';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const TEST_ROOT = '/tmp/nanoclaw-provider-surfaces-test';
+const GROUPS_DIR = path.join(TEST_ROOT, 'groups');
+const DATA_DIR = path.join(TEST_ROOT, 'data');
+
+vi.mock('./config.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./config.js')>()),
+  DATA_DIR: '/tmp/nanoclaw-provider-surfaces-test/data',
+  GROUPS_DIR: '/tmp/nanoclaw-provider-surfaces-test/groups',
+}));
+
+vi.mock('./log.js', () => ({
+  log: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    fatal: vi.fn(),
+  },
+}));
+
+import { buildMounts } from './container-runner.js';
+import { closeDb, createAgentGroup, initTestDb, runMigrations } from './db/index.js';
+import { ensureContainerConfig } from './db/container-configs.js';
+import { initGroupFilesystem } from './group-init.js';
+import { registerProviderContainerConfig } from './providers/provider-container-registry.js';
+import type { ContainerConfig } from './container-config.js';
+import type { AgentGroup, Session } from './types.js';
+
+// A provider that declares (at registration) that it owns its agent surfaces.
+// Registered once — the registry is module-global and rejects duplicates.
+registerProviderContainerConfig('surfaces-test-provider', () => ({}), { providesAgentSurfaces: true });
+
+function group(id: string, folder: string): AgentGroup {
+  return { id, name: folder, folder, agent_provider: null, created_at: new Date().toISOString() } as AgentGroup;
+}
+
+function session(id: string, agentGroupId: string): Session {
+  return { id, agent_group_id: agentGroupId } as Session;
+}
+
+function containerConfig(): ContainerConfig {
+  return { mcpServers: {}, packages: { apt: [], npm: [] }, additionalMounts: [], skills: [] };
+}
+
+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('initGroupFilesystem agent surfaces', () => {
+  it('writes the default surfaces when no provider is given (today’s behavior)', () => {
+    const ag = group('ag-default', 'default-group');
+    createAgentGroup(ag);
+
+    initGroupFilesystem(ag, { instructions: 'hello' });
+
+    const groupDir = path.join(GROUPS_DIR, ag.folder);
+    const claudeDir = path.join(DATA_DIR, 'v2-sessions', ag.id, '.claude-shared');
+    expect(fs.readFileSync(path.join(groupDir, 'CLAUDE.local.md'), 'utf-8')).toBe('hello\n');
+    expect(fs.existsSync(path.join(claudeDir, 'settings.json'))).toBe(true);
+    expect(fs.existsSync(path.join(claudeDir, 'skills'))).toBe(true);
+  });
+
+  it('writes the seed into the memory scaffold — never CLAUDE.* — for a provider with its own surfaces', () => {
+    const ag = group('ag-surfy', 'surfy-group');
+    createAgentGroup(ag);
+
+    initGroupFilesystem(ag, { instructions: 'hello', provider: 'surfaces-test-provider' });
+
+    const groupDir = path.join(GROUPS_DIR, ag.folder);
+    const sessionRoot = path.join(DATA_DIR, 'v2-sessions', ag.id);
+    expect(fs.existsSync(groupDir)).toBe(true);
+    // A fresh group on a surfaces-owning provider must not contain stale
+    // Claude surfaces; its seed lands in the scaffold's conventional file,
+    // which the container-side scaffold preserves at boot.
+    expect(fs.existsSync(path.join(groupDir, 'CLAUDE.local.md'))).toBe(false);
+    expect(fs.readFileSync(path.join(groupDir, 'memory', 'memories', 'imported-agent-memory.md'), 'utf-8')).toBe(
+      'hello\n',
+    );
+    expect(fs.existsSync(path.join(sessionRoot, '.claude-shared'))).toBe(false);
+  });
+
+  it('writes nothing at all for a surfaces-owning provider without instructions', () => {
+    const ag = group('ag-surfy-bare', 'surfy-bare-group');
+    createAgentGroup(ag);
+
+    initGroupFilesystem(ag, { provider: 'surfaces-test-provider' });
+
+    const groupDir = path.join(GROUPS_DIR, ag.folder);
+    expect(fs.existsSync(path.join(groupDir, 'CLAUDE.local.md'))).toBe(false);
+    expect(fs.existsSync(path.join(groupDir, 'memory'))).toBe(false);
+  });
+
+  it('treats an unregistered provider name as default surfaces', () => {
+    const ag = group('ag-unknown', 'unknown-group');
+    createAgentGroup(ag);
+
+    initGroupFilesystem(ag, { provider: 'not-registered' });
+
+    expect(fs.existsSync(path.join(GROUPS_DIR, ag.folder, 'CLAUDE.local.md'))).toBe(true);
+  });
+});
+
+describe('initGroupFilesystem deferred seed (.seed.md)', () => {
+  // Creation is provider-agnostic: the DM-agent creators drop a neutral
+  // `.seed.md` and defer placement to the first spawn, where the DB-resolved
+  // provider is known. group-init places it into the right surface and
+  // consumes it. Red-on-delete: if that placement is removed, these fail.
+  it('places .seed.md into CLAUDE.local.md for the default provider, then consumes it', () => {
+    const ag = group('ag-seed-default', 'seed-default');
+    createAgentGroup(ag);
+    const groupDir = path.join(GROUPS_DIR, ag.folder);
+    fs.mkdirSync(groupDir, { recursive: true });
+    fs.writeFileSync(path.join(groupDir, '.seed.md'), 'seeded identity\n');
+
+    initGroupFilesystem(ag, {}); // no inline instructions — must read .seed.md
+
+    expect(fs.readFileSync(path.join(groupDir, 'CLAUDE.local.md'), 'utf-8')).toBe('seeded identity\n');
+    expect(fs.existsSync(path.join(groupDir, '.seed.md'))).toBe(false);
+  });
+
+  it('places .seed.md into the memory scaffold (never CLAUDE.*) for a surfaces-owning provider, then consumes it', () => {
+    const ag = group('ag-seed-surfy', 'seed-surfy');
+    createAgentGroup(ag);
+    const groupDir = path.join(GROUPS_DIR, ag.folder);
+    fs.mkdirSync(groupDir, { recursive: true });
+    fs.writeFileSync(path.join(groupDir, '.seed.md'), 'seeded identity\n');
+
+    initGroupFilesystem(ag, { provider: 'surfaces-test-provider' });
+
+    expect(fs.existsSync(path.join(groupDir, 'CLAUDE.local.md'))).toBe(false);
+    expect(fs.readFileSync(path.join(groupDir, 'memory', 'memories', 'imported-agent-memory.md'), 'utf-8')).toBe(
+      'seeded identity\n',
+    );
+    expect(fs.existsSync(path.join(groupDir, '.seed.md'))).toBe(false);
+  });
+});
+
+describe('buildMounts agent surfaces', () => {
+  it('mounts the default surfaces for an unregistered provider (today’s behavior)', () => {
+    const ag = group('ag-mounts-default', 'mounts-default');
+    createAgentGroup(ag);
+    ensureContainerConfig(ag.id);
+    initGroupFilesystem(ag, {});
+
+    const mounts = buildMounts(ag, session('s1', ag.id), containerConfig(), 'claude', {});
+
+    const byContainerPath = new Map(mounts.map((m) => [m.containerPath, m]));
+    expect(byContainerPath.has('/home/node/.claude')).toBe(true);
+    expect(byContainerPath.has('/app/CLAUDE.md')).toBe(true);
+    expect(byContainerPath.has('/workspace/agent/CLAUDE.md')).toBe(true);
+    // Composer ran: the generated project doc exists on disk.
+    expect(fs.existsSync(path.join(GROUPS_DIR, ag.folder, 'CLAUDE.md'))).toBe(true);
+  });
+
+  it('suppresses the default surfaces and keeps contributed mounts for a surfaces-providing provider', () => {
+    const ag = group('ag-mounts-surfy', 'mounts-surfy');
+    createAgentGroup(ag);
+    ensureContainerConfig(ag.id);
+    initGroupFilesystem(ag, { provider: 'surfaces-test-provider' });
+
+    const contributed = {
+      mounts: [
+        {
+          hostPath: path.join(GROUPS_DIR, ag.folder),
+          containerPath: '/workspace/agent/OWN-DOC.md',
+          readonly: true,
+        },
+      ],
+    };
+    const mounts = buildMounts(ag, session('s2', ag.id), containerConfig(), 'surfaces-test-provider', contributed);
+
+    const containerPaths = mounts.map((m) => m.containerPath);
+    expect(containerPaths).not.toContain('/home/node/.claude');
+    expect(containerPaths).not.toContain('/app/CLAUDE.md');
+    expect(containerPaths).not.toContain('/workspace/agent/CLAUDE.md');
+    // Composer did NOT run for this group.
+    expect(fs.existsSync(path.join(GROUPS_DIR, ag.folder, 'CLAUDE.md'))).toBe(false);
+    // Core mounts and the provider's own contribution are intact.
+    expect(containerPaths).toContain('/workspace');
+    expect(containerPaths).toContain('/workspace/agent');
+    expect(containerPaths).toContain('/app/src');
+    expect(containerPaths).toContain('/workspace/agent/OWN-DOC.md');
+  });
+});
@@ -27,6 +27,19 @@ export interface ProviderContainerContext {
  sessionDir: string;
  /** Agent group ID, for any per-group logic. */
  agentGroupId: string;
+  /**
+   * Per-group host directory: `<GROUPS_DIR>/<folder>` (mounted RW at
+   * `/workspace/agent`). Exists by the time the config fn runs — group
+   * filesystem init happens first. Surfaces-providing providers compose
+   * their project doc and skill links here.
+   */
+  groupDir: string;
+  /**
+   * Skill names selected by the group's container config, with `'all'`
+   * already resolved against `container/skills/`. Surfaces-providing
+   * providers use this to sync their own skill-discovery links.
+   */
+  selectedSkills: string[];
  /** `process.env` at spawn time — pull passthrough values from here. */
  hostEnv: NodeJS.ProcessEnv;
 }
@@ -38,19 +51,56 @@ export interface ProviderContainerContribution {
  env?: Record<string, string>;
 }

+/**
+ * Static capabilities a provider declares at registration time — knowable
+ * without a spawn context, so any host path (group init, spawn, creation
+ * flows) can consult them by name.
+ */
+export interface ProviderHostCapabilities {
+  /**
+   * Optional. When true, this provider owns its agent-facing surfaces — the
+   * composed project doc, skill-discovery links, and provider state dir —
+   * and the host must NOT compose or mount the default ones (composed
+   * CLAUDE.md, `.claude-fragments`, `/app/CLAUDE.md`, `/home/node/.claude`,
+   * `CLAUDE.local.md` seeding). The provider's config fn does its own
+   * composing and returns its own mounts. Default off — providers that omit
+   * this get the default surfaces, which is today's behavior.
+   */
+  readonly providesAgentSurfaces?: boolean;
+}
+
 export type ProviderContainerConfigFn = (ctx: ProviderContainerContext) => ProviderContainerContribution;

-const registry = new Map<string, ProviderContainerConfigFn>();
+interface RegistryEntry {
+  fn: ProviderContainerConfigFn;
+  capabilities: ProviderHostCapabilities;
+}

-export function registerProviderContainerConfig(name: string, fn: ProviderContainerConfigFn): void {
+const registry = new Map<string, RegistryEntry>();
+
+export function registerProviderContainerConfig(
+  name: string,
+  fn: ProviderContainerConfigFn,
+  capabilities: ProviderHostCapabilities = {},
+): void {
  if (registry.has(name)) {
    throw new Error(`Provider container config already registered: ${name}`);
  }
-  registry.set(name, fn);
+  registry.set(name, { fn, capabilities });
 }

 export function getProviderContainerConfig(name: string): ProviderContainerConfigFn | undefined {
-  return registry.get(name);
+  return registry.get(name)?.fn;
+}
+
+/**
+ * Capability lookup by provider name. Unregistered providers (including the
+ * baked-in default) report no capabilities — the host applies its default
+ * surfaces, exactly as before this seam existed.
+ */
+export function providerProvidesAgentSurfaces(name: string | null | undefined): boolean {
+  if (!name) return false;
+  return registry.get(name)?.capabilities.providesAgentSurfaces === true;
 }

 export function listProviderContainerConfigNames(): string[] {
@@ -0,0 +1,4 @@
+{
+  "onecli-gateway": "1.36.0",
+  "onecli-cli": "2.2.5"
+}
@@ -4,6 +4,8 @@ export default defineConfig({
  test: {
    // container/agent-runner tests run under Bun (they depend on bun:sqlite).
    // See container/agent-runner/package.json "test" script.
-    include: ['src/**/*.test.ts', 'setup/**/*.test.ts', 'scripts/**/*.test.ts'],
+    // container/*.test.ts: top-level only — container/agent-runner tests run
+    // under Bun (they depend on bun:sqlite) and must not be picked up here.
+    include: ['src/**/*.test.ts', 'setup/**/*.test.ts', 'scripts/**/*.test.ts', 'container/*.test.ts'],
  },
 });
Author	SHA1	Message	Date
gavrielc	ae48986e42	feat(skills): structured nc: directive format + apply engine, first applied to Slack Introduces the optionally-deterministic skill format. Official skills carry `nc:` directive fences (copy/append/dep/run/prompt/env-set/env-sync) embedded in prose, so one SKILL.md is both agent-readable and machine-appliable. Robustness lives in the whole system — graceful degradation to an agent, plus lint + tests — not in the syntax, so the directives stay minimal and readable. scripts/skill-directives.ts — parser + linter. Extracts nc: directives; flags unpinned deps, undefined {{var}} references, and a @chat-adapter/* pin that doesn't match our lockfile's `chat` core (the drift that put add-slack on the wrong version). scripts/skill-apply.ts — the application engine. Plan (idempotency, prompt resolution, no writes) → mutate (copy/append/env-set, journaled) → run (dep/build/test). Remove is the journal played back (no hand-written REMOVE.md). Anything the engine can't do bounces to an AGENT with its prose — never the human, never a hard abort. A Prompter abstraction lets one engine serve both interactive setup and headless rebuilds; fork-aware remote resolution replaces a hardcoded `origin`. .claude/skills/add-slack/SKILL.md — converted to the format; `prompt` split from `env-set` so a captured secret can feed env, ncl, or the vault; pinned 4.26.0 to match our chat core. setup/channels/slack.ts — the Slack setup flow now applies the skill through the engine in-process (secrets via the Prompter, never argv/disk), deleting the hand-maintained setup/add-slack.sh + install-slack.sh, which had drifted from the skill (they pinned 4.26.0 vs the skill's stale 4.27.0). One source of truth. Verified end-to-end in an isolated worktree: apply copies the adapter + its registration test, installs 4.26.0, builds clean against chat@4.26.0, and the registration test passes. 19 unit tests for the parser + engine. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-14 22:42:47 +03:00
gavrielc	ac0a799cbf	refactor(add-codex): install Codex CLI via cli-tools.json, not the Dockerfile `adfae67` moved the agent's global Node CLIs into container/cli-tools.json so a skill adds one with a json-merge instead of editing the Dockerfile. The Codex provider install was left behind — add-codex.sh still awk'd an ARG + RUN into the Dockerfile and its test guarded that shape. Migrate add-codex to the seam: - add-codex.sh appends { name: "@openai/codex", version } to cli-tools.json (idempotent json-merge); install/idempotency gates read the manifest. - SKILL.md / REMOVE.md document the manifest append/removal, not Dockerfile edits. - codex-dockerfile.test.ts -> codex-cli-tools.test.ts, asserting the manifest entry (skips when the manifest is absent, e.g. the bare providers branch). Pairs with the providers-branch commit that drops the codex Dockerfile lines, renames the payload test, and points the setup install-check at the manifest. Verified end-to-end: full add-codex install into a clean worktree leaves the Dockerfile codex-free, the manifest correctly appended and idempotent; vitest cli-tools.test.ts (6) and bun codex-cli-tools.test.ts (2) green; host tsc clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-14 21:40:44 +03:00
github-actions[bot]	e3986eb58c	chore: bump version to 2.1.16	2026-06-14 18:29:28 +00:00
github-actions[bot]	6d0d48d585	docs: update token count to 195k tokens · 98% of context window	2026-06-14 18:29:25 +00:00
gavrielc	a142c496f7	Merge pull request #2756 from nanocoai/provider-selection feat(providers): operator-driven provider selection, switching, and memory migration	2026-06-14 21:29:12 +03:00
gavrielc	c5b4d11536	Apply suggestion from @gavrielc	2026-06-14 21:16:19 +03:00
Daniel M	ed8b4149e7	Merge pull request #2764 from glifocat/docs/fix-claude-md-relocated-paths docs(CLAUDE.md): fix two relocated Key Files paths	2026-06-14 18:13:31 +03:00
glifocat	d5ce02d1b8	docs(CLAUDE.md): fix two relocated Key Files paths The Key Files table and the Secrets/OneCLI section referenced src/onecli-approvals.ts and src/user-dm.ts, but both files were moved under src/modules/ (src/modules/approvals/onecli-approvals.ts and src/modules/permissions/user-dm.ts). onecli-approvals.ts is already cited at its correct new path elsewhere in the same doc, so this was a partial-rename miss. Docs only — no code changes. Closes #2763 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-14 17:01:40 +02:00
omri-maya	c8af599944	Merge branch 'main' into provider-selection	2026-06-14 15:17:13 +03:00
github-actions[bot]	435233a062	chore: bump version to 2.1.15	2026-06-14 11:04:33 +00:00
gavrielc	785fce3754	Merge pull request #2758 from nanocoai/feat/cli-tools-manifest feat(container): data-drive global CLI installs from cli-tools.json	2026-06-14 14:04:16 +03:00
Omri Maya	6d521a9d8d	refactor(memory): scope imported-memory doctrine to /migrate-memory The "read imported-agent-memory.md, treat it as binding" doctrine sat in the memory definition that every group loads, but it only matters when an import actually happened. Move it into the /migrate-memory skill — the step that writes the imported file and its index pointer (which the agent inlines into its prompt each turn) — and drop the always-on block from definition.md. Addresses review feedback on #2756. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-14 12:12:41 +03:00
gavrielc	adfae67611	feat(container): data-drive global CLI installs from cli-tools.json The agent's global Node CLIs (claude-code, agent-browser, vercel) were each a hardcoded ARG + RUN layer in the Dockerfile, so adding or bumping one meant editing the Dockerfile — a code reach-in every tool-installing skill had to make. Move the tool list into container/cli-tools.json. A skill now adds a CLI by appending a {name, version} entry (a json-merge) — the safest change shape: deterministic, idempotent, removable. install-cli-tools.sh parses the manifest with node (no new jq dep), writes the per-tool only-built-dependencies opt-ins, and runs one pinned `pnpm install -g`, so the pnpm supply-chain path is unchanged. Behavior is byte-for-byte: same opt-ins, same pinned installs. agent-browser is now pinned (0.27.1, what `latest` last resolved to) instead of floating. container/cli-tools.test.ts guards the seam: red if a baseline tool is dropped, a version unpins, or the Dockerfile wiring / pnpm path is removed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-14 12:07:14 +03:00
Omri Maya	13a37def89	feat(providers): operator-driven provider selection, switching, and memory migration Make the agent provider a first-class, operator-chosen property instead of a Claude-only assumption. Trunk gains the seams; the actual non-default payloads (Codex first) install from the `providers` branch. Setup - A provider registry feeds a hard-wired setup picker (Claude \| Codex). Picking a non-default provider installs its payload (setup/add-codex.sh, channel-style), runs a vault-only auth walkthrough (--step provider-auth), and records the pick on the first agent before its first spawn. - Picking Claude changes nothing — default installs are byte-for-byte unaffected. Provider as a DB property - Provider lives on container_configs.provider (materialized to container.json, read by resolveProviderName). Creation stays provider-agnostic; the picked provider is applied via the picked-provider seam. The deprecated agent_groups.agent_provider path is not used. Switching + memory - Switch a live group with `ncl groups config update --provider` + restart. - Memory never migrates at runtime — each provider keeps its own store. The /migrate-memory skill carries a group's memory across a switch in either direction (flat CLAUDE.local.md <-> memory/ scaffold). group-init seeds an imported-agent-memory note for non-default providers; the runner's memory definition reads it first turn. See docs/provider-migration.md. No install-wide default, no runtime provider guard — switching is operator-by- convention, consistent with the no-install-gating posture. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-14 07:49:39 +03:00
github-actions[bot]	03382e9dd7	chore: bump version to 2.1.14	2026-06-13 13:05:30 +00:00
github-actions[bot]	9763551656	docs: update token count to 194k tokens · 97% of context window	2026-06-13 13:05:27 +00:00
gavrielc	a9c9cb300d	Merge pull request #2754 from nanocoai/oss/exchange-hook feat(runner): onExchangeComplete provider hook + slash-command interruption	2026-06-13 16:05:14 +03:00
gavrielc	a619fc1aa2	Apply suggestion from @gavrielc	2026-06-13 16:03:02 +03:00
Omri Maya	3d2f3e58ca	feat(runner): onExchangeComplete provider hook + slash-command interruption Inverts conversation archiving into an optional onExchangeComplete provider hook: the runner never archives on a provider's behalf, and the markdown writer ships with the provider that needs it. Dormant for the default provider. Slash commands now interrupt an in-flight turn — a runner-handled command (/clear, /compact, /cost, …) arriving mid-turn aborts the active stream and runs immediately instead of waiting out the turn. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-13 15:56:43 +03:00
gavrielc	11afc64ba4	Merge pull request #2747 from nanocoai/oss/onecli-sdk-v2 feat(onecli): SDK 2.2.1 — credential-stub mounts + machine-checkable pins	2026-06-13 15:49:40 +03:00
github-actions[bot]	0ee75d393c	chore: bump version to 2.1.13	2026-06-13 12:27:29 +00:00
github-actions[bot]	72b9cc7ed0	docs: update token count to 192k tokens · 96% of context window	2026-06-13 12:27:24 +00:00
gavrielc	5fcf234165	Merge pull request #2746 from nanocoai/oss/agent-surfaces feat(providers): agent-surfaces capability seam	2026-06-13 15:27:12 +03:00
github-actions[bot]	9b1236505f	chore: bump version to 2.1.12	2026-06-13 12:25:58 +00:00
github-actions[bot]	878cd68c1b	docs: update token count to 191k tokens · 96% of context window	2026-06-13 12:25:52 +00:00
gavrielc	fab1ebf2d6	Merge pull request #2745 from nanocoai/oss/memory-scaffold feat(memory): opt-in persistent memory scaffold for providers	2026-06-13 15:25:39 +03:00
Omri Maya	3f9e89d345	feat(onecli): SDK 2.2.1 — credential-stub mounts + machine-checkable pins Injects credentials as request-time stubs so no credential is ever written into a container or to disk. Gateway and CLI versions move to versions.json (machine-checkable pins); breaking upgrades are documented in docs/onecli-upgrades.md as an agent-executable runbook (detect / why / fix / verify / rollback), and the update flow follows linked docs and diffs the pins. BREAKING: requires a gateway upgrade; the doc carries the steps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-12 11:30:11 +03:00
Omri Maya	14810a5090	feat(providers): agent-surfaces capability seam Host-side registry where a provider can declare, by capability rather than by name, that it owns its agent surfaces (project doc, skills). Default providers keep the standard surfaces; a surfaces-owning provider suppresses them. Dormant until a provider registers — no change for existing installs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-12 11:30:10 +03:00
Omri Maya	2cfa86e570	feat(memory): opt-in persistent memory scaffold for providers Adds a provider capability (usesMemoryScaffold) and a container-side boot scaffold that materializes a persistent memory/ tree for providers that opt in. Dormant for the default provider — the scaffold is only built when a provider declares the capability, so existing installs are byte-identical (asserted by a boot-gate wiring test). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-12 11:30:09 +03:00
github-actions[bot]	36cbf17e10	chore: bump version to 2.1.11	2026-06-11 17:16:51 +00:00
gavrielc	4459ab2e54	Merge pull request #2739 from nanocoai/feat/raw-webhook-registry feat(webhook-server): raw-route registry — non-Chat-SDK webhooks become an append	2026-06-11 20:16:33 +03:00