mercury-agent 0.21.0 → 0.23.0-beta.1

package/README.md

@@ -292,7 +292,7 @@ mercury service uninstall
 mercury service status
 mercury service logs [-f]
 
-# upgrade (stops the service, installs globally, restarts)
+# upgrade (pulls the matching agent image first, then stops the service, installs globally, restarts; --dry-run prints the plan)
 mercury upgrade             # latest
 mercury upgrade 0.14.0      # a specific version
 ```
@@ -420,7 +420,7 @@ Supported OAuth providers: Anthropic, GitHub Copilot, Google Gemini CLI, Antigra
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `MERCURY_AGENT_IMAGE` | `ghcr.io/avishai-tsabari/mercury-agent:latest` | Container image |
+| `MERCURY_AGENT_IMAGE` | `ghcr.io/avishai-tsabari/mercury-agent:<version>` | Container image; pinned to the installed version, see `docs/configuration.md` § Agent image |
 | `MERCURY_CONTAINER_TIMEOUT_MS` | `300000` | Container timeout (5 min) |
 | `MERCURY_CONTAINER_RUNTIME` | `runc` | `runc` (default) or `runsc` ([gVisor](https://gvisor.dev)) |
 | `MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT` | `false` | Set `true` on Linux Docker Engine (see note below) |

package/container/Dockerfile

@@ -60,7 +60,7 @@ RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
 ENV CHROMIUM_FLAGS="--no-sandbox"
 
 # Install CLIs
-RUN bun add -g @earendil-works/pi-coding-agent@~0.84.1
+RUN bun add -g @earendil-works/pi-coding-agent@~0.85.1
 
 WORKDIR /app
 
@@ -111,6 +111,7 @@ COPY src/cli/mrctl.ts /app/src/cli/mrctl.ts
 COPY src/cli/mrctl-http.ts /app/src/cli/mrctl-http.ts
 COPY src/extensions/reserved.ts /app/src/extensions/reserved.ts
 COPY src/extensions/permission-guard.ts /app/src/extensions/permission-guard.ts
+COPY src/extensions/bash-timeout.ts /app/src/extensions/bash-timeout.ts
 COPY src/text/sanitize-text.ts /app/src/text/sanitize-text.ts
 COPY src/types.ts /app/src/types.ts
 COPY resources/ /app/resources/

package/container/Dockerfile.base

@@ -42,7 +42,7 @@ RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
 ENV CHROMIUM_FLAGS="--no-sandbox"
 
 # Install CLIs
-RUN bun add -g @earendil-works/pi-coding-agent@~0.84.1
+RUN bun add -g @earendil-works/pi-coding-agent@~0.85.1
 
 WORKDIR /app
 
@@ -80,6 +80,7 @@ COPY src/cli/mrctl.ts /app/src/cli/mrctl.ts
 COPY src/cli/mrctl-http.ts /app/src/cli/mrctl-http.ts
 COPY src/extensions/reserved.ts /app/src/extensions/reserved.ts
 COPY src/extensions/permission-guard.ts /app/src/extensions/permission-guard.ts
+COPY src/extensions/bash-timeout.ts /app/src/extensions/bash-timeout.ts
 COPY src/text/sanitize-text.ts /app/src/text/sanitize-text.ts
 COPY src/types.ts /app/src/types.ts
 COPY resources/ /app/resources/

package/container/agent-package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "~0.84.1"
+    "@earendil-works/pi-coding-agent": "~0.85.1"
   }
 }

package/container/build.sh

@@ -31,9 +31,12 @@ docker build -f container/Dockerfile \
     -t "${IMAGE_NAME}:${VERSION}" \
     -t "${IMAGE_NAME}:latest" .
 
-# Both tags, on purpose. `:latest` is what src/config.ts still defaults to, so
-# dropping it would break every existing host; `:<version>` is what a host can
-# pin to once it stops trusting a floating tag (release-gate R0.4).
+# Both tags, on purpose. `mercury-agent:latest` is the explicit local override
+# a source-run box sets (`agent.image` / MERCURY_AGENT_IMAGE), so dropping it
+# would break every such host; `mercury-agent:<version>` mirrors the registry
+# tag the default now pins to (release-gate R0.6 — `src/config.ts` defaults to
+# `ghcr.io/…/mercury-agent:<version>`, which `mercury build` tags as well).
+# Neither local name has a registry host, so neither is ever pulled.
 echo "✓ Built ${IMAGE_NAME}:${VERSION} and ${IMAGE_NAME}:latest"
 echo ""
 echo "Version label:"

package/docs/configuration.md

@@ -20,7 +20,9 @@ These must be supplied via environment variables only; they are **not** read fro
 
 - `MERCURY_API_SECRET`
 - `MERCURY_CHAT_API_KEY`
+- `MERCURY_SHADOW_API_SECRET` (a shadow's own; see [Shadow mode](#shadow-mode-mercury_shadow))
 - `MERCURY_DISCORD_GATEWAY_SECRET`
+- `MERCURY_HEARTBEAT_URL` (see [Heartbeat](#heartbeat-mercury_heartbeat_url-mercury_heartbeat_tasks))
 
 Platform tokens, provider API keys, and extension keys (e.g. `MERCURY_TELEGRAM_BOT_TOKEN`, `MERCURY_BRAVE_API_KEY`) are also **env-only** today—they are not part of the YAML schema.
 
@@ -103,6 +105,107 @@ Restarting *before* the make-up run lands drops it, the same way a restart drops
 a pending retry: the boot pass leaves `next_run_at` off the cron grid, and the
 next boot realigns normally.
 
+## Heartbeat (`MERCURY_HEARTBEAT_URL`, `MERCURY_HEARTBEAT_TASKS`)
+
+Nothing on the box can alert while the box is off. Twice in six days the box
+was down overnight (2026-09-05, 2026-09-10) and the 09:00 article with it, and
+the missed-run report above could only speak once the box was back. The
+heartbeat is the reader that lives somewhere else: after a listed task
+**delivers**, the host GETs a URL, and the *service* behind that URL alerts the
+owner's phone when the ping is late. A dead box, a dead WSL distro and a dead
+WhatsApp socket are all heard the same way, because nothing here has to be
+alive to raise the alarm.
+
+Both keys are **env-only** (the URL is a credential — anyone holding it can mark
+the check up — and is listed under Secrets above; `mercury env dump` reports
+both as present or absent and prints neither value, so a swapped pair cannot
+leak the URL through the task list):
+
+```bash
+# .env
+MERCURY_HEARTBEAT_URL=https://hc-ping.com/<ping-key>/mercury-{task}
+MERCURY_HEARTBEAT_TASKS=24,621
+```
+
+- **`{task}`** in the URL is replaced by the task id, so one credential serves
+  one check per task — with healthchecks.io's slug pings the checks above are
+  `mercury-24` and `mercury-621` under one project ping key. A URL without the
+  placeholder is fine for a single listed task; with two or more, every ping
+  lands on one check and a delivered roundup would silence the alarm for a
+  missing article — `mercury preflight` warns on that shape.
+- **When a ping is sent — one rule.** A run of a listed task that recorded
+  `status: ok` with `outcome: posted` (the ledger's own words, see
+  `mercury env dump` / `task_runs`). **Not** on `no_update` — the article that
+  found nothing to say is exactly the case to alert on. Not on an error, not on
+  a delivery failure, not for an unlisted task (extension one-shots, chat turns).
+  A manual **Run now** that delivers counts; a `silent` task that delivers
+  counts (the run ran and produced; whether the group heard it is `silent`'s
+  question).
+- **Bounded and never fatal.** One GET with a 5-second bound, after the ledger
+  row and the schedule advance, so a slow or dead ping host holds neither
+  hostage. Success is `Heartbeat pinged taskId=24 status=200` at info; failure
+  is `Heartbeat ping failed taskId=24 reason=ENOTFOUND` at **warn**, never an
+  error and never a failed run — a missing ping is what the service alerts on.
+  The log line carries the task id and the status; never the URL.
+- **A shadow never pings.** `MERCURY_SHADOW=1` (below) disables the heartbeat
+  whatever the copied `.env` says, so a rehearsal cannot mark the live check up.
+- **`mercury preflight` / `mercury doctor` — `host.heartbeat`.** `skipped` on a
+  box with no active cron task; `warn` (never `blocked`) when there are cron
+  tasks and no URL, a URL and no listed task, a listed id that is not an active
+  cron task, a malformed URL, or the shared-check shape above; `pass` otherwise.
+  The evidence names task ids, never the URL.
+
+**Setting up the service (recommended: healthchecks.io, free tier).** One check
+per listed task, shaped by how often the task *delivers*, not by its cron: only
+a `posted` run pings, a `no_update` slot does not. A task that posts on every
+slot gets a cron-shaped check — the article as `0 9 * * *` Asia/Jerusalem with a
+30-minute grace (alert at 09:30). A task that is allowed to stay silent on a
+slot gets a *simple* check whose period covers its longest expected silence —
+the roundup, where 3 of 9 slots in one week were `no_update`, as period 1 day
+with a 6-hour grace; a cron-shaped check there alerts on every quiet slot.
+Alert channels: email is enough — it reached the owner's phone within the
+grace period the first time the box died (2026-09-12); a push channel
+(Telegram, Signal) is optional. Never the bot's own WhatsApp, which is the
+thing that is down.
+
+**One healthchecks.io project per box, named after the box.** One account
+will end up holding checks for several bots — a client's, a second project's,
+this one's. The alert email leads with the *project* name, then the check
+name, and `mercury-24` says nothing about which box missed. A project named
+after the box (`Mercury — home PC (WSL)`) is the cheapest fix and the safest
+shape: the project is the credential boundary — it owns the ping key, so a
+key that leaks from a client's box cannot mark this bot's checks up — and it
+owns its own alert channels and members, so a colleague added to a work
+project never sees a private bot. Renaming the project touches no slug and
+nothing on the box. Rename the checks inside it only if the task is not
+obvious from the name (`article 09:00`, `roundup`, `WSL anchor`), and then
+mind that the name and the **slug** are separate fields: the URL template
+above pings by slug, so a rename must leave the slug (`mercury-24`) as it is
+— read the Slug field in the same dialog before saving, and put it back if
+the new name re-derived it — or the ping starts returning 404 and every
+listed task reads as down. A changed slug is a box-side change: new
+`MERCURY_HEARTBEAT_URL` template in `.env`, a restart in a gap, and the
+anchor loop's own URL.
+
+**Optional second signal, not built here.** A box that pings every few minutes
+from outside Mercury gives the same service a "the machine is up" check that is
+independent of any task — and it is the one that speaks first: a dead distro
+is heard within its grace period instead of at 09:30. On the WSL box that is a
+loop started by the owner's anchor script, against its own check
+(`mercury-anchor`, a *simple* check — period 10 min, grace 10 min, pinged every
+5 min):
+
+```bash
+# ~/mercury-anchor.sh — alongside the sleep that holds the distro open
+while true; do curl -fsS -m 10 --retry 2 -o /dev/null "https://hc-ping.com/<ping-key>/mercury-anchor" || true; sleep 300; done &
+```
+
+The loop dies with the distro, and the logon task that starts the anchor fires
+at Windows logon only — after a distro restart with no logon (a WSL crash, a
+`wsl --shutdown`) the anchor and the loop are both gone until
+`Start-ScheduledTask 'Start Mercury WSL'` is run again; the check going late a
+second time is how that shows.
+
 ## Operator alerts (`alerts:`)
 
 When a provider OAuth credential can no longer be refreshed, every space stops
@@ -138,6 +241,49 @@ Env equivalents: **`MERCURY_ALERTS_ENABLED`**, **`MERCURY_ALERTS_COOLDOWN_MS`**.
 - **Transient failures** (HTTP 408/429/5xx from the token endpoint) alert only
   after three in a row; a single blip heals itself. A rejected refresh token, or
   a cause that could not be classified, alerts on the first occurrence.
+- **Scheduled-task failures go two ways.** A task a person created reports its
+  final failure into its own space, as before (`scheduling.notify_on_failure`).
+  A task an **extension** opened — feed-watch's verify one-shots; any task named
+  after a loaded extension, or whose `created_by` is not a platform user id
+  (`system`, the console, `space-profile`) — reports to the operators above
+  instead, and its space hears nothing, even when no operator is reachable
+  (then the only record is the ERROR log line). No cooldown: a final failure is
+  already once per due cycle.
+- **Partial deliveries.** A scheduled post that reached some of a space's linked
+  conversations and not others is **not** retried — a retry would post a second
+  copy where the first landed — and the operators are told which conversations
+  missed it.
+
+## History per conversation, and the reporter lint (per-space)
+
+Two behaviours that only matter to a space with **more than one linked
+conversation** or with a **reporter standard** — every other space is
+byte-identical.
+
+**History per conversation.** Chat and ambient rows record the conversation
+they were said in (`messages.conversation`, a thread id such as
+`whatsapp:<group-jid>`). When a space has two or more linked conversations, a
+run answering one of them reads only that conversation's rows plus the space's
+own rows — scheduled posts, and rows written before the column existed — and
+never the other conversation's chatter. A scheduled run in such a space reads
+only the space's own rows. A space with one conversation reads exactly what it
+always read. Nothing to configure.
+
+**`reporter.standard`** (per space, unset by default) — the path, relative to
+the space directory, of a reporter standard JSON file (the shape of
+`examples/profiles/football-reporter/standard.json`; the football profile
+seeds it there and sets the key). When set, every scheduled reply the space
+sends is linted on the host **after** delivery and the findings are written
+to the journal — one `reporter-lint: finding` line per finding with the rule
+id and the task id, and one `reporter-lint: <n> findings` line per run. The
+reply is never altered or held; an unreadable file is one warn line. A reply
+that carries a `[longview:summary]` block is linted as the article, anything
+else as a scan. The path must stay inside the space directory and end in
+`.json`.
+
+```bash
+mrctl config set reporter.standard standard.json
+```
 
 ## Ambient group context
 
@@ -218,6 +364,28 @@ Snapshot directories are built by `mercury shadow snapshot`, which generates
 the shadow's `.env` and `mercury.yaml` — nothing here needs to be set by
 hand. See [live-testing.md](live-testing.md) §2 and §7.
 
+**A shadow answers to no live credential.** Every snapshot gets a fresh
+**`MERCURY_SHADOW_API_SECRET`** (64 hex characters), and the generated `.env`
+also overrides `MERCURY_API_SECRET` and `MERCURY_CHAT_API_KEY` with that same
+value — so the live bot's secret opens nothing on the shadow: not `/api/*`,
+not `/chat`, not the dashboard, and not the route below. The value lives
+only in the snapshot's `.env`; `shadow snapshot`, `shadow up`, `shadow
+status`, `/health` and the logs print key names, never the value. Rotation
+is a new snapshot.
+
+**`POST /api/shadow/simulate`** (goal `rehearsal-bench` M2.2b) exists only on
+a shadow — on a live process the path is whatever `/api`'s guard says (401
+without the live secret, 404 with it). It is authenticated by
+`MERCURY_SHADOW_API_SECRET` **alone**: unset ⇒ 503 (a snapshot taken before
+this key existed — take a fresh one), mismatch ⇒ 401. The body is a
+`SyntheticWhatsAppEvent` by field name (`application/json`, or
+`multipart/form-data` with an `event` part and `file` parts for attachments);
+`isBotMentioned` / `isReplyToBot` are derived from the stanza and a body
+carrying either is a 400. The response is `text/event-stream`: one `entry`
+event per outbox line as it is journaled, then a `result` event with the
+`SimulateResult`. `/health` reports `simulateRoute: true|false` and
+`mercury shadow status` prints it.
+
 ## System prompt authorship (`agent.override_pi_system_prompt`)
 
 Chooses whether Mercury replaces pi's own system prompt or appends to it:
@@ -300,7 +468,49 @@ and under an explicit override, the vars reaching every container:
 Container env passthrough: explicit `all` override — these vars reach every space's container and are scoped to nothing. […] vars=MERCURY_SCRAPER_API_KEY, MERCURY_BILLING_API_KEY
 ```
 
-For secrets that only host-side hooks and jobs need, prefer `mercury.env({ from: "…", hostOnly: true })`, which keeps them out of containers in either mode. For credentials the agent should never hold at all, use a host-side capability handler (`mercury.capability()`), which runs the privileged call on the host and returns only the result.
+For secrets that only host-side hooks and jobs need, prefer `mercury.env({ from: "…", hostOnly: true })`, which keeps them out of containers in either mode. For credentials the agent should never hold at all, use a host-side capability handler (`mercury.capability()`), which runs the privileged call on the host and returns only the result. `hostOnly` is a required field: under `claimed` a claim is the only way a `MERCURY_*` var reaches a container, so a claim has to say whether it means to — `hostOnly: false` is a decision that something inside the container reads the var, and the repo gate (`tests/env-claims-declare-hostonly.test.ts`) holds those to an allowlist naming the reader. The loader warns at startup about any installed extension whose claim does not decide.
+
+## Container shared memory (`agent.container_shm_size`)
+
+How big `/dev/shm` is inside every agent container, in Docker's `--shm-size` spelling:
+
+```yaml
+agent:
+  container_shm_size: 512m   # 512m (default) | 1g | any Docker size
+```
+
+Env: `MERCURY_CONTAINER_SHM_SIZE`. Applies to both runtimes — `/dev/shm` is Docker's, not gVisor's.
+
+Docker's own default is **64 MB**, and that is the wrong size for what these containers actually do. Chromium is the workload: the `web-browser` extension drives it, the `poster` extension renders through it, and an agent asked to screenshot a page runs it directly. A large frame (a 1856x2304 poster, say) exhausts 64 MB, and Chromium's response is not an error — it **hangs**. The turn then sits idle until the host kills the container at `container_timeout_ms`, and the user gets no reply, only the time-limit marker. Three customer-facing runs were lost that way on 2026-09-10 before the cause was found.
+
+The default is deliberately generous rather than minimal. A tmpfs is allocated as it is used, so a container that renders nothing pays nothing for the headroom, and under `container_runtime: runsc` the total is bounded by the container's `--memory` limit anyway. Lower it only on a host that is genuinely short of RAM, and expect large renders to hang again if you go back to 64 MB.
+
+Two related things worth knowing:
+
+- Passing `--disable-dev-shm-usage` to Chromium sidesteps `/dev/shm` entirely and works at any size. The `poster` extension already does this, which is why it kept working while direct Chromium calls hung.
+- `mercury preflight`'s round-trip probe spawns with the same value, so the shape it vouches for is the shape a real turn gets.
+
+## Bash call timeout (`agent.container_bash_timeout_seconds`)
+
+The longest a single `bash` tool call may run inside an agent container, in seconds:
+
+```yaml
+agent:
+  container_bash_timeout_seconds: 300   # 300 (default)
+```
+
+Env: `MERCURY_CONTAINER_BASH_TIMEOUT_SECONDS`. It is both a default and a ceiling: a call that names no `timeout` gets this one, and a call that asks for more is clamped down to it. The agent can only ask for *less*.
+
+pi's `bash` tool takes an optional `timeout` and arms no timer at all when the model omits it — its own parameter description says "optional, no default timeout". A command that hangs rather than failing therefore blocks the turn with nothing watching it, until the host kills the whole container at `container_timeout_ms` and the user gets no reply, only the time-limit marker. That is the other half of the 2026-09-10 incident described under `container_shm_size`: the hanging Chromium was the cause, and the missing bound is what turned each hang into a lost 20-minute run instead of a recoverable error.
+
+When the bound fires, pi kills the command's whole process tree and returns `Command timed out after N seconds` as a normal tool error, so the turn can retry differently, fall back, or explain — while it still has budget left to reply.
+
+Two things to keep in mind when changing it:
+
+- **Keep it comfortably below `container_timeout_ms`.** A bound at or above the container limit buys nothing, because the SIGKILL arrives first. The defaults (300 s against 5 minutes) leave that ratio to whoever tunes both.
+- **Long jobs need a different shape, not a bigger number.** Raising this to cover a slow build makes every hang that much more expensive. Prefer backgrounding the work and polling a file for its result.
+
+The value in force is stated to the model in its system prompt, so it can plan around the ceiling instead of meeting it as a dead tool call.
 
 ## Agent run traces (`agent.trace_runs`)
 
@@ -380,6 +590,7 @@ a detail on the page can be answered.
 | `longview.enabled` | `false` | Publish long replies from this space. |
 | `longview.threshold_chars` | `2000` | Publish when a reply exceeds this many characters. Minimum 500. |
 | `longview.target` | `telegraph` | Where pages are published. |
+| `longview.sources` | `both` | Which replies are published: `both` (any reply over the threshold, whoever asked), `scheduled` (task runs only — a member's long answer stays in chat), or `chat` (the reverse). A turn whose origin the host did not report is never published under `scheduled` or `chat`. |
 | `longview.summary_model` | *(empty)* | Model that writes the chat summary. Empty uses the space's configured model. |
 
 `summary_model` must name a model on the space's **existing provider**. The
@@ -535,3 +746,40 @@ lands back in `default`.
 The **Cursor Agent CLI** integration has been removed. All model legs use **pi** with standard providers (`anthropic`, `openai`, `google`, `mistral`, `groq`, `openrouter`, etc.).
 
 If your chain still has `provider: cursor`, the agent run **fails fast** with an error that points here. Switch to the **native provider** for the model you want (for example `anthropic` for Claude, `openai` for GPT) and set the matching **`MERCURY_*_API_KEY`**.
+
+## Agent image (`agent.image`)
+
+Which container image every agent run spawns:
+
+```yaml
+agent:
+  image: mercury-agent:latest    # a locally built image (container/build.sh or `mercury build`)
+```
+
+Env: `MERCURY_AGENT_IMAGE`.
+
+**The default is the registry image at this host's own version** —
+`ghcr.io/avishai-tsabari/mercury-agent:<version>`, where `<version>` is the
+installed package's `package.json` version (release-gate R0.6, since 0.22.0;
+before that the default floated on `:latest`). Nothing needs to be set for it,
+and a host upgrade changes the reference by itself, so the box asks for the
+new tag on its next boot. The tag is what `release.yml` pushes on every
+release; the package is private, so a box on the default needs a registry
+token that can read it, and a box that has none should set an explicit image
+instead. `mercury preflight`'s `docker.image` check names the pinned tag, the
+host version and both ways out when the tag is absent — that is the check to
+read, not the first failed spawn.
+
+**An explicit value is kept exactly as written.** Nothing normalises it, and
+the pin never rewrites it: a locally built `mercury-agent:latest`, another
+registry, a digest-pinned reference. Two of those shapes are never pulled or
+re-pulled — a name with no registry host (`mercury-agent:latest`,
+`mercury-agent-ext:<hash>`) is a local build, and a digest cannot drift; see
+[container-lifecycle.md](container-lifecycle.md) § Staying Current. An
+explicit *floating* tag with a registry host is re-pulled when the host
+version changes, as before.
+
+`mercury env dump --json` reports the key with its source
+(`config.keys[].key == "agentContainerImage"`, `source` one of `default`,
+`file`, `env`), which is how a deploy tells a box on the pinned default from
+one with an override before restarting it.

package/docs/container-lifecycle.md

@@ -100,6 +100,12 @@ When a container exceeds the timeout:
 4. A marker assistant message ("[System: this run was killed at the container time limit before replying. …]") is recorded in chat history, so the next run's agent knows the previous run was cut off and can check the workspace for partial work
 5. Queue unblocks, next message can proceed
 
+A container that hits the timeout was not necessarily busy. The commonest way to burn the whole budget is a child process that hangs rather than fails, and the commonest such child is Chromium on a too-small `/dev/shm`. Every spawn therefore sizes it explicitly — see `container_shm_size` in [configuration.md](configuration.md#container-shared-memory-agentcontainer_shm_size).
+
+| Config | Env Var | Default | Applies to |
+|--------|---------|---------|------------|
+| `containerShmSize` | `MERCURY_CONTAINER_SHM_SIZE` | `512m` | both runtimes |
+
 The host always injects a resolved **model chain** into the container (after `MERCURY_*` passthrough) so retries and fallbacks use the same policy Mercury loaded at startup:
 
 | In-container env | Source (host) | Purpose |
@@ -176,8 +182,9 @@ Message received
 # Set container timeout to 10 minutes
 export MERCURY_CONTAINER_TIMEOUT_MS=600000
 
-# Use the preset image from GitHub Container Registry
-export MERCURY_AGENT_IMAGE=ghcr.io/avishai-tsabari/mercury-agent:latest   # Full (default)
+# Override the agent image. The default needs no setting: it is the registry
+# image at this host's own version, ghcr.io/avishai-tsabari/mercury-agent:<version>
+export MERCURY_AGENT_IMAGE=mercury-agent:latest   # a local `mercury build` / container/build.sh
 ```
 
 ## Sandboxing (Bubblewrap)
@@ -330,12 +337,24 @@ Mercury publishes an image preset to GitHub Container Registry:
 
 | Preset | Size | Contents |
 |--------|------|----------|
-| `ghcr.io/avishai-tsabari/mercury-agent:latest` | ~2.8GB | Full devcontainer: Bun, Node.js, Python, Go, git, build tools |
+| `ghcr.io/avishai-tsabari/mercury-agent:<version>` | ~2.8GB | Full devcontainer: Bun, Node.js, Python, Go, git, build tools |
 
 Images are published on each release by `release.yml`'s `publish-image` job,
 which builds from the published npm tarball and pushes `:<version>` alongside
 `:latest`. A prerelease publishes its own tag only and leaves `:latest` alone.
 
+**The default is pinned to the host's version** (release-gate R0.6, since
+0.22.0): a host running mercury `X.Y.Z` with no `agent.image` override asks
+for `ghcr.io/avishai-tsabari/mercury-agent:X.Y.Z` — never `:latest`. So a
+host upgrade changes the reference, the new tag is absent locally, and boot
+pulls it (or fails loudly if it cannot); `mercury preflight`'s `docker.image`
+check names the pinned tag, the host version and the two ways out when the
+tag is missing. An explicit override (`agent.image` in `mercury.yaml`,
+`MERCURY_AGENT_IMAGE`) is kept byte-for-byte: a source-run box that builds
+its own image sets `mercury-agent:latest` and is untouched by the pin. The
+package is private (G-007), so a box on the default needs a registry token
+that can read it; the boot line and preflight are where its absence shows.
+
 > Before 0.19.0 this sentence was aspirational: nothing in CI built the image,
 > the registry copy was hand-pushed and stale, and an install outside the
 > tagula fleet had no image to pull. See `docs/goals/release-gate/decisions.md`
@@ -348,8 +367,11 @@ A floating tag used to mean "whatever this box pulled the first time":
 upgraded through npm kept running the old container against new host code with
 `/health` at 200 and nothing in the log.
 
-Startup now re-pulls the image whenever the host's Mercury version is not the
-one that last pulled it, recording the pair in `<dataDir>/image-pull.json`.
+Two things close that. The default is now pinned to the host's version (above),
+so on a default box the question is simply whether `:<version>` is present.
+And for any **floating** reference an operator sets explicitly, startup
+re-pulls the image whenever the host's Mercury version is not the one that
+last pulled it, recording the pair in `<dataDir>/image-pull.json`.
 Two references are never re-pulled: a **digest-pinned** one (`…@sha256:…`),
 which cannot drift, and a **locally built** one, which exists in no registry —
 so a pull would fail on every boot. "Locally built" means any name with no
@@ -365,9 +387,9 @@ image id, repo digest, version label and whether a refresh happened, so drift
 is visible without being asked for:
 
 ```
-Agent image resolved image=ghcr.io/avishai-tsabari/mercury-agent:latest
-  imageId=sha256:… digest=…@sha256:… imageVersion=null hostVersion=0.18.2
-  refresh=refreshed reason=version-changed previousImageId=sha256:…
+Agent image resolved image=ghcr.io/avishai-tsabari/mercury-agent:0.22.0
+  imageId=sha256:… digest=…@sha256:… imageVersion=0.22.0 hostVersion=0.22.0
+  refresh=pulled reason=not-present
 ```
 
 `imageVersion` is the image's `com.mercury.version` label (release-gate R0.1

package/docs/deployment.md

@@ -102,12 +102,32 @@ Not currently supported via `mercury service`. Options:
 ## Upgrading
 
 ```bash
-mercury upgrade            # to the latest published version
-mercury upgrade 0.14.0     # to a specific version
+mercury upgrade                    # to the latest published version
+mercury upgrade 0.14.0             # to a specific version
+mercury upgrade --dry-run          # print the plan, do nothing
+mercury upgrade --skip-image-pull  # host only — for a box on a locally built image
 ```
 
-On macOS and Linux this stops the managed service, installs the new version
-globally, and restarts the service.
+**Image first, host second** (release-gate R0.5). The command resolves what
+you asked for to one exact version (`latest`, a dist-tag or a range go
+through `npm view`), then **pulls the agent image that version's host will
+ask for** — the default is pinned to the version, so that is
+`ghcr.io/avishai-tsabari/mercury-agent:<version>` — and refuses when the
+registry has no such tag or refuses the credential, **leaving the host
+untouched**. Only then, on macOS and Linux, does it stop the managed service,
+install the new version globally and restart the service. It installs the
+exact version it pulled the image for, not the spec, so the two cannot drift
+apart between the pull and the install. Every step prints a line; the last
+one names `mercury preflight` as what to run next from the project
+directory (the derived image rebuilds on the first run, as before).
+
+An explicit `agent.image` is respected: a registry reference is pulled as
+configured (if it pins another version, preflight's `image.contract` says so
+after the restart); a **local build** (`mercury-agent:latest`) cannot be
+fetched, so the upgrade refuses unless you pass `--skip-image-pull` — then
+run `mercury build` before the first run on the new version. The rules are
+`docs/release-gate.md` Gate 4; `upgrade` does not run preflight itself
+because it runs outside any project directory.
 
 ### Windows: stop Mercury before upgrading
 
@@ -135,6 +155,27 @@ first:
 Mercury's own CLI does not load the WhatsApp stack at startup, so running
 `mercury upgrade` never locks the tree it is replacing.
 
+### Disk: prune the build cache after every upgrade
+
+Each upgrade pulls a new base image (~2 GB of layers) and Mercury rebuilds the
+derived `mercury-agent-ext` image on the next start. Removing the old base with
+`docker rmi` / `docker image prune` does **not** free its layers: the derived
+build leaves BuildKit cache records that keep the old base layers alive, so
+overlay2 grows by roughly 2 GB per release and `docker system df` under-reports
+it. A 38 GB box hit 93% after five releases (2026-09-08).
+
+Once `/health` reports the new version and the journal shows `Built derived
+agent image`, run:
+
+```bash
+docker builder prune -af
+```
+
+Safe with the bot running: it touches no image, container or data. The only
+cost is that the next derived-image build starts cold, which it does after a
+base change anyway. Never `docker image prune -a` on an idle box — with no
+container running it removes the derived image and the base too.
+
 ## Auto-Restart Behavior
 
 Both systemd and launchd are configured to automatically restart Mercury if it crashes:

package/docs/extensions.md

@@ -95,17 +95,23 @@ Can only be called once per extension.
 
 ### `mercury.env(def)`
 
-Declare an environment variable this extension needs. Only injected into containers when the caller has permission for this extension. Claimed vars are excluded from the blind `MERCURY_*` passthrough, preventing credential leakage to unprivileged callers.
+Declare an environment variable this extension needs, and decide whether it enters the container. Claimed vars are excluded from the blind `MERCURY_*` passthrough; a claim with `hostOnly: false` is injected into containers only when the caller has permission for this extension.
 
 ```typescript
-mercury.env({ from: "MERCURY_GH_TOKEN" });                    // injected as GH_TOKEN
-mercury.env({ from: "MERCURY_GH_TOKEN", as: "GITHUB_TOKEN" }); // custom container name
-mercury.env({ from: "MERCURY_STT_API_KEY", hostOnly: true }); // host-side only
+mercury.env({ from: "MERCURY_STT_API_KEY", hostOnly: true });                    // host-side only — never enters a container
+mercury.env({ from: "MERCURY_GH_TOKEN", hostOnly: false });                      // injected as GH_TOKEN
+mercury.env({ from: "MERCURY_GH_TOKEN", as: "GITHUB_TOKEN", hostOnly: false });  // custom container name
 ```
 
 - `from` — env var name as set in `.env` (e.g. `MERCURY_GH_TOKEN`)
 - `as` — (optional) name inside the container. Defaults to `from` with `MERCURY_` prefix stripped
-- `hostOnly` — (optional) claim the var (kept out of the blind `MERCURY_*` passthrough) but **never inject it into any container**. Use for secrets consumed only by host-side hooks/jobs (e.g. an STT API key used in `before_container`).
+- `hostOnly` — **required**, no default. `true`: claim the var (kept out of the blind `MERCURY_*` passthrough) but **never inject it into any container** — secrets consumed only by host-side hooks/jobs (an STT API key used in `before_container`, an OAuth refresh token the host exchanges, a credential a `mercury.capability()` handler uses). `false`: something inside the container reads it — name that reader, because a reviewer will ask.
+
+**Why it is required.** The claim loop in `src/core/runtime.ts` skips a claim only when `hostOnly` is `true`; a claim that did not decide was injected. Under the default `claimed` passthrough (`docs/configuration.md`, *Container env passthrough*) a claim is the *only* way a `MERCURY_*` var reaches a container, so a bare claim was strictly wider than not claiming at all — the one call an author made in order to be careful about a secret was the call that exposed it. It shipped three times (`docs/debug/moderate/2026-09-01-tradestation-credentials-enter-the-container.md`, `docs/debug/moderate/2026-09-12-gws-env-claim-bypasses-the-credential-shape-guard.md`) before the field became required.
+
+**The gate.** `tests/env-claims-declare-hostonly.test.ts` walks every `mercury.env()` call in `examples/**/index.ts` and `src/**`, loads every example extension through the real API, and asserts that the set of container-visible claims **equals** `ENV_CLAIM_ALLOWLIST` — a row per `hostOnly: false` claim naming the file inside the container that reads it. A new container-visible claim without a row, a bare claim, or a row whose reader no longer mentions the key is a red `bun run check`. The three rows today: `poster`'s two provider keys (the poster CLI runs inside the container) and `gws`'s legacy credentials-file path (a path, not a secret). Everything else is `hostOnly: true`.
+
+**On a live box.** The type cannot reach an extension written outside this repo, so `ExtensionLoader` logs `Extension "<name>": env claim "<VAR>" does not state hostOnly; it is container-visible …` for each bare claim it loads. The extension still loads and behaves as before; the line is the reader.
 
 Can be called multiple times for multiple env vars.
 
@@ -279,6 +285,39 @@ mercury.widget({
 
 Widgets render HTML fragments in the dashboard overview. Errors show a placeholder — never crash the dashboard.
 
+### `mercury.capability(name, handler)`
+
+Register a host-side handler the agent reaches from inside the container with
+`mrctl capability <name> <action> '<json>'` → `POST /api/capability/:name/:action`.
+Credentials the handler uses stay on the host and never enter the container.
+
+```typescript
+// in extensions/rooms/index.ts
+mercury.permission({ defaultRoles: ["admin"] });
+mercury.capability("rooms", async (req, ctx) => {
+  if (req.action === "book") return { data: await bookRoom(req.callerId, req.body) };
+  return { status: 400, data: { error: "unknown action" } };
+});
+```
+
+- **`name` must equal the extension's own name** — registering under any other
+  name throws at load. The broker authorizes a call with `checkPerm(<name>)`,
+  so the equality is what makes that the *extension's* permission: the same
+  predicate the env-var injection rule and the sensitive-connection guard use.
+  A capability named after some other extension's permission would be reachable
+  by callers those two legs believe cannot reach it.
+- **The extension must also call `mercury.permission()`.** Without a *registered*
+  permission of that name, `checkPerm` refuses every role — including `admin`,
+  whose grant is the enumerated set of built-in plus registered permissions, not
+  a wildcard — so the capability is unreachable, silently.
+- An extension named after a **built-in** permission (`prompt`, `stop`, `clear`,
+  …) cannot register a capability at all: it could not own that permission
+  (`mercury.permission()` refuses a built-in name) while the broker would still
+  authorize the handler with it, and `prompt` is one every member holds.
+- One capability per extension; branch on `req.action` for sub-verbs.
+- The name is resolved host-wide, so two extensions cannot own it — a
+  collision is rejected at load time.
+
 ### `mercury.store`
 
 Scoped key-value store for persistent state.