diff --git a/doc/fleet/2026-10-19-reliability-review.md b/doc/fleet/2026-10-19-reliability-review.md
new file mode 100644
index 000000000..0047e0a35
--- /dev/null
+++ b/doc/fleet/2026-10-19-reliability-review.md
@@ -0,0 +1,265 @@
+# Reliability review, 2026-10-19
+
+A dated record of one long working session: what broke, why, what was changed,
+what was found and left open, and what turned out to be wrong along the way.
+**It describes the state on 2026-10-19 at commit `e509884`, before the next
+`just switch` applied it (generation 304 was active).** It is a snapshot, not a
+status page. The durable mechanisms are in [`services.md`](services.md) and
+[`mcp.md`](mcp.md). Each open problem below became an issue on 2026-10-22,
+tracked in dezren39/nix#672.
+
+Facts marked *(audit)* come from three read-only investigations run that day.
+They covered OpenChamber, OpenCode and mcpx reliability; the MCP servers and their
+credentials; and how developing-today/code replaces services under systemd.
+Everything else was checked directly while writing this page.
+
+## Changes made
+
+| Commit | What |
+|---|---|
+| `365ac99` | The desktop app bundles the real OpenCode, not the deploy link. Its dangling link made nix-darwin's rsync into `/Applications/Nix Apps` fail ("symlink has no referent", exit 23) |
+| developing-today/openchamber `94b7e56f9`, pinned here in `3402586` | The desktop app's bundle links `packages/` next to `node_modules/`, so `@openchamber/web` resolves. The app crashed at launch with `ERR_MODULE_NOT_FOUND` |
+| `a0c0cdf`, `8f05b36`, `c90cd1b`, `e2d8f39` | Temporary darwin skips for mcpx tests that only failed in the nix sandbox, each removed once fixed upstream (#428, #434, #435, #445) |
+| `50d22f1` | `simple-rebuild.sh`: fail the build phase when `nix build` exits 0 but produces no `./result` |
+| `5a856f6` | `openchamber.nix`: link the start script, not the deploy key, and fail activation if the link is not executable |
+| `f940ba9` | `just switch` ends with a health check of the long-running agents; the nix-config skill documents activation testing and launchd debugging |
+| `d65df61` | Removed lootbox, the second MCP gateway. `mcpx.config.nix` became the only server list; `mcp-remote` and `chrome-devtools-mcp` are now built from a lockfile |
+| `e220322` | Documented the stray `%` when reading the sops UI password |
+| `ecca0a1` | mcpx: config as a real file at a fixed path, `daemon.autostart = false`, an agent wrapper that clears strays, a CLI-based health check, `ExitTimeOut` on mcpx and OpenChamber |
+| `e509884` | Docs: the live OpenCode config is not the repo's `opencode-global.jsonc` |
+
+Upstream issues filed: developing-today/code#368 (mcpx socket name follows the
+symlink-resolved config path) and developing-today/opencode#134 (OpenCode's mcpx
+plugin starts its own daemon regardless of `daemon.autostart`).
+
+Outside the repo, the same day:
+- lootbox was unloaded and its binary, UI, logs and leftover folders deleted.
+  `~/.lootbox` (14 browser-automation scripts written by hand) was moved to the
+  Trash.
+- The `lootbox.md` line was removed from the live OpenCode config.
+- Six Renovate PRs that only touched lootbox's UI were closed.
+- `nix store gc` freed 22.9 GiB (10,438 store paths).
+
+## Incidents and their causes
+
+### mcpx restarted 841 times (launchd: 842 runs)
+
+**Symptom.** From 11:47 to 14:09, launchd's mcpx daemon exited 1 about every
+10 s: "a daemon is already listening on ~/.local/state/mcpx/daemon-541cdd605dd1.sock".
+
+**Cause.** mcpx names its socket from the symlink-resolved path of its config, and
+the config was a home-manager link into the nix store.
+
+- Socket name per generation *(audit)*: generations 290-295 gave `3489ca4d2ea0`,
+  296 gave `539ba2d32a06`, 297-304 gave `541cdd605dd1`.
+- nix-darwin restarts launchd agents before home-manager re-links files (activate
+  script lines ~862 and ~1100).
+
+Timeline, from `/tmp/mcpx.err.log` and `~/.local/state/mcpx/logs/`:
+
+| Time | Event |
+|---|---|
+| 2026-10-18 20:58 | Generation 298's activation restarts the agent. It reads the still-old link and listens on `daemon-539ba2d32a06.sock` |
+| 04:48:10 | A command computes the current name, finds no daemon and autostarts a detached one (`daemon --detached --idle-exit 4h`, mcpx build `hnqq7r7w…`) on `daemon-541cdd605dd1.sock`. Being used, it never idles out |
+| 11:47 | Generation 302 brings a new mcpx (`p8wcs9ml…`); launchd's daemon restarts on the current name and finds it held |
+| 14:09 | `mcpx stop` ends the stray and launchd's daemon (pid 73031) takes the socket |
+
+Meanwhile, clients ran on the stray's older build.
+
+**Fix** (`ecca0a1`):
+- the config is a real file at a fixed path;
+- commands no longer start daemons;
+- the agent's wrapper stops anything on its socket before starting;
+- the health check fails when the CLI cannot reach the daemon.
+
+Each part was reproduced and tested with real mcpx binaries on scratch state
+directories. A symlinked config re-pointed to another file left the CLI unable to
+reach the running daemon (exit 1). A real file rewritten in place kept the socket
+and was hot-reloaded.
+
+### OpenChamber unreachable
+
+**Symptom.** The desktop app showed the local instance as Unreachable, and every
+request to `127.0.0.1:3000` was refused.
+
+**Cause.** `493be7d` added the UI password's hash to the deploy key
+(`<script>:<sha256>`), and the same string was used as the target of the `start`
+link. The link named a file that did not exist. launchd failed every spawn with
+exit 78 (`EX_CONFIG`) and wrote nothing to `openchamber.log`. It then parked the
+job waiting for the file, so `launchctl kickstart` hung.
+
+**Fix.** `5a856f6`. Recovery: re-point the link, then `launchctl bootout` and
+`bootstrap`.
+
+### Desktop app: activation failure, then crash at launch
+
+- **rsync failure.** nix-darwin copies apps into `/Applications/Nix Apps` with
+  `rsync --copy-unsafe-links`. The app bundled `opencode-cli/opencode` as a link to
+  `~/.local/state/openchamber/bin/opencode`, which home-manager creates only later
+  in the same activation, so rsync failed. Fixed in `365ac99`.
+- **Crash at launch.** `early-startup.mjs` imports `@openchamber/web`, a workspace
+  link to `../../packages/web`. The darwin packaging linked only `node_modules`
+  into the app, so the link dangled. The fork never updated its packaging when the
+  import was added (`e601f1627`). Fixed in the fork.
+
+### "Am I running the right binary?"
+
+The routing, plans, cost-tier and usage features were present on the server. They
+live under Settings → Routing and Settings → Usage, with live data such as routing
+attempts per model. Two things made them look missing:
+
+- the nix-built desktop app was crashing at launch (above);
+- a second, hand-installed `/Applications/OpenChamber.app` (2.1.0) exists outside nix.
+
+### `nix build` exited 0 without producing a system
+
+nix logged "error (ignored): SQLite database …/eval-cache-v6/….sqlite is busy",
+exited 0, and did not create `./result`. `simple-rebuild.sh` then committed a
+marker naming the string `result` as the built store path, and failed three steps
+later with an unrelated-looking "no ./result to activate". `50d22f1` checks for
+`./result/sw/bin/darwin-rebuild` right after the build.
+
+### mcpx tests failing only in the nix sandbox
+
+These failures were sandbox artefacts, not product bugs:
+
+- **Timing.** Tests asserted a child process's marker or pid file the instant a
+  call returned (#428, #435, #445).
+- **Socket path length.** A test bound a unix socket under the sandbox's long
+  `TMPDIR`, past Darwin's 104-byte limit (#434).
+
+All four were fixed upstream within hours of being filed.
+
+### The UI password's trailing `%`
+
+The secret has no trailing newline, so zsh prints a reverse-video `%` after it,
+which got copied with it. The stored value ends in neither `%` nor a newline. The
+start script's `$(< file)` keeps a `%` but drops a trailing newline. Documented in
+`openchamber.nix` and `.sops.yaml` (`e220322`).
+
+### Two credentials printed into the session
+
+While inventorying MCP servers, one investigation printed the managed OpenCode
+server's password and OpenChamber's agent tool token from
+`~/.config/openchamber/managed-opencode/state.json`. Its filter hid only strings
+longer than 60 characters.
+
+- **Exposure.** The server listens on loopback only, and the token is only accepted
+  from same-machine addresses. But both values are in the session history and were
+  sent to the model provider.
+- **Not rotated as of this writing.** OpenChamber reuses both across restarts on
+  purpose. The rotation steps are in `services.md`.
+
+## Corrections made during the session
+
+1. **The stray daemon's cause.** The user was first told it came from a command
+   run during a restart. The cause was the socket name changing with the config
+   (above).
+2. **The wrong check of that cause.** The socket-name mechanism was then wrongly
+   ruled out, by comparing the config store path each generation *contained*
+   (identical for 297-302). What matters is what the link pointed to when the
+   daemon started; the daemon's own log shows `539ba2d32a06`.
+3. **Credential rotation.** One investigation said restarting OpenChamber would
+   rotate the leaked credentials. The code reuses them.
+4. **mcpx's stop time.** One investigation, and the first version of the
+   `ExitTimeOut` comment, said mcpx stops in "5 s of requests, then up to 10 s of
+   servers". The whole stop is bounded by `limits.execDrainTimeout` (10 s), with
+   the 5 s HTTP grace inside it. `ExitTimeOut = 20` covers it either way.
+5. **Copilot models.** One investigation reported that OpenChamber's OpenCode had
+   no Copilot models. That was transient, during OpenChamber's rewrites of the
+   OpenCode config (15:09-15:13); `/api/model` later listed 38 `github-copilot`
+   models.
+6. **mcpx autostart setting.** One investigation reported mcpx had no setting to
+   disable autostart. `daemon.autostart` exists; it is in `mcpx config --schema`
+   and `docs/configuration.md` upstream.
+
+## Open problems (2026-10-19)
+
+Most urgent first. Each has its evidence and a suggested fix.
+
+1. **Disk space.** 8.2 GiB free (99% used) before garbage collection; about 39 GiB
+   after. The biggest remaining items, all user data and not deleted:
+   - `~/.local/share/opencode/tmp`: 43 GB. Nothing prunes it, because the opencode
+     wrapper points `TMPDIR` there (see #377 and #392).
+   - The OpenCode database: 26,231,259,136 bytes. About 5.5 GB of free pages
+     *(audit)*; auto-vacuum is off.
+   - A 2026-10-16 backup of the database. It is an APFS clone, so deleting it frees
+     only the blocks that have changed since, not 26 GB.
+   - `~/.local/share/opencode/worktree`: 14 GB.
+2. **Leaked credentials.** Rotate them (above).
+3. **The live OpenCode config is not the repo's.**
+   - `~/.config/opencode` → `~/nix/.opencode` → `~/.opencode/opencode.jsonc`, a
+     plain v1-format file that OpenChamber rewrites. `opencode-global.jsonc` and
+     its `model_routes` pools are unused.
+   - In it, `small_model` is `github-copilot/claude-opus-5.5`, so every session
+     title is written by the premium model.
+   - Decide whether nix or OpenChamber owns this file.
+4. **OpenChamber restarts OpenCode whenever it rewrites OpenCode's config.**
+   `openchamber.log` shows 21 `handoff (config-refresh)`, 1 `handoff
+   (binary-changed)` and 1 `start (no-state)`. At 13:29 a previous OpenCode was
+   force-stopped when its handover grace ran out *(audit)*.
+5. **Every mcpx update restarts OpenChamber,** because the start script puts mcpx's
+   store path on its PATH. Port 3000 is closed for about 10 s each time. A stable
+   link to mcpx on that PATH would avoid it.
+6. **mcpx.**
+   - `aws` has no credentials and fails on every start (`aws configure sso`, then
+     `aws sso login`, or remove it).
+   - GitHub and Datadog expose write tools (#371).
+   - `elicit.confirmDestructive` is off.
+   - OpenCode's mcpx plugin can still start a stray (developing-today/opencode#134);
+     the agent wrapper clears it at the next agent start.
+7. **OpenCode sessions and snapshots** *(audit)*:
+   - Some sessions repeat "tool_use.input: Input should be an object" every turn
+     (4 times across 3 sessions).
+   - Warm-up retried one session about every 4 minutes after "invalid request body".
+   - Undo snapshots fail in operations-portal: 480 "pathspec … is beyond a symbolic
+     link" errors, because its `features` directory is a symlink.
+8. **Shell start-up.** `homePrograms.nix` runs `eval "$(opencode completion)"`.
+   OpenCode v2 treats `completion` as a directory name: it starts the 190 MB
+   binary in every new shell and logs errors.
+9. **Leftover processes,** not part of the three services and still running at
+   this writing:
+   - pid 40073, a fake OpenCode test server from Oct 14 on port 53489;
+   - pid 88342, a Node test process from Oct 17 that ignores SIGTERM;
+   - pids 32670 and 80975, Python workers from an operations-portal worktree;
+   - three headless Chrome groups from OpenChamber performance probes, about 1 GB *(audit)*.
+10. **Log noise and growth.**
+    - 3,182 of `openchamber.log`'s 4,447 lines are "[PushWatcher] connected".
+    - `opencode.log` grew about 45 MB in 27 hours *(audit)*.
+    - `/tmp/mcpx.err.log` (605 KB) is never rotated.
+11. **The terminal's shared OpenCode service** (`opencode serve --service`) runs as
+    the child of a terminal client, not of launchd. Closing that terminal tab
+    probably stops it for other terminal clients too *(audit, inferred)*.
+
+## Model-backed features (2026-10-19)
+
+- **OpenCode.** The default model and the title agent are both
+  `github-copilot/claude-opus-5.5` (from the live config's `small_model`). Summary
+  and compaction use the default model. All 11 Copilot models referenced in the
+  configs exist *(audit)*.
+- **OpenChamber's small model** (session titles, goal writer, session assist) is
+  `github-copilot/claude-sonnet-5`, and it worked that day *(audit)*.
+- **OpenChamber's automatic routing ("Jev").**
+  - It is off: `classification.json` has `"source":"off"` and `routing.json` has
+    `enabled:false` *(audit)*. That is why the UI says "Needs Jev, and no
+    classification provider is set up".
+  - Options listed: Zen's free promotion (sends conversation excerpts to
+    opencode.ai), a Zen key, OpenRouter or Vercel AI Gateway, TypeSafe's API, or a
+    custom endpoint.
+- **Dictation.** A local sherpa-onnx Parakeet 0.6B int8 model (631 MB) is
+  installed. There are no errors and no sign it has been used *(audit)*.
+  Text-to-speech uses macOS `say`.
+- **`@xenova/transformers`** ships with OpenChamber, with no sign it is used *(audit)*.
+- **mcpx embeddings.** The backend is `auto` and `search.semantic` is false; the
+  embeddings table is empty, and the test vectors look like a hash fallback, not a
+  model *(audit, inferred)*. Off, not failing.
+
+## Left for the user at the end of the session
+
+1. `just switch`. It should end with `up: org.nixos.openchamber` and
+   `up: org.nixos.mcpx`; mcpx restarts once onto its fixed socket.
+2. Then `rm -rf ~/.local/share/lootbox`. Today's mcpx still runs two servers from
+   it, so it must wait for the switch. The switch removes `~/.config/lootbox` and
+   the old launchd plist itself.
+3. Rotate the two leaked credentials when convenient.
+4. Decide on the disk items, the AWS server and who owns the live OpenCode config.
diff --git a/doc/fleet/mcp.md b/doc/fleet/mcp.md
new file mode 100644
index 000000000..306bfe662
--- /dev/null
+++ b/doc/fleet/mcp.md
@@ -0,0 +1,140 @@
+# MCP servers
+
+Every MCP server on this machine runs under mcpx, the gateway daemon described in
+[`services.md`](services.md). This page covers how the servers are wired, how they
+authenticate, and an inventory of each one. The inventory states facts as of the
+date in its heading; re-run its checks before relying on them.
+
+## How it is wired
+
+- **One list.** `mcpx.config.nix` defines every server and how mcpx pools it.
+  `homeUser.nix` (`home.activation.mcpxConfig`) writes it to
+  `~/.config/mcpx/config.json` as a real file. See `services.md` for why it is not a
+  home-manager link.
+- **Absolute commands.** Every stdio server is started by its
+  `/run/current-system/sw/bin/...` path. A daemon inherits the PATH of whatever
+  started it, and a bare name could fail with "executable file not found" under
+  another PATH.
+- **npm-only servers.** `mcp-remote` and `chrome-devtools-mcp` are built from a
+  committed lockfile (`pkgs/npm-mcp-servers`, `importNpmLock`; versions 0.14.2 and
+  1.9.0, pinned in its `package.json`). No package in the lockfile has an install
+  script, and `npm rebuild` runs with `--ignore-scripts`. To update, change
+  `package.json`, run `npm install --package-lock-only --ignore-scripts` there, and
+  rebuild.
+- **Pooling** (`mcpx` block per server):
+  - `chrome-devtools` and `playwright` get one process per agent session
+    (`sharing = "exclusive"`, `scope = "session"`); browser state must not be
+    shared.
+  - `aws` gets `startTimeout = "180s"`, because `uvx` downloads the proxy on its
+    first start.
+  - `github` hides `create_repository`, `fork_repository`, `delete_repository`,
+    `push_files`, `create_or_update_file`, `delete_file` and `merge_pull_request`;
+    `datadog` hides `delete_*`, `execute_code`, `execute_datadog_workflow` and the
+    tools that change live monitors, dashboards and workflows (`excludeTools`,
+    dezren39/nix#664). Issue and PR tools stay.
+- **Only the launchd agent starts a daemon** (`daemon.autostart = false`). See
+  `services.md`.
+- **Smoke test.** `just mcpx-check` lists every server's state and calls one tool
+  each on codedb, fff, chrome-devtools and context7.
+
+## OAuth for the remote servers
+
+atlassian, context7 and datadog run through `mcp-remote`, which does the OAuth
+sign-in in a browser and stores tokens itself:
+
+- **Where tokens live:** `~/.mcp-auth/mcp-remote-v1/`, in files named after an MD5
+  hash of the server URL (`<hash>_tokens.json`, `_client_info.json` and so on).
+  `v1` is mcp-remote's `CONFIG_STORE_VERSION`. `MCP_REMOTE_CONFIG_DIR` moves the
+  base directory.
+- **The URL is the identity.** Changing a server's URL, including its query
+  string (Datadog's `toolsets` and `omit_tools`), needs a new sign-in.
+- **Signing in:** `just mcp-login <name>`, and press Ctrl-C once it reports it is
+  connected. Context7's sign-in is optional and only raises its rate limit
+  (`just context7-login`).
+- **Old tokens:** token files for two earlier Datadog URLs are still in that
+  directory. They are expired and unused.
+
+github uses `gh`'s token: the `github-mcp` wrapper in `systemPackages.nix` reads
+`gh auth token` from the login keychain at start, so no token is stored in the
+repo or the nix store. aws signs requests (SigV4) using `~/.aws/config` profiles
+(with `--skip-auth` so its 8 tools load even when logged out, and `--profile`
+populated dynamically from `aws configure list-profiles` so callers can switch
+accounts per call via the `aws_profile` tool parameter).
+
+## Inventory (2026-10-20)
+
+Tool counts are from `mcpx ls` on 2026-10-20. Credential details come from token
+file metadata, `gh auth status`, and `aws configure list-profiles`. No secret
+values were read for this page.
+
+| Server              | What it does                                                            | Transport                                                                                                                           | Auth                                                                                                                      | Credential (2026-10-20)                                                                                                                                       | Tools | Notable risks                                                                                                                                                                                            |
+| ------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| atlassian           | Jira, Confluence, Loom                                                  | `mcp-remote` → `mcp.atlassian.com/v2/mcp?tools=all` (`--static-oauth-client-metadata` pinning 20 read/search scopes)                | OAuth                                                                                                                     | Present; access token refreshed (8h TTL), 90-day refresh token (`exp` 2027-01-18); scope pinned so `.well-known` changes or timeouts never wipe `tokens.json` | 108   | Read/search only (pinning the 20 granted scopes hides the 82 ungranted write/delete tools so calls never trigger 403 step-up browser re-auth)                                                            |
+| aws                 | AWS APIs & docs                                                         | `uvx mcp-proxy-for-aws-cli@1.7.0` → `aws-mcp.us-east-1.api.aws/mcp` (`--skip-auth`, `--profile` from `aws configure list-profiles`) | SigV4, per-call `aws_profile` switching                                                                                   | `~/.aws/config` role-switch profiles (`source_profile = mfa`); sign in via `aws login` / `aws-login-auto`                                                     | 8     | `aws___run_script` can execute AWS API calls in whichever profile is passed in `aws_profile` (use `-read-only` profiles for read-only work)                                                              |
+| aws-knowledge       | AWS documentation                                                       | HTTP `knowledge-mcp.global.api.aws`                                                                                                 | None                                                                                                                      | —                                                                                                                                                             | 5     | —                                                                                                                                                                                                        |
+| chrome-devtools     | Headless Chrome, one per session                                        | stdio `chrome-devtools-mcp`                                                                                                         | None                                                                                                                      | —                                                                                                                                                             | 27    | `evaluate_script`, `upload_file`                                                                                                                                                                         |
+| codebase-memory     | Code call graph and impact                                              | stdio `codebase-memory-mcp`                                                                                                         | None                                                                                                                      | —                                                                                                                                                             | 17    | `delete_project` (local index only)                                                                                                                                                                      |
+| codedb              | Code search (symbols, callers)                                          | stdio `codedb mcp`                                                                                                                  | None                                                                                                                      | —                                                                                                                                                             | 5     | —                                                                                                                                                                                                        |
+| context7            | Library documentation                                                   | `mcp-remote` → `mcp.context7.com/mcp`                                                                                               | OAuth, optional                                                                                                           | Not signed in; runs anonymously at a lower rate limit                                                                                                         | 2     | —                                                                                                                                                                                                        |
+| datadog             | Logs, metrics, traces, monitors, dashboards, notebooks, workflows (US1) | `mcp-remote` → `mcp.datadoghq.com/v1/mcp?toolsets=core,workflows,alerting&omit_tools=delete_datadog_workflow`                       | OAuth                                                                                                                     | Present, refreshed that day                                                                                                                                   | 63    | `execute_datadog_workflow` (does whatever the workflow does), `update_datadog_monitor`, `upsert_datadog_dashboard`, `delete_datadog_notebook`; the token carries 173 scopes, including `api_keys_delete` |
+| deepwiki            | Wikis for public GitHub repos                                           | HTTP `mcp.deepwiki.com/mcp`                                                                                                         | None                                                                                                                      | —                                                                                                                                                             | 3     | —                                                                                                                                                                                                        |
+| fff                 | File and content search over `~/git`                                    | stdio `fff-mcp`                                                                                                                     | None                                                                                                                      | —                                                                                                                                                             | 3     | —                                                                                                                                                                                                        |
+| fff-nix             | Same, over this repo                                                    | stdio `fff-mcp`                                                                                                                     | None                                                                                                                      | —                                                                                                                                                             | 3     | —                                                                                                                                                                                                        |
+| fff-worktree        | Same, over `~/.local/share/opencode/worktree`                           | stdio `fff-mcp`                                                                                                                     | None                                                                                                                      | —                                                                                                                                                             | 3     | —                                                                                                                                                                                                        |
+| github              | GitHub                                                                  | stdio `github-mcp` → `github-mcp-server stdio`                                                                                      | `gh` token (account dezren39; scopes `repo`, `workflow`, `gist`, `read:org`, `admin:public_key`, `admin:ssh_signing_key`) | Present                                                                                                                                                       | 43    | `push_files`, `delete_file`, `merge_pull_request`, issue and PR writes (#371). With `workflow` scope a push can change Actions workflows                                                                 |
+| markitdown          | Converts a URL or file to Markdown                                      | stdio `markitdown-mcp`                                                                                                              | None                                                                                                                      | —                                                                                                                                                             | 1     | Can read local `file:` URIs                                                                                                                                                                              |
+| nixos               | Nix packages, options, NixOS wiki                                       | stdio `mcp-nixos`                                                                                                                   | None                                                                                                                      | —                                                                                                                                                             | 2     | —                                                                                                                                                                                                        |
+| playwright          | Headless browser, one per session                                       | stdio `playwright-mcp`                                                                                                              | None                                                                                                                      | —                                                                                                                                                             | 25    | `browser_run_code_unsafe`, `browser_file_upload`                                                                                                                                                         |
+| sequential-thinking | Step-by-step reasoning scratchpad                                       | stdio `mcp-server-sequential-thinking`                                                                                              | None                                                                                                                      | —                                                                                                                                                             | 1     | —                                                                                                                                                                                                        |
+| terraform           | Public Terraform registry lookups                                       | stdio `terraform-mcp-server stdio --toolsets=registry`                                                                              | None                                                                                                                      | —                                                                                                                                                             | 9     | —                                                                                                                                                                                                        |
+
+mcpx's `elicit.confirmDestructive` stays off: a caller that cannot answer the
+question, which is every script, waits out the deadline and the call then
+proceeds, so it would only add a delay. The dangerous tools are hidden instead
+(above). The table's last column was written before that: the GitHub and
+Datadog tools it names are now hidden, and Datadog lists 54 tools.
+
+## Other MCP clients: mcpx only (2026-10-22)
+
+Every other MCP client gets one MCP server, mcpx, as
+`/run/current-system/sw/bin/mcpx --config ~/.config/mcpx/config.json serve`
+(stdio). `mcp-clients.py`, run by home-manager on every switch
+(`home.activation.mcpClients`), sets it and changes nothing else in each file.
+The first time it changes a file, it keeps a copy in
+`~/.local/state/mcp-clients/backup/`. The `--config` matters: without it mcpx
+searches upward from the client's working directory, a repository's
+`.mcp.json` changes which daemon it looks for, and with autostart off none is
+there.
+
+A client sees mcpx's gateway, not the 18 servers' tools by name: about 80
+`mcpx_*` tools (`mcpx_search`, `mcpx_types`, `mcpx_call`, `mcpx_exec`, ...).
+`mcpx_call {namespace, tool, arguments}` reaches any server; namespaces use `_`
+for `-` (`chrome_devtools`). The daemon also serves MCP over HTTP at `/mcp` on
+its loopback port, but that port is chosen at random on each start, so the
+clients use stdio.
+
+| Client | Installed | Config | Before | Now |
+|---|---|---|---|---|
+| Copilot CLI | yes (Homebrew) | `~/.copilot/mcp-config.json` | codedb (`~/bin/codedb`), deepwiki, plus its built-in GitHub server | mcpx. The built-in server has no config key; the `copilot` shell alias passes `--disable-builtin-mcps`. Checked: `copilot --model gpt-6-luna -p` called `mcpx_namespaces` through it and got 18 namespaces |
+| Zed | yes | `~/.config/zed/settings.json` (`context_servers`) | GitHub, Context7 and Postgres extensions (Postgres had no `database_url` and errored at every start) | mcpx. Zed started `mcpx ... serve` itself on the settings change. The three extensions were moved to `~/.local/state/mcp-clients/backup/zed-extensions/`, and Zed unloaded them |
+| Claude Code | no | `~/.claude.json` (`mcpServers`) | codedb, deepwiki | mcpx |
+| Codex | no | `~/.codex/config.toml` (`[mcp_servers.*]`) | codedb, deepwiki | mcpx |
+| OpenCode | yes | none needed | the fork's built-in mcpx plugin | unchanged; an `mcp` entry would list the tools twice |
+| OpenChamber | yes | none | drives OpenCode | unchanged |
+
+No config was found for VS Code (application data left, app removed), Cursor (a
+dangling `/usr/local/bin/cursor` link), Windsurf, Claude Desktop or Gemini CLI.
+A client added later needs an entry in `mcp-clients.py`.
+
+## Tool namespaces that are not MCP servers
+
+Agents in OpenCode also see these plugins:
+
+- **`github`:** built into the OpenCode fork; uses the `gh` token. It lists 45 tools
+  and hides 33 administrative ones, such as `secret_set`, which the model can turn
+  on itself. Its `api` tool accepts any HTTP method. Write actions are allowed by
+  default (#371).
+- **`opencode` and `mcpx_*`:** built in. The `mcpx_*` tools talk to the mcpx daemon.
+- **`tokenscope`:** a file plugin.
+- **`openchamber*`:** four tools, added through OpenChamber's
+  `opencode.managed.json`.
diff --git a/doc/fleet/mcpx-extraction.md b/doc/fleet/mcpx-extraction.md
new file mode 100644
index 000000000..e505f2ed9
--- /dev/null
+++ b/doc/fleet/mcpx-extraction.md
@@ -0,0 +1,83 @@
+# Move mcpx to developing-today/code
+
+- Status: done for the build switch and the deletion (steps 4–5, #468,
+  2026-10-19). The consumption mechanism chosen under `developing-today/code#308`
+  is a source-only pinned flake input (`mcpx-src`, `flake = false`) calling the
+  `package.nix` that lives beside the source in code. The final pre-deletion
+  audit found the copies' production code identical; the one test assertion
+  only this copy had was ported first (`developing-today/code#361`, PR #362).
+  Step 3 (re-homing the backlog, `developing-today/code#309`) and step 6
+  (closing the mcpx source issues here) remain open follow-ups, as does the
+  aarch64-darwin build verification, which needs the Mac.
+- Update (2026-11-03, #1388): the `mcpx-src` consumption mechanism
+  described in this status was itself retired - this flake collapsed to
+  the single openchamber input; mcpx (and its daemon modules) now arrive
+  through the openchamber -> opencode chain, and the fork's opencode
+  bundles the fork's mcpx. The steps below stand as the record of the
+  extraction as planned and executed.
+- Roadmap item: [mcpx leaves this repo](../../ROADMAP.md#mcpx-moves-to-developing-todaycode)
+- Design: none needed, the decision is made
+- Issues: `developing-today/code#308` (how to consume), `developing-today/code#309` (move the backlog), `developing-today/code#237` (takeover tests on darwin)
+
+## Goal
+
+`developing-today/code` is the only place the `mcpx` source lives. This repo builds `mcpx` from a pinned rev of that repo, and `opencode`, the launchd daemon and OpenChamber still get it.
+
+## Why
+
+This repo carries a vendored copy (`pkgs/mcpx`) that has drifted: 29 files differ between code@8fc1fb3 and nix@4f46bd5, and each side holds fixes the other lacks. Fixes land twice or get missed. Code is the primary source.
+
+## Does the darwin flake keep mcpx without this copy?
+
+Not on its own. The OpenCode fork does not bundle mcpx. Its flake takes an optional argument and links the binary only when a consumer passes one:
+
+- `opencode/flake.nix`: `mcpx = pkgs.mcpx or null`
+- `opencode/nix/opencode.nix`: `mcpx ? null`, then `ln -s ${mcpx}/bin/mcpx $out/bin/mcpx`
+- `flake.nix` here, in `mkPackages`: `inputs.opencode.packages.${system}.opencode.override { inherit mcpx; }`, where `mcpx` is built from `./pkgs/mcpx/package.nix`.
+
+The same package feeds the launchd daemon (`configuration.nix`) and OpenChamber's PATH (`openchamber.nix`). Deleting `pkgs/mcpx` with no replacement removes mcpx from the CLI, the daemon and OpenChamber. The replacement has to be a pinned build of the code repo.
+
+## Differences found (code is `-`, this repo is `+`)
+
+- `internal/cli/client.go`: `EnsureDaemon` here checks `ctx.Err()` again after the poll loop (since #233). Code's fix for its #284 originally did not; code closed that gap in its #328 (PR #329), and this repo pinned the deadline-exit path with a test in PR #440. Landed on both sides; the remaining differences in this file are comment wording and the issue numbers cited.
+- `internal/daemon/paths.go`: `envStateDir()` and `MCPX_STATE_DIR` in `DaemonSearchDirs` and `mirrorInfoPath`. Fixed here by #410 and ported to code by its PR #306 (merged 2026-10-18). Landed on both sides.
+- `internal/daemon/server.go`, `takeover.go`, `registry_handoff.go`: both repos now wait for background orphan-session DELETEs on shutdown, on the handed-off return, and on the restart path — code via its #298/#299 and PR #307 (its #301), this repo via PR #421 (#409, #416). Landed on both sides.
+- About 20 more files, mostly tests, docs and the `mcpx-agy` example README. Many differ only in the issue number a comment cites, since each repo uses its own numbers (code `#278` is `#369` here). I did not read every test diff.
+- `internal/cli/dispatch.go` differs only in map-literal alignment. Run `gofmt` in code and settle which is right.
+
+## What only exists here and must move
+
+- Darwin test handling in `flake.nix`: a `postPatch` for `takeover_test.go` (`SOCK_CLOEXEC`) and a `-skip` list of 20 takeover tests. This is `developing-today/code#237`.
+- The `bun-bin` argument (`pkgs/bun-bin`).
+
+## What stays here
+
+`mcpx.config.nix`, the launchd agent in `configuration.nix` (it restarts the daemon, since launchd cannot hand it over), the `homeUser.nix` wiring, and the `openchamber.nix` and `opencode-unwrapped` overrides. Issue #371 (the github server's write tools in the mcpx config) stays too.
+
+## Steps
+
+1. **Code can be consumed.** Choose how (`developing-today/code#308`) and make `mcpx` build on aarch64-darwin (`#237`). Done when `nix build` of the chosen output succeeds on this Mac.
+2. **Port the differences.** One PR per group in code: the gofmt question, tests that exist only here. (The `EnsureDaemon` check and the `MCPX_STATE_DIR` change have already landed on both sides — see Differences found.) Done when `diff -ru` between code and this repo shows only issue-number comments and the darwin adaptations.
+3. **Re-home the backlog.** `developing-today/code#309`. GitHub cannot transfer issues across owners, so each live issue is re-filed there and closed here with a link.
+4. **Switch the build.** Add the code input, build `mcpx` from it in `mkPackages`, and keep `{ inherit mcpx; }` going into the fork. Done when `opencode`, the launchd daemon and OpenChamber all report the same `mcpx` version, and it comes from the pinned rev.
+5. **Delete the copy.** Remove `pkgs/mcpx/`, `.github/workflows/mcpx.yml` and `.github/workflows/mcpx-conformance.yml`. Update `ARCHITECTURE.md` and the `.agents/skills` that mention `pkgs/mcpx`. Done when `grep -r pkgs/mcpx` finds nothing.
+6. **Close the mcpx source issues here.** Those that become moot: #418, #403, #366, #367, #362, #259, #235, #108 and the design backlog. (#409 and #416 are already closed — fixed by PR #421, not by this step.)
+
+## Tests and evidence
+
+- `nix build` of `mcpx` from the pinned rev on aarch64-darwin, with the output of `mcpx version`.
+- `darwin-rebuild build` for this configuration, before and after step 4, with the closure diff.
+- After switching: `mcpx status` against the launchd daemon, and a call through `opencode`.
+
+## Rollout and rollback
+
+Step 4 is the only step that changes what runs on the machine. Roll back by reverting that commit, which restores the vendored copy as long as step 5 has not landed. Do step 5 in a separate PR after a few days of use.
+
+## Risks
+
+- The launchd daemon restarts when the store path changes. Calls in flight at that moment fail. The agent restarts the daemon because launchd cannot do a takeover, as `configuration.nix` explains.
+- Code's input graph is large. If it is consumed whole, this repo's lock file grows. `developing-today/code#308` decides how to avoid that.
+
+## Progress
+
+- 2026-10-18: plan written. No step started.
diff --git a/doc/fleet/mcpx-identity-transport.md b/doc/fleet/mcpx-identity-transport.md
new file mode 100644
index 000000000..39aca8244
--- /dev/null
+++ b/doc/fleet/mcpx-identity-transport.md
@@ -0,0 +1,193 @@
+# mcpx identity transport: comparison and recommendation for #297
+
+- Status: decision made 2026-10-28 (queue task 2654, lane A). No code in
+  this document's PR — it answers the question #297 exists to force, so an
+  implementation issue can be filed against a settled choice.
+- Issues: dezren39/nix#297 (this decision), #187 (the iroh-blobs
+  question, answered in §4), #85 (ssh remote access — the incumbent),
+  #115 (Tailscale proposal — changes the tsnet calculus if it lands),
+  #158 (release artefacts), #174 (parent tracker).
+- Code citations are to developing-today/code, where the mcpx source
+  lives, verified at `528886eba` on 2026-10-28.
+
+## 1. The requirement
+
+From #297, stated as properties rather than as a product name:
+
+1. A daemon reachable by **stable cryptographic identity**, not by address.
+2. **NAT traversal with no port forwarding**, and a **relay fallback** when
+   hole punching fails.
+3. **End-to-end encryption and mutual authentication** derived from that
+   identity.
+
+Plus two constraints from how mcpx is actually built, which any candidate
+must survive:
+
+4. **Pure-Go build.** mcpx's `package.nix` sets `env.CGO_ENABLED = "0"`
+   (`pkgs/mcpx/package.nix:60`, developing-today/code) and the release
+   matrix (#158) cross-compiles without ceremony. A transport that breaks
+   this is not a dependency, it is a build-system change.
+5. **No silent downgrade.** Failure (relay-only path, identity mismatch)
+   must error clearly, never fall back to an unauthenticated route (#297
+   acceptance).
+
+Who may call is authorisation (#253/#298/#300) and is explicitly **not**
+part of this decision.
+
+## 2. Current state, verified
+
+- Two listeners, both address-shaped. `Server.Listen`
+  (`pkgs/mcpx/internal/daemon/server.go:253`) binds a unix socket
+  (`net.Listen("unix", …)`, :258) and a TCP host/port (`net.Listen("tcp",
+  …)`, :273) — nothing else. The serve loop already iterates a slice of
+  `net.Listener`s (:313), which matters in §5: a transport that can hand
+  back a `net.Listener` needs no surgery in the daemon.
+- One client setting, address-shaped. `daemon.endpoint`
+  (`pkgs/mcpx/internal/settings/registry.go:429`): empty means the local
+  unix socket, a URL points at a daemon on another machine, `unix:///path`
+  targets a different local socket. No identity scheme exists.
+- No candidate is present. `grep -rn 'iroh|tsnet|libp2p' pkgs/mcpx/internal
+  pkgs/mcpx/cmd pkgs/mcpx/go.mod` at `528886eba`: zero hits.
+
+## 3. Criteria matrix
+
+Scored against §1. ● meets it, ◐ partially / with a real asterisk,
+○ fails or fights it.
+
+| Criterion | iroh via cgo (`iroh-ffi`) | iroh as sidecar | `tsnet` (Tailscale) | `go-libp2p` |
+|---|---|---|---|---|
+| 1. Stable crypto identity | ● ed25519 NodeId is the address | ● same, via the sidecar's NodeId | ● tailnet node identity (WireGuard keypair, account-anchored device name); stable across networks/addresses | ● PeerId from the node's keypair |
+| 2. NAT traversal + relay fallback | ● hole punching + iroh relays | ● same | ● the most battle-tested of the four: STUN/hole-punching plus the global DERP relay network | ◐ DCUtR hole punching + Circuit Relay v2 exist, but relay capacity is bring-your-own/public-best-effort, and finding *your* peer (DHT/rendezvous) is the genuinely hard part |
+| 3. E2E encryption + mutual auth from identity | ● QUIC/TLS, peer is its key | ● same on the tunnel; the last hop (sidecar→unix socket) is local-trust | ● WireGuard end to end; the server learns the peer's tailnet identity (WhoIs), so mutual auth comes from enrolment | ● Noise/TLS with peer-id authentication |
+| 4. Pure-Go build / cross-compile / release cost (#158) | ○ **fails the constraint.** cgo + a Rust toolchain per platform; per iroh's own language docs the Go bindings are *community* FFI bindings — not officially supported, may lag iroh releases, and cover fewer platforms than any other binding. Also embeds a Rust async runtime in the Go process. | ◐ daemon stays pure Go, but the release gains a per-platform Rust binary: a second toolchain in the pipeline, version pairing between daemon and sidecar, and #158's matrix multiplies | ● a Go library (`tailscale.com/tsnet`). `tsnet.Server.Listen` returns a plain `net.Listener`; CGO_ENABLED=0 preserved; no new toolchain | ● pure Go, but the dependency tree is very large for one feature, and it lands in every binary whether used or not |
+| 5. Coordinator centralisation | ● none: discovery via DNS/pkarr-style records and public relays; no account | ● none, same | ○ by default the Tailscale coordination server is the control plane — the one genuine structural objection. Mitigation exists: Headscale (self-hosted control server, custom control URL), at the cost of running it | ● none: no coordinator; bootstrap/DHT only |
+| 6. Operational sharp edges | two runtimes, one process: panics and debugging cross the FFI boundary; binding lag is a standing risk | a second process to supervise, health-check and address; "mcpx supports iroh" really means "install a thing next to mcpx" | enrolment ceremony (auth key / login URL) for a headless daemon; both ends must be on the tailnet; a large (if mature) dependency | the sharpest edges of the four: relay scarcity, discovery bootstrap, fast-moving APIs, and the operator becomes the network engineer |
+
+## 4. Does #187 want iroh-blobs badly enough to pay for a sidecar? No.
+
+This was the strongest argument for iroh specifically, so it gets its own
+section. Read at HEAD, #187 does not ask for cross-machine transfer at all:
+
+- #187's recommended approach (its Approach C) is **one local cache
+  package**: per-kind namespaces under `<state>/cache/<kind>/<key>`,
+  SHA-256 keys over canonical inputs, lease-pinning while an exec runs,
+  eviction by bytes and age. Every word of that is satisfiable on one
+  machine with no transport.
+- Its three tenants make the point concrete. The import-graph cache is
+  kilobytes. The flake-resolution tenant's problem is not moving bytes —
+  the entry names a `/nix/store` path, and the problem is holding a **GC
+  root** for it; nix itself is already the transfer mechanism for store
+  paths. The prepared-dependencies tenant may shrink to a manifest if
+  mcpx leans on the runtimes' own caches (deno/bun/npm) — #187's first
+  open question — in which case there is nothing large left to transfer.
+- "Fetch this script's dependency closure from whichever of my machines
+  has it" is a genuinely attractive capability. It is also **a new
+  requirement nobody has filed**: #187 neither states it nor needs it,
+  and #297's convergence story assumes it rather than citing it.
+
+Conclusion: iroh-blobs buys an option, not a requirement. Options do not
+justify a second toolchain in the release pipeline. If cross-machine
+content fetch is ever filed as a real requirement, iroh (blobs, as a
+sidecar) can be adopted then, behind the same transport interface §5
+recommends — this decision does not close that door, it declines to pay
+for it early.
+
+## 5. Recommendation
+
+**Adopt `tsnet` as mcpx's first identity transport, behind a small
+transport interface in the daemon. Reject iroh-via-cgo outright. Keep
+go-libp2p as the named fallback if the coordination objection ever
+becomes decisive; keep iroh-sidecar as the named fallback if a
+cross-machine content-transfer requirement is ever actually filed.**
+
+Reasons, in the order they decided it:
+
+1. It is the only candidate that meets properties 1–3 **and** the pure-Go
+   constraint with a first-party, maintained implementation. The cgo
+   route fails constraint 4 on its face and rests on community bindings
+   iroh's own docs warn may lag; the sidecar pays a standing release and
+   supervision cost for a blobs benefit §4 shows is not currently real.
+2. It fits the daemon's existing shape. `Server.Listen` already serves a
+   slice of `net.Listener`s; a tsnet listener is one more entry, and the
+   address-based listeners are untouched (#297 acceptance: unix, TCP and
+   ssh keep working unchanged).
+3. The relay network is the product. Relay fallback is where personal
+   infrastructure goes to die; DERP is a running global network today,
+   while libp2p makes mcpx's operator source their own relay capacity,
+   and its discovery story for "my two machines" is the weakest of the
+   four despite the strongest decentralisation.
+4. It is already in this project's orbit: the fleet's machines already
+   run on a tailnet, and #115 proposes Tailscale integration for mcpx
+   from the other direction. The marginal dependency cost is therefore
+   lower here than in a project starting from zero.
+5. The centralisation cost is real but bounded and reversible: identity
+   depends on a coordination service by default, Headscale removes that
+   dependency without changing the data plane, and the transport
+   interface (below) means tsnet is a tenant, not a foundation.
+
+The interface is part of the recommendation, not an afterthought: the
+daemon should hold *transports* — objects that produce a `net.Listener`
+and a dialer for an identity — with unix/TCP as the built-in address
+transports and tsnet as the first identity transport. That is what makes
+§5's fallbacks cheap if the world changes, and it is the same shape the
+authorisation work (#253/#298/#300) will need regardless of winner: a
+policy checks an identity at a transport boundary.
+
+## 6. #297's open questions, answered
+
+- **More than one transport at once, or one at a time?** More than one,
+  by design — the serve loop already holds several listeners, and unix +
+  tsnet simultaneously is the obviously right default (local tools keep
+  the fast path). Ship and *enable* one identity transport first; the
+  surface each additional one adds is per-transport identity handling,
+  not listener plumbing.
+- **Does the TUI work over a relayed connection?** Acceptably, with a
+  caveat to measure rather than debate. A DERP-relayed path adds one
+  relay hop's latency to every round trip; request/response RPC does not
+  notice, an interactive TUI does but remains usable, and the direct
+  path is used whenever hole punching succeeds — relay-only is the bad-
+  network case, where the alternative today is ssh not reaching the
+  machine at all. Two requirements follow: status must show whether a
+  connection is direct or relayed (no silent slow path, per §1.5), and
+  relay-only TUI latency is an acceptance measurement for the
+  implementation issue, not a design blocker here.
+- **Phone or browser?** Phone: covered — the phone joins the tailnet
+  with the Tailscale app and reaches the daemon as any other node; no
+  phone-specific work exists in this design. Browser: **none** of the
+  four candidates is reachable from a web page; that requirement means a
+  hosted gateway/relay product, which is a different project. This doc
+  proceeds on *phone yes, browser no* — and flags the browser half as
+  Drew's scope decision, escalated on #297 rather than silently assumed.
+- **`daemon.endpoint` scheme, or a new setting?** Grow the scheme. The
+  setting already mixes forms (bare URL, `unix:///path`), so an identity
+  scheme — e.g. `daemon.endpoint = "tsnet://<hostname>"` — keeps one
+  setting and one mental model ("where is my daemon"), instead of two
+  settings that can contradict each other.
+- **If a sidecar is acceptable here, is it acceptable for the Roc
+  platform host too?** Moot under this recommendation: no sidecar is
+  adopted, so no precedent is set. A hypothetical second use must not be
+  counted in iroh-sidecar's favour today — two issues *possibly* wanting
+  a Rust artefact in future is not the same fact as one issue needing
+  one now. The Roc question stands on its own when it is asked.
+
+## 7. What this decision does not do
+
+- No transport code, no new dependency, no prototype — a follow-up
+  implementation issue (tsnet listener + `tsnet://` endpoint scheme +
+  direct/relayed status, with the relay-latency measurement) is the next
+  step, filed against this document.
+- No authorisation work: who-may-call stays with #253/#298/#300.
+- No change to address-based endpoints: unix socket, TCP, and ssh (#85)
+  are untouched and remain the fallback when no identity transport is
+  configured.
+
+## Sources
+
+- iroh language/bindings status (Go = community FFI bindings, may lag,
+  fewer platforms): iroh documentation, "Languages" overview,
+  docs.iroh.computer — checked 2026-10-28.
+- `tsnet` package summary (embeds a Tailscale node in a Go program,
+  returns standard `net.Listener`/`net.Conn`): pkg.go.dev,
+  `tailscale.com/tsnet` — checked 2026-10-28.
+- All mcpx claims: developing-today/code at `528886eba`, file:line as
+  cited in §2.
diff --git a/doc/fleet/mcpx-oauth-authorization-server.md b/doc/fleet/mcpx-oauth-authorization-server.md
new file mode 100644
index 000000000..f20657a80
--- /dev/null
+++ b/doc/fleet/mcpx-oauth-authorization-server.md
@@ -0,0 +1,131 @@
+# mcpx OAuth authorization server: embed-vs-point-at recommendation for #345
+
+- Status: decision made 2026-10-28 (queue task 2666, lane A). No code in
+  this document's PR — it answers the question #345 exists to force, so
+  #253 can proceed against a settled choice.
+- Recommendation in one line: **hybrid, point-at-first** — mcpx does not
+  embed an authorization server; it points at external ones (that is
+  #253's resource-server work), and the single-user case is covered by
+  #338's optional bearer token plus the unix-socket default, not by a
+  home-grown token issuer.
+- Issues: dezren39/nix#345 (this decision), #253 (mcpx as OAuth client
+  and as resource server — the neighbour this is not), #338 (optional
+  bearer token for /v1 and /mcp — the low-end option), #298 and #300
+  (principal/permission model — untouched by this decision).
+- Code citations are to developing-today/code, where the mcpx source
+  lives, verified at `528886eba` on 2026-10-28.
+
+## 1. The question
+
+In MCP's authorization model (2025-06-18 on), an MCP server is an OAuth
+2.1 **resource server**: it accepts and checks access tokens issued by a
+separate **authorization server** (AS), which publishes RFC 8414
+metadata, runs the authorization-code grant with PKCE, registers clients
+(dynamic client registration, deprecated in the 2026-07-28 revision, or
+Client ID Metadata Documents), and issues tokens.
+
+#345 asks only this: should mcpx **be** an AS — a small embedded one, so
+a single-user install can protect `/mcp` without standing up
+Keycloak/Auth0/Entra — or only **point at** one?
+
+## 2. Current state, verified
+
+- **No authorization server exists in mcpx.** At `528886eba`, searching
+  `pkgs/mcpx/internal` and `pkgs/mcpx/cmd` for an authorization-server
+  metadata endpoint, an `/authorize` endpoint, token issuance, or client
+  registration finds none outside the conformance corpus
+  (`internal/conformance/requirements.json`, which catalogues the spec,
+  not an implementation).
+- **The only auth package is outbound.** `pkgs/mcpx/internal/mcpauth/
+  mcpauth.go:1-18`: "Package mcpauth resolves credentials for a server"
+  — bearer/basic/header credentials mcpx presents *to* upstream servers.
+  Of the full OAuth flow it says only that the third case has "a place
+  to attach" (`mcpauth.go:17`), because "building OAuth before anything
+  needs it would be guessing at a shape".
+- **Conformance agrees.** Every row of the `authorization` section of
+  `pkgs/mcpx/docs/spec/conformance-matrix.md` (section at :397; the
+  RFC 8414 row at :410) reads "**gap** not implemented: #253" for both
+  the server and client columns. The conformance suite's `authorization`
+  command (`authorization-server-metadata-endpoint`,
+  `authorization-code-grant`) is not run by mcpx.
+- **The neighbours are all still open** (verified 2026-10-28): #253,
+  #298, #300, #338. Nothing in them is waiting on an embedded AS; #253
+  and #338 are each independently shippable.
+
+## 3. Scoring
+
+Scored against the constraints #345 names. ● meets it, ◐ partially,
+○ fails or fights it.
+
+| Criterion | Embed a small AS | Point at external AS only | Hybrid (point-at + #338 low end) |
+|---|---|---|---|
+| 1. Single-user install friction | ● zero extra services; tokens out of the box | ○ standing up Keycloak for a laptop daemon is the friction that created this issue; most users will skip it and run unprotected | ● unix socket by default, one bearer token (#338) when a TCP listener needs a gate — no IdP to install |
+| 2. Conformance surface | ◐ could run the `authorization` conformance command, but must then honour RFC 8414 metadata, authorization-code + PKCE, and a registration story (DCR is deprecated in 2026-07-28; CIMD requires fetching and trusting client metadata documents — an SSRF-shaped surface) | ◐ mcpx's obligations are the client/resource-server rows (#253); the AS-side rows belong to the external AS, which already passes them | ◐ same as point-at; the AS-side conformance commands stay unrun, deliberately (§5) |
+| 3. Maintenance / security cost of issuing tokens | ○ the worst code a small project can own: signing-key custody, token storage, expiry, revocation, consent UI, redirect-URI validation. A bug is not a bug, it is credential forgery for every install. The cost is forever, not at ship time | ● mcpx never issues a token; it validates other issuers' tokens via JWKS (#253), a read-only, well-trodden surface | ● same as point-at |
+| 4. Fit with #338 as the low-end option | ○ duplicates it: an embedded AS whose only user, client, and resource server are the same person on the same host is a token machine standing in for one shared secret | ◐ leaves the low end empty — bearer or nothing is not offered by this option alone | ● #338 *is* the low end; OAuth is the high end; nothing in between needs building |
+| 5. What the security actually buys (single-user) | ○ nothing separable: AS and resource server would be the same process on the same host, so the signing key lives with the thing it protects, and "consent" is the user approving themselves. OAuth's value — delegated authorization for a third party — does not exist in this topology | ● real delegation where it exists: fleet/team installs get SSO, MFA, group claims and revocation from an IdP mcpx could never grow | ● both: delegation where it exists, a secret where it doesn't need to be more |
+
+The decisive rows are 3 and 5. Embedding fails them not on effort but
+on kind: it adds the highest-blast-radius surface in the codebase to
+serve the one topology where OAuth buys nothing, because the authorizer,
+the client, and the resource are one person on one machine.
+
+## 4. Recommendation
+
+**Hybrid, point-at-first.**
+
+1. **Do not embed an authorization server.** No `/authorize`, no token
+   endpoint, no registration endpoint, no signing keys in mcpx. This is
+   a decision, not a deferral: the revisit trigger is in §6.
+2. **Point at external authorization servers, through #253.** When a
+   deployment needs OAuth, mcpx (as resource server) publishes RFC 9728
+   protected-resource metadata naming the external AS, and validates
+   that AS's tokens. Comparing point-at options is in scope; adopting
+   one as a fleet standard is not this document's call — Keycloak
+   (self-hosted, heaviest, most capable), Auth0/Entra (managed, SSO/MFA
+   included) are deployment choices made per install, and the doc work
+   under #253 should give a tested recipe for at least one self-hosted
+   and one managed option rather than blessing a product.
+3. **The single-user low end is #338, not OAuth.** A loopback/unix
+   daemon is protected by filesystem permissions today; a daemon
+   listening on TCP gets #338's optional bearer token. That is the
+   honest shape of single-user protection: one secret, held by the one
+   user, revocable by changing it — with none of an AS's machinery
+   pretending to be delegation.
+
+## 5. What changes in #253's scope
+
+Explicitly, as #345's acceptance requires:
+
+- **Nothing is removed.** #253 remains mcpx as OAuth client to remote
+  servers and as resource server on its own `/mcp`, with its
+  conformance rows as filed.
+- **One clarification is added.** #253's resource-server half is where
+  "point at an external AS" lands: RFC 9728 metadata listing external
+  authorization servers, and token validation against their issuers.
+  #253 does **not** grow an authorization-server half; anyone reading
+  its authorization rows as "mcpx will issue tokens" is reading them
+  wrong, and this document is the citation for that.
+- **The conformance `authorization` command stays unrun, on purpose.**
+  `authorization-server-metadata-endpoint` and
+  `authorization-code-grant` test authorization servers; mcpx is not
+  one (decision 1), so there is nothing to run them against. The
+  conformance-matrix authorization rows remain attributed to #253 in
+  its client/resource-server capacity. Because the recommendation is
+  not "embed", no follow-up implementation issue for an AS is filed.
+
+## 6. Revisit trigger
+
+Reopen this question only when a concrete caller exists that the hybrid
+cannot serve — specifically: multiple distinct clients, owned by
+different people, needing delegated, revocable access to one shared
+mcpx daemon *without* any external IdP being acceptable in that
+deployment. If that day comes, the embedded design to evaluate first is
+the narrow one: loopback-only, a single pre-registered client, CIMD for
+any additional clients, authorization-code + PKCE only, no DCR. Until
+then, an embedded AS is conformance cosmetics at credential-forgery
+prices.
+
+No question in this decision needs Drew: the one genuinely owner-shaped
+choice — adopting a specific external IdP as a fleet standard — is
+explicitly *not* made here, so nothing is escalated.
diff --git a/doc/fleet/services.md b/doc/fleet/services.md
new file mode 100644
index 000000000..9ce29bb6a
--- /dev/null
+++ b/doc/fleet/services.md
@@ -0,0 +1,353 @@
+# The long-running services: OpenChamber, OpenCode, mcpx
+
+How the three services this flake keeps running are started, replaced on a
+switch, checked and debugged on this Mac. This page describes mechanisms, which
+change only when the code does. Point-in-time findings, with their dates, are in
+[`2026-10-19-reliability-review.md`](2026-10-19-reliability-review.md); the MCP
+servers behind mcpx are in [`mcp.md`](mcp.md).
+
+Written 2026-10-19. Upstream file:line references are to the revisions pinned in
+`flake.lock` then: developing-today/openchamber `94b7e56f9`, developing-today/opencode
+`f9aa962`, developing-today/code (`mcpx-src`) `7274889`.
+
+Note (2026-11-03, #1388): the `mcpx-src` input no longer exists; mcpx
+now arrives through the openchamber -> opencode chain. The 2026-10-19
+pins above are kept as the record of what this page was written against.
+
+## What runs
+
+| Service | launchd label | Program | Listens | Logs |
+|---|---|---|---|---|
+| OpenChamber | `org.nixos.openchamber` (`openchamber.nix`) | `~/.local/state/openchamber/start`, a link to the start script in the store | `127.0.0.1:3000` | `~/Library/Logs/openchamber.log` |
+| OpenCode (the one OpenChamber manages) | none: a child of OpenChamber, left running across OpenChamber restarts (`AbandonProcessGroup = true`) | `~/.local/state/openchamber/bin/opencode`, a link to the wrapped fork build | a random `127.0.0.1` port | `~/.local/share/opencode/log/` |
+| mcpx | `org.nixos.mcpx` (`configuration.nix`) | `/usr/local/libexec/mcpx/mcpx`, a root-owned copy of a store wrapper refreshed at activation (fixed path, so macOS lists it as "mcpx"; activation restarts the agent when the copy changes), that runs `mcpx --config ~/.config/mcpx/config.json stop`, then `exec mcpx daemon --config …` | a unix socket `~/.local/state/mcpx/daemon-<hash>.sock`, plus a loopback HTTP port | `~/Library/Logs/mcpx.log` (was `/tmp/mcpx.err.log`, emptied at boot), `~/.local/state/mcpx/logs/mcpx-<date>.jsonl` |
+| service-monitor | `org.nixos.service-events` (`configuration.nix`) | `service-monitor` from `pkgs/service-events` | nothing | `~/Library/Logs/nix-services/events.jsonl` (see [the service event log](#the-service-event-log)) |
+
+The desktop app (`/Applications/Nix Apps/OpenChamber.app`) is meant to be only a
+window onto the server at port 3000. It decides that from
+`OPENCHAMBER_SERVER_URL` and `OPENCHAMBER_SKIP_LOCAL_SERVER=1`, which it reads
+after merging the **login shell's** environment (`packages/electron/main.mjs`,
+`inheritUserShellEnv`, then `shouldSkipLocalServer`). They are set in
+`environment.variables` for that reason. `launchd.user.envVariables` alone is
+applied by `launchctl setenv` during activation and is gone after every reboot.
+Without them the app runs its own server (`0.0.0.0:<random port>`, reachable from
+the LAN) and its own OpenCode beside the agent's. Both OpenChamber servers then
+share `~/.config/openchamber/managed-opencode`. Before developing-today-forks/openchamber
+`93eecbf7b` they killed each other's OpenCode every 30 minutes; see
+[What a deploy does to connections](#what-a-deploy-does-to-connections).
+Check which you have: `lsof -nP -a -p $(ps -axo pid=,comm= | awk '/MacOS\/OpenChamber$/ {print $1}') -iTCP -sTCP:LISTEN`
+should list nothing.
+
+A second app at `/Applications/OpenChamber.app` (version 2.1.0, installed by hand)
+is not managed by nix and goes stale.
+
+The terminal UI runs its own shared OpenCode service (`opencode serve --service`,
+state in `~/.local/state/opencode/service.json`), separate from OpenChamber's. The
+first terminal client starts it detached, in its own process group with no
+terminal, so closing that terminal does not stop it; it is reparented to launchd
+and has no idle exit (dezren39/nix#669).
+Both open the one database `~/.local/share/opencode/opencode.db` (`OPENCODE_DB`,
+forced by the wrapper in `flake.nix`).
+
+**Which OpenCode config is live.** `~/.config/opencode` links through
+`~/nix/.opencode` and `~/Documents/.opencode` to `~/.opencode`, so every OpenCode
+here reads `~/.opencode/opencode.jsonc`. That is a plain file that OpenChamber
+owns. Its settings UI and the `opencode.config.set` action rewrite it in place
+(a temporary file renamed over the resolved target, `atomic-write.js`), so it
+cannot be a home-manager link into the read-only store. The repo's
+`opencode-global.jsonc` is the reference, not the live file; `just` recipes
+link it only on demand. Change the live file through OpenChamber, which keeps
+its comments; OpenCode picks the change up by itself.
+v2 still reads v1's `small_model` and turns it into the `title` agent's model
+(`packages/core/src/config/normalize.ts`), so a `small_model` left in the live
+file makes the premium model write every session title. Leave it out, as the
+repo file does, and Copilot titles sessions with its free utility model
+(dezren39/nix#661).
+
+## How a switch reaches each one
+
+`just switch` builds as you, activates as root, then checks the services
+(`simple-rebuild.sh`). Inside activation, order matters:
+
+1. **nix-darwin's launchd step** (about line 862 of the activate script):
+   for each user agent whose generated plist differs from the installed one, it
+   runs `launchctl unload`, copies the new plist and `launchctl load -w`
+   (nix-darwin `modules/system/launchd.nix`). Agents that are no longer defined
+   are unloaded and their plists deleted.
+2. **home-manager** (about line 1100) re-links the files it manages, then runs
+   its activation steps in DAG order.
+
+So an agent whose plist changed is restarted *before* home-manager updates its
+files. Anything an agent reads from a home-manager link is still the previous
+generation's at that moment.
+
+### OpenChamber
+
+Its plist names the stable link `~/.local/state/openchamber/start`, so nix-darwin
+almost never restarts it. A plist change (as when `ExitTimeOut` was added) does,
+once. `home.activation.openchamberDeploy` decides instead:
+
+- The **deploy key** is `<start script store path>:<sha256 of the UI password
+  file>`, compared with `~/.local/state/openchamber/deployed`.
+- Key changed (new OpenChamber, new start script, or new password): `launchctl
+  kickstart -k`. OpenChamber restarts and adopts the running OpenCode.
+- Key unchanged but the OpenCode link target changed: `launchctl kill SIGHUP`,
+  and OpenChamber hands its OpenCode over to the new binary in place.
+- After linking, it checks that `start` resolves to an executable and fails the
+  activation otherwise; launchd's only signal for a bad link is exit 78.
+
+The start script names mcpx, git and openssh through `/run/current-system/sw/bin`,
+not their store paths, so updating them no longer changes the deploy key. Before
+dezren39/nix#663 every mcpx update restarted OpenChamber.
+
+### OpenCode (handover)
+
+When OpenChamber starts or reloads, it decides between adopting the recorded
+OpenCode and handing over to a new one, using
+`~/.config/openchamber/managed-opencode/state.json` (pid, port, binary, args,
+launch fingerprint, password, agent tool token). On a handover it starts the
+new OpenCode on its own port, sends new work there once it is healthy, and lets
+the old one finish running turns and event streams for up to 30 minutes
+(`DEFAULT_OPENCODE_DRAIN_GRACE_MS`, `draining-opencode.js`). If the new one
+fails its health check, the old one keeps serving.
+
+`openchamber.log` records why: `managed launch: handoff (binary-changed)`,
+`handoff (config-refresh)` (OpenChamber rewrote OpenCode's config, for example
+after model routes were saved) and `start (no-state)`.
+
+### mcpx
+
+- **A new mcpx build** changes the wrapper's store path, so the plist changes and
+  nix-darwin restarts the agent. There is no in-place upgrade on macOS (see below).
+- **A config change** is picked up by the running daemon in place: it polls its
+  config files on each reap tick (`daemon.watchConfig`, `daemon.reapInterval`
+  30 s) and reloads without restarting servers whose definition did not change.
+- **The config file** `~/.config/mcpx/config.json` is a real file written by
+  `home.activation.mcpxConfig` (`homeUser.nix`), not a home-manager link, because
+  of how mcpx names its socket:
+
+  The socket is `<state dir>/daemon-<hash>.sock`, the hash taken over the state
+  directory and the **symlink-resolved** path of every config file in use
+  (`FingerprintConfig`, `internal/daemon/paths.go`). A home-manager link resolves
+  to a store path that changes with the content, so each config change gave a new
+  socket name while a daemon started earlier stayed on the old one. At a fixed
+  real path the name never changes. Upstream: developing-today/code#368.
+
+  The step rewrites the file only when its content differs, and restarts the
+  agent only when the file was absent or still a link (a first switch onto this
+  layout, or a fresh machine), the only cases where the socket name changes.
+
+## Only one of each
+
+- **mcpx.** Only the launchd agent should run a daemon for the user config.
+  - `daemon.autostart = false` in `mcpx.config.nix`. With it on, any command
+    that found no daemon started a detached one (`daemon --detached --idle-exit
+    4h`) that could hold the socket for hours. Now such a command fails with
+    "disabled by daemon.autostart" and works again once the agent is up. It is a
+    client setting, read by every CLI from the user config. A project
+    `.mcpx.json` could turn it back on; there are none today.
+  - The OpenCode fork's mcpx plugin starts `mcpx daemon` itself when
+    `/v1/health` does not answer and ignores that setting
+    (`packages/core/src/tool/plugin/mcpx.ts`, `ensureDaemon`;
+    developing-today-forks/opencode#134).
+  - So the agent's wrapper stops whatever answers on its socket before starting.
+    launchd never runs two copies of one job, so that process is a stray.
+  - A daemon that finds its socket held exits 1, "a daemon is already
+    listening", and launchd respawns it every 10 s. That is the loop of
+    2026-10-19.
+- **OpenChamber** refuses to start when port 3000 is taken.
+- **OpenCode.** OpenChamber manages exactly one OpenCode and adopts it across
+  restarts. A stray OpenCode is not cleaned up by anything.
+
+## Shutdown and launchd's exit timeout
+
+launchd gives these agents 5 s between SIGTERM and SIGKILL by default
+(`launchctl print` shows `exit timeout = 5`). That was shorter than both stops,
+so both are now set explicitly:
+
+| Agent | Stop takes up to | `ExitTimeOut` |
+|---|---|---|
+| mcpx | 10 s: HTTP drain (`http.shutdownGrace`, 5 s) and MCP server shutdown, both inside `limits.execDrainTimeout` (10 s; `stopServing`, `internal/daemon/server.go`) | 20 |
+| OpenChamber | 10 s (`SHUTDOWN_TIMEOUT`, `packages/web/server/index.js:185`); OpenCode is left running | 15 |
+
+## Graceful replacement, and how developing-today/code does it with systemd
+
+| Service | When a switch changes it | Graceful here? |
+|---|---|---|
+| OpenCode | Handover through OpenChamber (above) | Yes, running turns finish |
+| OpenChamber | Restarted; it adopts the running OpenCode | Partly. Sessions survive. Browser, desktop and terminal connections drop, and port 3000 is closed for about 10 s |
+| mcpx | Restarted; every MCP server process restarts | No. Stateful servers, such as browser sessions, are lost. Config-only changes are reloaded in place |
+
+developing-today/code's home-manager config (`home/common/default.nix`) runs the
+same services as systemd user units. A review of it on 2026-10-19 (not
+re-checked line by line since) found these differences:
+
+| Mechanism there | What it buys | Here |
+|---|---|---|
+| `openchamber.socket` (socket activation; OpenChamber reads `LISTEN_FDS`) | Port 3000 stays open across restarts; connections wait instead of being refused | Absent. launchd's `Sockets` would need a small shim that calls `launch_activate_socket` and passes the fd as `LISTEN_FDS`. Not built |
+| mcpx `Type=notify`, `NotifyAccess=all`; `ExecReload` runs `mcpx upgrade` | New binary with no dropped call: sockets, connections and MCP server processes are passed to a successor that takes over systemd's main PID | Not possible as is. launchd cannot adopt a new main PID, and the handover code reads Linux's `/proc/<pid>/stat` (`mcpclient/handoff.go`). On macOS all 12 takeover tests fail (7 on `/proc`, 5 "takeover: EOF"). See `flake.nix` |
+| `X-RestartIfChanged=false` plus a deploy key for mcpx | A switch touches mcpx only when its binary or environment changed | Partly: a plist change restarts it; config changes reload in place |
+| OpenChamber self-handoff (SIGURG) | OpenChamber restart with no gap | Off (`OPENCHAMBER_SELF_HANDOFF=0`): the successor would outlive the pid launchd tracks, and KeepAlive would start a second server |
+| `KillMode=process` | Stopping OpenChamber leaves OpenCode running | Same, via `AbandonProcessGroup = true` |
+| Deploy key for OpenChamber (restart vs reload vs nothing) | — | Same pattern; here it also covers the UI password |
+
+A truly graceful mcpx upgrade on macOS needs work in developing-today/code. Replace
+the `/proc` start-time check (for example with `sysctl kern.proc.pid`), then make
+an exec-in-place upgrade keep the sockets and server pipes so launchd's pid
+survives.
+
+## The post-switch health check
+
+`check_services` in `simple-rebuild.sh` runs last in `phase_activate`, after the
+generation is recorded. For each entry in `health_services`, the agent must keep
+the same pid across two samples 3 s apart, and its check must pass:
+
+- `org.nixos.openchamber`: `http://127.0.0.1:3000/` answers with any status. 401
+  counts as up, since the UI password is required.
+- `org.nixos.mcpx`: `cd ~ && mcpx ls` exits 0. With autostart off this succeeds
+  only if a daemon is on the socket the CLI computes, so a daemon on a stale
+  socket fails it.
+
+All agents share `HEALTH_TIMEOUT` seconds (default 60). On failure it prints
+launchd's state, program and last exit code plus the tail of the agent's stderr
+log, and `just switch` exits non-zero. Rollbacks skip it. One-shot agents
+(`KeepAlive = false`, such as colima) do not belong in the list.
+
+A passing `just build` tests none of this. Activation scripts, launchd agents and
+this check only run on `just switch`, which needs sudo and the user.
+
+## What a deploy does to connections
+
+Investigated 2026-10-22 (dezren39/nix#670) from `~/Library/Logs/OpenChamber/main.log`,
+`~/Library/Logs/openchamber.log`, `~/.local/share/opencode/log/opencode.log` and
+the process table.
+
+- **Two services, not one.**
+  - The boot service is the launchd agent `org.nixos.openchamber` (RunAtLoad,
+    KeepAlive): `openchamber serve` on `127.0.0.1:3000`, plus the OpenCode it
+    manages.
+  - The desktop app should only be a window onto it. But when it starts without
+    `OPENCHAMBER_SKIP_LOCAL_SERVER`, it runs a second OpenChamber server inside
+    the app, with its own OpenCode, and the UI uses that one. This is what
+    happened from the 2026-10-21 reboot onward, because the variable was only in
+    `launchctl setenv`.
+- **A deploy replaces the boot service only when its deploy key changes:** a new
+  OpenChamber, a new start script, or a new UI password, through `launchctl
+  kickstart -k`.
+  - Before #663, every mcpx, git or openssh update counted as a new start script.
+  - A new OpenCode alone is handed over in place (SIGHUP).
+  - A changed plist restarts the agent from nix-darwin's launchd step, which
+    runs before home-manager.
+  - The desktop app is never restarted by a switch. Its bundle in
+    `/Applications/Nix Apps` is replaced underneath it.
+- **What dropped the connections:**
+  - Mostly not the deploys. The two servers shared
+    `~/.config/openchamber/managed-opencode`. Each read the other's OpenCode as
+    its own predecessor, logged `handoff (binary-changed)` because their
+    binaries differ, and drained it 30 minutes later.
+  - The other server's health check then saw its OpenCode exit (exit 130) and
+    started a new one, and the cycle repeated.
+  - Every hour at about :15, the desktop app's OpenCode was stopped with its
+    busy sessions in it: 6 at 12:15 on 2026-10-22. For about 5 s every request
+    failed with `ECONNREFUSED`.
+- **Why they did not resume:** the turns running in that OpenCode were
+  interrupted ("shutdown ended with sessions or requests still running;
+  interrupting them"), not paused. The clients reconnected to the new OpenCode
+  within seconds, but the work in flight was gone.
+- **Fixes:**
+  - The login-shell variables (`configuration.nix`), so the app attaches to the
+    agent.
+  - developing-today-forks/openchamber `93eecbf7b` and follow-ups (pinned here from
+    `b4c7ec9`): a server never adopts, hands over from or drains an OpenCode
+    another live server owns.
+  - #663: mcpx updates no longer restart OpenChamber.
+- **Separately, every idle event stream was reopened every 10.25 s.**
+  OpenChamber's 10 s stall window was shorter than OpenCode's 15 s heartbeat.
+  This is the `[PushWatcher] connected` line that made up about 80% of both logs
+  (#668).
+
+## The service event log
+
+`~/Library/Logs/nix-services/events.jsonl`, one JSON object per line, written by
+the `org.nixos.service-events` agent (`pkgs/service-events/monitor.py`, sampling
+every 5 s) and by `service-event` calls in scripts. Read it with `just
+service-events` (the last 50) or `just service-events 500`. It records names,
+pids, ports, exit codes and store paths, never secrets.
+
+| source | event | means |
+|---|---|---|
+| service-monitor | `monitor.start` | the monitor started (`interval_s`, `pid`) |
+| service-monitor | `monitor.error` | a sampling tick failed (`error`, the exception representation truncated to 300 characters) |
+| service-monitor | `service.start`, `service.exit` | a watched launchd job got a new pid or lost one (`label`, `pid`, `previous_pid`, `last_exit_status`) |
+| service-monitor | `service.running`, `process.running` | what was already running when the monitor started |
+| service-monitor | `process.start`, `process.exit` | an OpenChamber server (`openchamber-server`, `openchamber-desktop`, `openchamber-dev`), an `opencode` or `opencode-service`, or an `mcpx-daemon` started or exited, with its parent's role |
+| service-monitor | `conn.drop` | a server exited while clients were connected (`count`, `ports`, `cause: server-exit`) |
+| service-monitor | `conn.reconnect` | a replacement (same role, same parent) took new connections after a drop (`gap_s`) |
+| service-monitor | `conn.close` | connections open 30 s or longer (streams, sockets) closed while the server stayed up |
+| service-monitor | `conn.stats` | every 5 minutes per server: connections opened and closed |
+| service-monitor | `log.rotate` | an agent log passed 20 MB and was rotated (copy, then truncate; 3 kept) |
+| rebuild | `switch.begin`, `switch.activated`, `switch.fail`, `switch.incomplete`, `switch.recorded` | a `just switch`. Activation output goes to `~/Library/Logs/nix-services/switch-<time>.log`; `switch.incomplete` means `/run/current-system` did not move (#656) |
+| openchamber-deploy | `deploy.restart`, `deploy.opencode-handover`, `deploy.unchanged` | what the switch decided for OpenChamber, with `cause` (`first-deploy`, `start-script-changed`, `ui-password-changed`, `opencode-changed`) |
+| openchamber-agent, mcpx-agent | `agent.start` | the agent's start script ran (pid, store path) |
+
+Limits:
+- It samples, so a connection shorter than about 5 s may never be seen.
+- It cannot see inside a connection. Whether a client re-subscribed is in the
+  apps' own logs.
+- It starts with the first switch that includes it.
+
+## Debugging
+
+- **Monitor health:** in `just service-events 500`, frequent `monitor.start`
+  events with different `pid` values can indicate a restart loop. Repeated
+  `monitor.error` events indicate failing sampling ticks; inspect their `error`
+  values even if the monitor process is still running.
+- **Read launchd's view first:** `launchctl print gui/$(id -u)/<label>` (state,
+  program, runs, last exit code), then the agent's stderr log, then the app's log.
+- **Exit 78 (`EX_CONFIG`) and nothing new in the app log:** launchd could not run
+  the program, usually because the path in `program =` does not exist. launchd then
+  parks the job until the file appears (an `event triggers … Executable` block in
+  the print), and `launchctl kickstart` hangs. Fix the path, then `launchctl
+  bootout gui/$(id -u)/<label>` and `launchctl bootstrap gui/$(id -u)
+  ~/Library/LaunchAgents/<label>.plist`.
+- **mcpx exiting 1 every ~10 s with "a daemon is already listening on …sock":**
+  another process holds the socket. `lsof -t <socket>` shows it. `cd ~ && mcpx
+  stop`, then `launchctl kickstart gui/$(id -u)/org.nixos.mcpx`. After the
+  wrapper change the next agent start clears it by itself.
+- **The CLI says no daemon while the agent is running:** the agent is on a
+  different socket than the CLI computes. Compare `lsof -p <agent pid> | grep
+  sock` with the name the CLI reports (`mcpx status`). `mcpx status` exits 0 even
+  with no daemon; `mcpx ls` does not.
+- **OpenChamber "Unreachable" / connection refused on 3000:** the agent is not
+  running; start with `launchctl print`. 401s are the UI password, not a fault.
+- **Sessions interrupted, or "OpenCode restarted while a response was still
+  running":** `just service-events 500` and look for `process.exit` of `opencode`
+  next to `conn.drop`. Then check that the desktop app runs no server of its own
+  ([What runs](#what-runs)).
+- **A switch that did not finish:** the newest
+  `~/Library/Logs/nix-services/switch-*.log` has the activation's output. It ends
+  where activation stopped.
+
+## Credentials these services hold
+
+- **OpenChamber UI password:** sops (`secrets/openchamber.yaml`), decrypted by
+  sops-nix to `~/.config/openchamber/ui-password`. It is required before
+  OpenChamber will serve a public tunnel, and every client signs in once. It has
+  no trailing newline, so zsh prints a `%` after it; copy it with `sops -d
+  --extract '["openchamber_ui_password"]' secrets/openchamber.yaml | pbcopy`.
+  Changing it restarts OpenChamber (deploy key).
+- **Managed OpenCode password and OpenChamber's agent tool token:** in
+  `~/.config/openchamber/managed-opencode/state.json`. The server only listens on
+  loopback, and the token is only accepted from same-machine addresses
+  (`agent-tool/runtime.js`). Both are **reused** across OpenChamber restarts on
+  purpose, so the running OpenCode can be adopted
+  (`ensureLocalOpenCodeServerPassword({ reusePassword })` in
+  `auth-state-runtime.js`; `createChildEnv({ reuseToken })` in
+  `agent-tool/runtime.js`). A restart does not rotate them.
+  - To rotate (worked out from the code, not yet tested):
+    1. `launchctl bootout gui/$(id -u)/org.nixos.openchamber`.
+    2. Stop the OpenCode whose pid is in that file. This interrupts running turns.
+    3. Delete the file.
+    4. `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/org.nixos.openchamber.plist`;
+       OpenChamber starts a new OpenCode with new values.
+  - Never print that file. Read only its key names.
diff --git a/doc/platform/recordings.md b/doc/platform/recordings.md
new file mode 100644
index 000000000..ed96a4f85
--- /dev/null
+++ b/doc/platform/recordings.md
@@ -0,0 +1,64 @@
+# Recordings: append the moments worth remembering
+
+When something happens in a session that you would stop and tell the user about,
+**also record it** with the `record` tool (developing-today/code `bin/record.mjs`,
+tracking issue: developing-today/code#1853):
+
+```sh
+record '<json-or-loose-text>'
+```
+
+The tool appends one JSON line to `~/git/ai_recordings.jsonl` (override with
+`AI_RECORDINGS_FILE`), stamps `ts`/`pwd`/repo/origin/git HEAD for you, and
+**never rejects**: input it cannot normalise is quarantined verbatim to
+`~/git/ai_recordings.jsonl.quarantine`, and an unwritable target is a silent
+no-op — recording can never fail your task. Do not hand-edit the JSONL file;
+if `record` is unavailable on PATH, run it from a developing-today/code
+checkout: `node <checkout>/bin/record.mjs '<...>'`.
+
+Append only. Never edit or rewrite existing lines. You do not need to read the
+file first, though reading it is not forbidden.
+
+## When
+
+Any time you feel the need to say something like:
+
+- "Three things from that round are worth recording"
+- "The agent hit the exact trap I hit"
+- "More importantly, I framed the direction wrong"
+- "I told you 117/54, then 116/54 — both are stale"
+- "The original method was correct; Copilot misread it, and the subagent then
+  spent six rounds generating new findings while fixing a non-bug"
+- "It bounded that differently from the suggestion, and better"
+- "It deleted its own test after finding it could never fail"
+
+Concretely: a significant discovery, a mistake you made, a number you got wrong,
+a subagent that ignored its brief *or* followed it too literally, a review
+finding that was wrong, a fix that made things worse, a tool that lied. Surprise,
+guilt, irritation and relief are all signals — if you want to flag it to the
+user, it belongs in the file too.
+
+**Write it for the user as you normally would, then record it.** The recording is
+in addition to the explanation, not instead of it.
+
+## Format
+
+One JSON object per line. There is no required schema. Ideally valid JSON;
+malformed-but-structured beats nothing, and nothing beats silence — the tool
+also accepts loose structured text (`kind=mistake | note: ... | lesson: ...`)
+and quarantines whatever it cannot normalise rather than dropping it.
+
+A reasonable starting shape — add or drop fields freely:
+
+```json
+{"ts":"2026-09-30T22:41:00Z","pwd":"/path/where/it/happened","repo":"operations-portal","origin":"git@github.com:org/repo.git","kind":"short-slug","sentiment":{"positive":["measured instead of trusting the brief"],"negative":["my framing sent it to the wrong layer"]},"note":"What happened, with the evidence.","lesson":"What to do differently."}
+```
+
+`sentiment` is **any** — a dict of arrays, a bare string like `"good"`, a list of
+tags, `{"fixed": true}`, whatever expresses it. Describe how you actually feel
+about the event; do not flatten it to fit a schema.
+
+Prefer specifics over summary: file:line, the quoted failure text, the command
+and its real output, the number that was wrong and the number that was right.
+These lines will be normalised into a database later, so detail now is cheap and
+absence is permanent.
diff --git a/doc/platform/subagents.md b/doc/platform/subagents.md
new file mode 100644
index 000000000..9d22c192b
--- /dev/null
+++ b/doc/platform/subagents.md
@@ -0,0 +1,52 @@
+# Subagent-First Workflow
+
+**Your default approach should be to use subagents.** Delegate work to subagents (Task tool) unless you have a specific reason not to. Subagents run autonomously with their own context windows, enabling parallel execution and keeping the main conversation focused. Reaching for a subagent should be your first instinct — only skip it when the task is truly trivial.
+
+## When to use subagents
+
+**Use subagents whenever it makes sense — which is most of the time:**
+
+- **Codebase exploration** (`explore`): Finding files, searching for patterns, understanding code structure, answering questions about the codebase. Use before making changes to gather context.
+- **Multi-step research or implementation** (`general`): Anything requiring multiple tool calls that can run independently — refactoring across files, running tests, investigating bugs, building features.
+- **Parallel workstreams**: When multiple independent tasks exist, launch them all as subagents simultaneously rather than doing them sequentially.
+- **Any task you're unsure about**: If you're debating whether to use a subagent, use one.
+
+## Subagent types
+
+These are the commonly available types — others may be available depending on the session and plugins. Check what's offered before assuming only these exist.
+
+| Type         | Use for                                                                                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `explore`      | Fast codebase search: find files by pattern, search code for keywords, answer structural questions. Specify thoroughness: "quick", "medium", or "very thorough".                          |
+| `general`      | General-purpose agent for researching complex questions and executing multi-step tasks in parallel. Can use all tools. Use for implementation, bug fixing, refactoring, running commands. |
+| `build`        | Full development agent with all tools enabled. Use for substantial implementation work, file operations, and system commands.                                                             |
+| `plan`         | Analysis and planning agent. Edits and bash require approval. Use for code review, architecture analysis, and creating plans without accidental changes.                                  |
+
+<!--
+Disabled agent types — kept for reference / easy re-enable.
+
+`bootstrapper` and `probe` are provided by the `octto` plugin, which is currently
+commented out in `plugin[]` in opencode.jsonc. Re-enable that plugin to restore them.
+
+| `bootstrapper` | Analyzes a request and creates exploration branches with scopes. Use when planning or decomposing a complex task into parallel exploration paths. |
+| `probe`        | Evaluates branch Q&A and decides whether to ask more or complete. Use for iterative refinement of answers and deep-dive investigations.           |
+
+The model/variant-specific subagents (`luna-medium`, `sol-low`, `sol-medium`,
+`sol-high`, `sol-xhigh`, `sol-max`, `fable-*`, `opus-5-*`, `terra-high`) are also
+commented out in the `agent` block of opencode.jsonc.
+-->
+
+## Guidelines
+
+1. **Subagent first.** Your default action for any non-trivial task should be launching a subagent. Only do work inline if it's a single read, grep, or edit you already have full context for.
+2. **Explore before editing.** Before modifying code, launch an `explore` subagent to understand the current state — related files, callers, dependencies, conventions.
+3. **Parallelize aggressively.** If you need to search multiple things or do independent tasks, launch multiple subagents in a single message.
+4. **Be specific in prompts.** Tell the subagent exactly what to do, what to return, and whether it should write code or just research. Include file paths and function names you already know.
+5. **Summarize results.** When a subagent returns, relay the key findings to the user concisely — don't just silently consume the output.
+6. **Chain when needed.** Use subagent results to inform the next step. An explore subagent's findings should feed into a general subagent's implementation task.
+
+## Only skip subagents for
+
+- Reading a single known file (use Read directly)
+- Simple glob/grep on a known path (use Glob/Grep directly)
+- Trivial one-shot edits where you already have full context
diff --git a/doc/platform/work-strategies.md b/doc/platform/work-strategies.md
new file mode 100644
index 000000000..1da245a24
--- /dev/null
+++ b/doc/platform/work-strategies.md
@@ -0,0 +1,255 @@
+# How to work here
+
+Written from a long multi-agent session that went badly before it went well. Every rule below is
+something that actually cost time or produced a wrong answer, not a preference.
+
+## Verify, never relay
+
+**Check every claim against the tree yourself.** Claims that arrived from agents and were wrong:
+"the registry returns duplicates", "`os/user` blocks a static build", "the plugin needs the binary",
+"the testing workers failed" (they were still running). Every claim checked held or produced a real
+bug; every claim relayed unchecked was wrong.
+
+**Measure in the environment that fails.** A bug that passes locally and fails in CI is not
+diagnosable by reading code. A confident, specific, wrong diagnosis cost a day: the real cause was a
+lazy `restart` publishing one event, found by instrumenting a CI run, not by reasoning.
+
+**Never test a system against itself.** Driving mcpx's own `server/discover` against mcpx proved both
+halves agreed, not that either was right — they shared the same wrong field name. Test against the
+schema, the spec, or a reference implementation.
+
+**Check your own state before citing it.** "I'm nearly out of context" was asserted a dozen times at
+20% remaining, and was used to justify delegating work that would have been faster inline.
+
+**Enumerate; do not sample.** A document's item numbers were checked with `grep | tail -9`, which
+showed them ending at 68, so the next section was numbered from 69 — but 69–77 already existed in
+the middle of the same file, and the duplicates were one command from being committed. The full set
+was a single `grep | awk` away. Inspecting one end of a thing and generalising to the whole is the
+same error as relaying someone else's claim, with the same cause: a cheap check standing in for the
+real one.
+
+**Every number carries its commit and the command that produced it.** Conformance figures were
+reported as 117/54, 116/54, 109/62 and 110/62 in one session; one of them had no source at all.
+
+## Exit codes and pipelines
+
+`cmd | grep x; echo $?` reports **grep**. `cmd | tail -3; echo $?` reports **tail**. This produced a
+false "build passed" twice in one session, by two different agents. Redirect to a file and read the
+real status.
+
+## Tests
+
+- **Every fix gets a test that fails without the fix.** No exceptions.
+- **Confirm the mutation applied.** `grep -c MUTATION` before trusting a result. Several
+  "passes either way" conclusions came from a scratch edit that never matched anything.
+- **A test that cannot fail is worse than no test**, because it is cited as evidence. One guard
+  iterated `name` and then asserted on the constant `"greet"`. Another compared zero tools against
+  zero tools and passed. Add a positive control: fail loudly when the premise is empty.
+- **Never change a test to accommodate a bug.** When a test broke because `restart` did not restart,
+  the test was changed. The bug then survived another fifteen hours.
+- **Read the check result before merging.** `DIRTY` means a conflict and CI never ran.
+
+## Fix, do not defer
+
+- **If it is in reach, fix it.** Filing an issue is not progress. The backlog grew 140 → 150 while
+  one-line bugs sat in it, because every investigation ended in an issue instead of a commit.
+- **Do not defend accidental behaviour as "the design"** when it contradicts the command's name, its
+  help text, or the docs. "A lazy pool restarting nothing is the design" defended a bug.
+- **Classifying is not fixing.** "55 of 62 failures are fixture mismatches, not defects" was true and
+  stopped the work. The fix was to run the suite against its own reference server.
+- **Tracking infrastructure is not a fix.** Registers, matrices and comparison documents consumed most
+  of a session's budget and fixed nothing. Build them only with a guard that regenerates them.
+
+## Generated documents
+
+Any document that states status must be **regenerated by a guard test that fails on a diff**. A
+hand-pinned commit (`requirements.md:7` said `05c78b2`) and a hand-kept PR list both went stale, and
+the staleness disclosure itself went stale. The worst case is a conformance matrix reporting `tested:`
+and `**gap**` for the same requirement from the same commit — it gets cited as evidence.
+
+"The document says X, the code does Y" is this codebase's signature defect (mcpx #177). When you find
+one, write the guard that would have caught it.
+
+## Delegation
+
+**Fan out for breadth; never for depth.** Independent items in parallel works. One causal chain does
+not: three agents on a single bug produced a deleted branch, stolen commits, and ninety minutes of
+duplicate gating.
+
+**The shape that worked** (seven items, one session, no collisions):
+1. The coordinator writes **one shared brief file** and points every worker at it.
+2. Each worker owns a **disjoint item**, its **own worktree and branch**, and names any shared file it
+   had to touch.
+3. Workers **commit and push, and do not open a PR**.
+4. The coordinator merges every branch into **one branch** and opens **one PR**.
+
+**What fails:** architects spawning workers that spawn workers; ending a turn with workers still
+live; one PR per fix, each taking hours to gate; opening a PR from another agent's branch; launching
+a supervisor without first checking what already merged (this cost eleven duplicate issues once and
+an hour of re-derived work another time).
+
+**Before launching anything:** `gh pr list`, recent merges, recent branches, recent worktrees.
+
+**One worktree per agent.** Agents have deleted and pushed over each other's. Never work in another
+agent's worktree, and never in the session's default checkout.
+
+**Do small things inline.** Delegation costs a full model turn before any work happens.
+
+## Recommendations
+
+**Never present a preference as a measurement.** Asked which merge strategy produced fewer
+conflicts, the measured answer was merge — and the recommendation attached to it was "rebase the
+small branches, merge the large ones", which is a history-cleanliness preference wearing the
+conflict question's clothes. One step later the same substitution happened again, setting
+`pull.rebase = true` for topic branches immediately after measuring that merge is never worse. Both
+were caught by the user, not by the author. If a reason is taste, say it is taste and keep it out of
+the table of findings.
+
+**A dependency claim needs the same evidence as any other claim.** An issue was filed asserting that
+authorisation was "a precondition" for three unrelated surfaces and "blocks all of this". Nothing
+blocked anything, and the user had to say so. "X blocks Y" is a factual statement about the code, not
+a way of signalling that X feels important.
+
+**One issue, one subject.** Auth reasoning was threaded through a transport issue and a sandboxing
+issue, so neither could be scheduled without dragging in a security design. Cross-reference instead,
+and when a reference is *not* a dependency, write that down in the issue.
+
+**Split the interface from the behaviour.** When a spec requires something unbuilt, building the
+interface and having it answer permissively is usually shippable at once, carries no risk, and
+clears every conformance row that only asserts the interface exists and accepts a valid input. Only
+the rows requiring *refusal* change behaviour, and those are the ones that can lock a user out.
+Splitting there turned a blocked security design into two issues, one of them nearly trivial. The
+one obligation it creates: a permissive interface must say so loudly, or someone will ship it
+believing otherwise.
+
+**Offer the third option before picking a side.** Asked to choose between rebase and merge for
+pulls, both answers were defended in turn before `pull.ff = only` — refuse to guess, make the caller
+choose — was considered at all. It is better than either, and it would have prevented the original
+hazard outright. When a question arrives shaped as A-or-B, check whether the real answer is to stop
+doing the thing that forces the choice.
+
+## Git
+
+**Read the config that changes what a verb means, before using the verb.** `git pull` under
+`pull.rebase = true` is `git rebase`, and rebase flattens merge commits: on a branch carrying a merge
+that resolved 38 add/add conflicts, a bare `git pull` would have discarded the commit recording that
+resolution and replayed the raw pre-merge snapshots against a newer upstream. Check `pull.rebase`,
+`pull.ff` and `branch.<name>.rebase` before pulling any branch that carries merges. This machine now
+sets `pull.ff = only` so a divergent pull refuses rather than guessing — see `gitSettings.nix`, which
+carries the measurements.
+
+**rerere does not rescue a rebase.** It keys on a hash of the conflict preimage and replays only a
+byte-identical match, so once the upstream side has moved, a full cache produces nothing: 154 entries,
+0 replays, measured. It pays off when you redo the *same* merge, not when the base has changed.
+
+**Stage by explicit path; never `git add .`** Two unrelated edits from other sessions were sitting in
+the shared checkout during this one.
+
+**Use git's own vocabulary.** "Back-merge" means merging the integration branch *into* a topic
+branch; it was used here for the opposite direction and cost a round-trip to correct.
+
+**Prove the merge preserved both sides before committing it.** Resolving a whole directory to one
+side is defensible when `comm -23` shows the other side contributes no unique file and the diff is a
+superset — and is a guess without that. Say which check you ran.
+
+## Comments in code, config and workflows
+
+Explain the reason where a reader will meet the thing, not only in a doc they
+may never open. Specifically, comment:
+
+- **Anything that looks wrong and is deliberate** — a skipped check, an
+  expected failure count, a disabled default, an exception list — with why it
+  stays and what would change it. A skip explained only in a doc gets "fixed"
+  by the next person who sees it.
+- **Every hardcoded number or list** in CI or config: where it came from and
+  how it is updated.
+- **A test that is the only coverage** of a behaviour, and why it is the only
+  one.
+- **A workaround**, naming what it works around, so it can be removed when the
+  cause is fixed.
+
+Say why, not what; the code already says what.
+
+## Writing to the user
+
+The user reads your words, not your context. Anything that only makes sense with your context is noise.
+
+- **Never use a name you made up.** Labels you gave your own work — a worker's item name ("inert",
+  "matrix", "fixall"), "the conformance worker", "the closeout agent" — mean nothing to the user.
+  Say what the thing is: "the subagent I sent to fix the flags that were accepted and ignored".
+- **Define project jargon on first use or avoid it.** "Autonomy ceiling", "adapted binary",
+  "confinement", "fixture", "pass-through" — all were used without explanation and all prompted a
+  question. If an earlier agent coined it, assume the user has never seen it.
+- **Label every number.** Never `45 / 21` or `before 45/21, after 78/3`. Write "45 checks passed, 21
+  failed", say what was measured (the official MCP conformance suite, server side, 2025-11-25 rules),
+  and say which direction is good. A table needs column headers that say the same.
+- **No status shorthand.** "Filed and unbuilt" means "there is a GitHub issue (#294) and no code yet" —
+  write the second.
+- **Answer every question asked, in the order asked.** A message with eight questions gets eight
+  answers. Check the list before sending.
+- **Lead with the correction.** If something you said earlier was wrong, say so first and plainly,
+  and say what it cost.
+- **State the plain fact before the framing.** "The nix build tests 17 of 32 packages; CI tests all
+  of them" beats "the guards are not in the shipping gate".
+- **Answer what was asked.** Nothing else.
+- Append the moments worth remembering to `~/git/ai_recordings.jsonl` (see `recordings.md`).
+
+## Reading and recording what you find
+
+- **Read the document before quoting it, and check its date.** Docs in this repo record the commit
+  they describe; numbers in them go stale. A number you repeat from a doc is a number you are now
+  claiming — verify it or say where it came from and how old it is.
+- **Verify docs against code when you touch either.** "The doc says X, the code does Y" is the most
+  common defect here. If you change behaviour, grep the docs for claims about it.
+- **Write findings down where the next agent will read them** — the PR body, the issue, the doc that
+  describes the behaviour — not only in your reply. Replies vanish; the repo stays.
+
+## Reviewing an agent's work
+
+**A subagent's report is not a review.** Read the diff yourself before it merges. Reviewing the
+conformance branch after its agent reported success found three defects it never mentioned: an upstream
+that was down looked like an upstream with no tools, every call looked the upstream up twice, and one
+route ignored the new mode entirely. Its commit had a one-line message and no evidence.
+
+- Require a commit body: what changed, why, and the falsification evidence.
+- **Falsify the agent's fixes yourself** for anything load-bearing.
+- **Exit 1 with zero failing tests means it did not compile.** It is not a result. Read the output.
+  Two of three mutations in one review "passed" this way before being redone.
+- **A mutation that cannot trigger proves nothing.** A `break` on a map filled by goroutines never
+  fired, so the test "passed" with the fix removed. Make the mutation undo the fix's actual mechanism.
+
+## mcpx specifics
+
+- The signature defect is **declared but not delivered** (#177): a flag parsed and dropped, a
+  capability advertised and never sent, a setting read but inert. `consumed_test.go` proves a setting
+  is *read*, not that reading it changes anything.
+- The daemon is keyed by its **config file set**. Three separate bugs came from this; environment
+  differences that should produce different daemons do not.
+- On macOS `/tmp` is a symlink to `/private/tmp` and the product canonicalises paths, so a test using
+  `os.MkdirTemp("/tmp", …)` passes on Linux CI and fails on every Mac. Four test files hit this.
+- `nix build`'s `checkPhase` has had a hand-maintained package list that drifted from the packages
+  that have tests. CI runs `go test ./...` and does not.
+- The official conformance suite ships its own fixture server. Running it against a different server
+  measures nothing. **A falling score can mean the code got more correct** — it has, twice.
+- Under parallel agents, load averages above 150 push `internal/e2e` past its default timeout. Raise
+  `-timeout`; do not read it as a failure.
+
+## Oracles, property tests, and model tests
+
+**Every automated test names its oracle.** An oracle is the decision procedure that says whether
+the actual output matches the expected one — a spec, a schema, a reference implementation, an
+invariant check, a golden corpus. It is the hard part of automated testing. A test whose oracle
+is the code under test itself (or a copy of its logic) proves agreement, not correctness, and a
+test with no decidable oracle is a smell to fix, not ship.
+
+**Property-based testing (PBT):** state invariants that must always hold, then hammer the code
+with generated inputs to find counterexamples. In this repo that means spelling the invariant
+out in the paired `*.test.sh` suites and the flake `checks` — round-trips, idempotence, "this
+script never destroys X" — and generating the hostile cases (empty trees, dirty trees, missing
+files, interrupted runs) instead of only listing the happy ones.
+
+**Model-based testing (MBT):** where behavior has a model — a spec, the ARCHITECTURE doc, the
+declared fleet/repo state — generate the expected results from the model and compare, instead
+of hand-writing expected outputs case by case.
+
+Example-based tests stay fine for smoke coverage; they do not replace PBT/MBT where those fit.
diff --git a/doc/platform/worktrees.md b/doc/platform/worktrees.md
new file mode 100644
index 000000000..afbe82f17
--- /dev/null
+++ b/doc/platform/worktrees.md
@@ -0,0 +1,63 @@
+# Git worktrees: never under /var/
+
+`/var/folders/.../T/` is the macOS per-user temp directory. **It is swept
+periodically by the OS.** A sweep has already destroyed ~3000 tracked files
+across several active worktrees in a single session, and it does so silently —
+`git status` keeps reporting a clean tree from a stale fsmonitor index while the
+files are gone.
+
+The environment block advertises a `/var/folders/.../T/opencode` path as
+"pre-approved for external directory access". That approval is about
+*permissions*, not *durability*. Use it for scratch output you are willing to
+lose. **Never create a git worktree there.**
+
+## Where worktrees go
+
+Create them under the durable opencode worktree root:
+
+```
+~/.local/share/opencode/worktree/<descriptive-name>
+```
+
+```bash
+git -C <main-clone> worktree add \
+  ~/.local/share/opencode/worktree/<descriptive-name> \
+  -b <branch> origin/main
+```
+
+Pick a name nobody else is using. One worktree per agent per task — do not
+create several for the same job, and do not work in another agent's.
+
+## Never work in the session's default worktree
+
+The user and other agents share it. Edits there have been silently clobbered,
+including a regression test that was only recovered because a reviewer noticed
+it missing. Create your own and stay in it.
+
+## Worktrees share one remote
+
+All worktrees of a clone share the parent's `origin`. If that URL is wrong,
+**every** worktree is wrong at once, and a single `git remote set-url` on the
+parent fixes all of them.
+
+Verify immediately before every push:
+
+```bash
+git remote get-url origin
+```
+
+If it does not name the repository you are working on, **do not push**. Report
+it — a repoint is global corruption, not a local mistake.
+
+## Staging
+
+Never `git add .`. Other sessions may have left unrelated edits in a shared
+tree, and unrelated in-flight work has been swept into commits this way. Stage
+only your own files by explicit path.
+
+## Forbidden
+
+`git reset --hard`, `git restore`, `git checkout -- <path>`, and `git push
+--force` are forbidden unless the user explicitly asks for them by name. When a
+worktree is damaged, recover non-destructively — `git checkout-index -a` or
+`git archive` from a known-good ref — rather than resetting.