mercury-agent 0.22.0 → 0.23.0-beta.2

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
 

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
 
@@ -95,6 +95,20 @@ RUN while IFS= read -r ext || [ -n "$ext" ]; do \
 RUN echo '#!/bin/sh\nbun run /app/src/cli/mrctl.ts "$@"' > /usr/local/bin/mrctl && \
     chmod +x /usr/local/bin/mrctl
 
+# Same stamp as `container/Dockerfile`, generated from THIS file so the
+# manifest cannot drift from the tier that was actually built. The host's
+# drift check hashes its own `container/Dockerfile`; an image cut from this
+# tier will report that as a difference, which is true and is the point.
+ARG MERCURY_VERSION=unknown
+COPY container/Dockerfile.base /app/container/Dockerfile.base
+COPY src/agent/image-manifest.ts /app/src/agent/image-manifest.ts
+RUN bun run /app/src/agent/image-manifest.ts \
+      /app/container/Dockerfile.base "$MERCURY_VERSION" > /app/image-manifest.json && \
+    grep -q 'src/agent/container-entry.ts' /app/image-manifest.json
+LABEL org.opencontainers.image.version="${MERCURY_VERSION}" \
+      org.opencontainers.image.title="mercury-agent" \
+      com.mercury.version="${MERCURY_VERSION}"
+
 # Fix ownership of all mercury home dir artifacts before switching user
 # `mkdir` here rather than leaving it to Docker: the host mounts the global dir
 # into PI_CODING_AGENT_DIR entry by entry, so Docker would create this dir as

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,7 @@ 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`)
 
@@ -422,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
@@ -577,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

@@ -182,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)
@@ -336,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`
@@ -354,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
@@ -371,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
 

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.