mercury-agent 0.19.0 → 0.20.0

package/container/Dockerfile

@@ -125,6 +125,31 @@ 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
 
+# --- Self-description -------------------------------------------------------
+# Last, deliberately: MERCURY_VERSION changes on every release and an ARG
+# invalidates every layer after it, so anything above this line stays cached
+# across versions.
+#
+# The manifest is generated from THIS Dockerfile, inside the build, rather than
+# from a copy in the repo — a manifest written beside the Dockerfile can drift
+# from it, and a drift check whose own input has drifted is worse than none.
+# `container/Dockerfile` is copied in for that reason and kept, so a running
+# container can be asked what it was built from.
+ARG MERCURY_VERSION=unknown
+COPY container/Dockerfile /app/container/Dockerfile
+COPY src/agent/image-manifest.ts /app/src/agent/image-manifest.ts
+RUN bun run /app/src/agent/image-manifest.ts \
+      /app/container/Dockerfile "$MERCURY_VERSION" > /app/image-manifest.json && \
+    grep -q 'src/agent/container-entry.ts' /app/image-manifest.json
+
+# Read by the host's version check through the derived mercury-agent-ext-*
+# image, which inherits labels from this base with no builder change.
+LABEL org.opencontainers.image.version="${MERCURY_VERSION}" \
+      org.opencontainers.image.title="mercury-agent" \
+      org.opencontainers.image.source="https://github.com/Avishai-Tsabari/mercury" \
+      com.mercury.version="${MERCURY_VERSION}" \
+      com.mercury.image-manifest="/app/image-manifest.json"
+
 USER mercury
 
 ENTRYPOINT ["bun", "run", "/app/src/agent/container-entry.ts"]

package/container/build.sh

@@ -16,8 +16,28 @@ if [ $# -gt 0 ] && [ "$1" != "latest" ]; then
     exit 1
 fi
 
-echo "Building ${IMAGE_NAME}:latest (full devcontainer)..."
-docker build -f container/Dockerfile -t "${IMAGE_NAME}:latest" .
-echo "✓ Built ${IMAGE_NAME}:latest"
+# Taken from package.json, never typed here: a hand-written version is a second
+# source of truth, and the whole point of stamping the image is that the host
+# and the image cannot disagree about which release this is.
+VERSION="$(bun -e 'console.log(require("./package.json").version)')"
+if [ -z "$VERSION" ]; then
+    echo "Could not read the version from package.json — refusing to build an unlabelled image." >&2
+    exit 1
+fi
+
+echo "Building ${IMAGE_NAME}:${VERSION} (full devcontainer)..."
+docker build -f container/Dockerfile \
+    --build-arg "MERCURY_VERSION=${VERSION}" \
+    -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).
+echo "✓ Built ${IMAGE_NAME}:${VERSION} and ${IMAGE_NAME}:latest"
+echo ""
+echo "Version label:"
+docker image inspect "${IMAGE_NAME}:${VERSION}" \
+    -f '  com.mercury.version = {{index .Config.Labels "com.mercury.version"}}'
 echo ""
 echo "Build complete!"

package/docs/behavior-layers.md

@@ -16,9 +16,13 @@ the repo, after a pi upgrade.
 ## 1. The system prompt, top to bottom
 
 ```
-1. pi preamble ............................ image       container-entry.ts buildSystemPrompt
+1. Mercury standalone preamble ............ image       container-entry.ts buildSystemPrompt
      "You are an expert AI assistant…", tool list, "Be concise"
-     (override mode; OVERRIDE_PI_SYSTEM_PROMPT)
+     Replaces pi's own built-in prompt — this text is Mercury's, not pi's.
+     (override mode; MERCURY_OVERRIDE_PI_SYSTEM_PROMPT, default since 2026-09-03.
+      Set it to false and pi's "…operating inside pi, a coding agent harness"
+      prompt takes this slot instead — which an Anthropic OAuth credential
+      cannot use; see docs/configuration.md.)
 2. Mercury platform block .................. image       container-entry.ts buildMercuryAdditions
      inbox/outbox · "You are <bot_username>; read /docs/mercury"
      ## Permissions & Security            ("Permission denied → simply inform the user")
@@ -32,7 +36,9 @@ the repo, after a pi upgrade.
      ## Delivery                          ("[reply] … [/reply] — only the span inside is sent";
                                            pi-jsonl-parser.ts extractReplyEnvelope honours it,
                                            a reply with no markers is sent whole)
-     ## Character                         (mrctl character flow + "standing instruction → set a preference"
+     ## Character                         (heading + "Always follow it" + "only the owner can change it"
+                                           — unconditional, it is the reader instruction for 3c;
+                                           the mrctl character/prefs procedure under it
                                            — only for a caller holding prefs.set)
      reply-anchor sentence                (swipe-replies only)
 3. MERCURY_EXT_SYSTEM_PROMPT ............... host        runtime.ts ~1700-1760
@@ -66,17 +72,22 @@ Two consequences worth reading twice:
   than rely on being more specific."* The only reliable override is an
   explicit sentence naming what it overrides, plus deleting the competing
   rule wherever you control it.
-- **Layer 2 is mostly unconditional, and two voices are removable.** Every
+- **Layer 2 is mostly unconditional, and one voice is removable.** Every
   space receives the security text, the destructive-ops rule and the "simple
-  lists, never raw output" paragraph. Two paragraphs are *capability* text
-  and are emitted only when the caller can act on them: "## Moderation" for a
-  caller holding `mutes.mute`, "## Character" (the preference / character
-  flow) for a caller holding `prefs.set` — a member without `prefs.set` is no
-  longer told that "a standing instruction → set a preference". And a space
-  that owns its standard can set `persona.exclusive=true` (`space_config`,
-  profile-owned): the host then leaves the owner's Bot Character (3c) out of
-  its prompt and does not mount the global `AGENTS.md` (4), so the space file
-  is the only persona left. Everything that still reaches such a space (the
+  lists, never raw output" paragraph. One whole paragraph is *capability* text
+  and is emitted only when the caller can act on it: "## Moderation", for a
+  caller holding `mutes.mute`. "## Character" is **split** since `7d242e2`:
+  the heading, "Always follow it", the fact that only the owner can change the
+  character and the one-line decline for a personality/tone/greeting request
+  ship to *every* caller (`container-entry.ts:426-432`, ungated — they state a
+  fact and a refusal and carry no procedure), while only the `mrctl character
+  get/set` + `mrctl prefs *` procedure under them is gated on `prefs.set`. So a
+  member is told the rule and gets a one-line decline; what they no longer see
+  is the procedure, not the section. And a space that owns its standard can set
+  `persona.exclusive=true` (`space_config`, profile-owned): the host then
+  leaves the owner's Bot Character (3c) out of its prompt and does not mount
+  the global `AGENTS.md` (4), so the space file is the only persona left.
+  Everything that still reaches such a space (the
   platform text, skills, a per-space `system_prompt`) is unchanged. A persona
   that contradicts what remains (a reporter who must not offer lists) still
   has to say so in its `AGENTS.md`, in words.
@@ -158,7 +169,7 @@ it is still inside the window.
 | Surface | File | Injected | Condition |
 |---|---|---|---|
 | Episodic memory | `MEMORY.md` in the space dir | every run, verbatim, as `<episodic_memory>` | file exists and is non-empty. No size cap is enforced — the prompt asks for ~1500 tokens |
-| Active episodes | `knowledge/episodes/*.md` | per run, as `<active_episodes>`, ≤800 tokens | frontmatter `status: active|cooling`, `keywords: ["…"]` (JSON array); score = keyword overlap × (active 1.0 / cooling 0.5) × log(mentions+1); body = `summary:` + `## Current State` |
+| Active episodes | `knowledge/episodes/*.md` | per run, as `<active_episodes>`, ≤800 tokens | frontmatter `status: active|cooling`, `keywords: ["…"]` (JSON array); score = keyword overlap × (active 1.0 / cooling 0.5) × log(mentions+1); a message word matches a keyword exactly, or after dropping up to three leading Hebrew prefix letters (ו ה ב ל מ ש כ) when at least four characters remain; body = `summary:` + `## Current State` |
 | Member notes | `knowledge/members/<id>.md` | per run, as `<member_notes>` | `<id>` = platform id with `/`→`_`; ≤6000 chars total |
 | Members | `space_roles` table | per run, as `<members>` | always; authoritative identity |
 | Preferences | `space_preferences` | per run, as `<preferences>` | always |

package/docs/configuration.md

@@ -35,15 +35,80 @@ context:
   mode: context              # clear | context (default: context)
   window_size: 10            # 1-50 (default: 10). Sliding-window turns when mode=context.
   reply_chain_depth: 10      # 1-50 (default: 10). Reply chain depth when mode=clear.
+  history_max_chars: 2000    # 0-100000 (default: 2000, 0 = off). Per-message cap on the window.
 ```
 
-Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
+Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row. This holds for `history_max_chars` too — it is a builtin space key with a dashboard row, which is what makes it usable: the pathology is space-specific, since one space publishes articles and another only chats.
+
+### Why `history_max_chars` exists
+
+`window_size` counts *turns*, and a turn has no size limit. A space that
+publishes rather than chats therefore pays for its last ten whole articles on
+every round of every run — `<history>` measured 65-81% of the football space's
+prompt. Older messages in the window are clipped to `history_max_chars` and
+carry an in-band `[truncated: N of M characters omitted...]` notice so the model
+can tell a clipped message from one that ended where it looks like it ended.
+
+Never clipped: the newest turn, the swipe-reply anchor, reply chains in
+`clear` mode, ambient rows (they have their own budget), and the stored message
+itself — only the copy sent to the container is shortened. Set `0` to disable.
+Each time the cap bites, the host logs `History window: older messages clipped`
+with the space, `clippedRows` and `savedChars`.
+
+Per space: `mrctl config set context.history_max_chars 4000`, or the
+`context.history_max_chars` row on the dashboard's Context panel.
+
+## Missed scheduled runs (`scheduling.catch_up_window_ms`, per-task `catch_up`)
+
+Mercury does not fire a cron task on boot for the occurrences it slept through.
+That default is deliberate — a restart during a *failing* task must not replay
+it — but until it was reported, an outage longer than a task's interval lost the
+run with no log naming it and nobody told.
+
+Now every boot names what it skipped:
+
+```
+WARN  Missed 2 scheduled run(s) while the scheduler was down
+      taskId=24 name="daily article" oldest=2026-09-05T06:00:00Z
+      newest=2026-09-06T06:00:00Z policy=skip
+```
+
+and reports it in chat — to the task's creator, or to the task's own space when
+the creator has no conversation Mercury can reach. The report is gated by
+`alerts.enabled` (below) and honours no cooldown: the same boot pass advances
+`next_run_at` past the misses, so the same occurrences can never be reported
+twice.
+
+A task can opt into **one** make-up run:
+
+```bash
+mrctl tasks catch-up 24 once     # or: skip, the default
+mrctl tasks create --cron "0 9 * * *" --prompt "..." --catch-up once
+```
+
+`once` marks the task due immediately at boot — once, however many occurrences
+were missed — provided the newest of them is recent enough:
+
+```yaml
+scheduling:
+  catch_up_window_ms: 43200000   # 0 – 604800000 (default: 12h)
+```
+
+Env equivalent: **`MERCURY_TASK_CATCH_UP_WINDOW_MS`**. Past the window the task
+is treated as `skip`: a daily digest two days late is no longer the digest
+anyone asked for. `catch_up` applies to cron tasks only — an `at` task has one
+occurrence and is deleted after it, so there is nothing to make up.
+
+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.
 
 ## Operator alerts (`alerts:`)
 
 When a provider OAuth credential can no longer be refreshed, every space stops
 answering until someone re-authenticates on the host. Mercury DMs the configured
-operators so the outage does not wait for a human to read the logs.
+operators so the outage does not wait for a human to read the logs. The same
+switch gates the missed-run reports described above.
 
 ```yaml
 alerts:
@@ -79,6 +144,7 @@ Env equivalents: **`MERCURY_ALERTS_ENABLED`**, **`MERCURY_ALERTS_COOLDOWN_MS`**.
 In linked group chats, messages that don't trigger the bot are stored as **ambient context** (author-attributed) so it can answer questions about conversation it overheard. Every message in a linked group becomes a row, bounded on both ends:
 
 - **`MERCURY_AMBIENT_TTL_DAYS`** (default `14`) — days before ambient rows are aged out by the storage cleanup. Real user/assistant turns are never touched.
+- **`MERCURY_CONTEXT_HISTORY_MAX_CHARS`** (default `2000`, `0` disables) — per-message character cap on the `context`-mode history window, for spaces with no `context.history_max_chars` row of their own. Clips older messages only; the newest turn, the reply anchor and the stored row are left whole. See the `context:` block above.
 - **`MERCURY_AMBIENT_CONTEXT_ROWS`** (default `30`) — max ambient rows injected into a single prompt. Ambient has its own budget, so overheard chatter can't crowd real turns out of the context window.
 
 Per-space: `mrctl config set ambient.enabled false` disables capture entirely (tag-only mode).
@@ -137,26 +203,86 @@ 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.
 
+## System prompt authorship (`agent.override_pi_system_prompt`)
+
+Chooses whether Mercury replaces pi's own system prompt or appends to it:
+
+```yaml
+agent:
+  override_pi_system_prompt: true   # true (default) | false
+```
+
+Env: `MERCURY_OVERRIDE_PI_SYSTEM_PROMPT`. Unlike every other boolean key, this one is parsed
+strictly: only `false` or `0` (case-insensitive) opt out, an **empty** value is read as unset and
+takes the default, and anything else — `no`, `off`, a typo — is a startup config error. Opting into
+the mode that a Claude subscription cannot use has to be deliberate, so a bare `=` with nothing
+after it must not do it by accident. Note that a blank env var still *shadows* `mercury.yaml` (the
+env merge honours any present `MERCURY_*` key), so a `mercury.yaml` opt-out plus a blank env line
+resolves to the default, not to the file's `false`.
+
+- **`true`** — Mercury is the sole author. pi is invoked with `--system-prompt`, and
+  `buildSystemPrompt` supplies the whole thing: its own identity wrapper, the tool list, the
+  guidelines, and every Mercury platform block.
+- **`false`** — pi's built-in coding-agent preamble comes first and Mercury's content is appended
+  (`--append-system-prompt`).
+
+> ⚠️ **`false` does not work on a Claude subscription.** Anthropic's OAuth gate fingerprints pi's
+> preamble as a third-party app and answers **every** request with
+> `400 Third-party apps now draw from your extra usage, not your plan limits`. The message names
+> billing, but it is a *classification* result — no plan balance and no top-up changes it. If you
+> authenticated with `mercury auth login` (rather than setting `MERCURY_ANTHROPIC_API_KEY`), leave
+> this key at its default. Mercury logs a warning once per process when it spawns a container in
+> append mode while holding an Anthropic OAuth credential.
+>
+> API-key deployments are not gated and may use either mode.
+
+**Override mode gives up nothing you want.** Diffed against pi 0.84.2's `core/system-prompt.js`
+*inside the agent image* — the file ships in the image, not in this repo — append mode uniquely
+contributes exactly two things:
+
+- the phrase `operating inside pi, a coding agent harness`, which is the fingerprint itself; and
+- a block of pointers to pi's own README, docs and examples, for answering questions about pi's
+  extensions, themes, skills and TUI.
+
+The tool snippets and the three guidelines (`Use bash for file operations…`, `Be concise…`,
+`Show file paths clearly…`) are already reproduced verbatim by Mercury's override, which also
+substitutes its own identity line for the `You are Claude Code` preamble. Re-diff after a pi
+upgrade: this is a claim about the image, so it can go stale.
+
+> ⚠️ **Changing this setting needs no image rebuild, but the flag is read inside the container.**
+> The host forwards it as `OVERRIDE_PI_SYSTEM_PROMPT`; `container-entry.ts` reads it per run. A
+> restart is enough to pick up a new value.
+
 ## Container env passthrough (`agent.env_passthrough`)
 
 Controls which host `MERCURY_*` variables reach agent containers:
 
 ```yaml
 agent:
-  env_passthrough: all       # all (default) | claimed
+  env_passthrough: claimed   # claimed (default) | all
 ```
 
+- **`claimed`** (default) — only variables an extension declared via `mercury.env()` are passed, and only when the triggering caller holds that extension's permission. Undeclared variables stay on the host.
 - **`all`** — every `MERCURY_*` var except a fixed blocklist is passed into the container with the prefix stripped (`MERCURY_BILLING_API_KEY` → `BILLING_API_KEY`). Convenient, but blunt: a secret added to `.env` for one purpose reaches **every space's container**, regardless of who triggered the turn or whether that space has anything to do with it. Vars an extension declares `hostOnly` are excluded even here — `MERCURY_BRAVE_API_KEY` stays on the host once `web-search` is installed, which brokers Brave queries through `mrctl capability web-search`.
-- **`claimed`** — only variables an extension declared via `mercury.env()` are passed, and only when the triggering caller holds that extension's permission. Undeclared variables stay on the host.
 
 **Model-provider credentials are exempt** and pass in both modes (`MERCURY_ANTHROPIC_API_KEY`, `MERCURY_ANTHROPIC_OAUTH_TOKEN`, `MERCURY_GEMINI_API_KEY`, `MERCURY_GROQ_API_KEY`, and the rest of the provider list). pi reads them inside the container, and no extension declares them — without the exemption, `claimed` would leave the agent unable to reach any model. They remain subject to the blocklist.
 
+**So is the sandbox escape hatch** `MERCURY_DISABLE_BUBBLEWRAP` — not a secret, and read inside the container under its stripped name, so `claimed` would otherwise withdraw it silently and the container would spawn bwrap again on a host where it cannot start.
+
 Env: `MERCURY_CONTAINER_ENV_PASSTHROUGH`.
 
-`claimed` is opt-in because it breaks setups that rely on blind passthrough for anything other than provider keys — API keys consumed by skills (search, TTS, scrapers) and any credential you added by hand. To migrate, declare those in an extension (see [extensions.md](extensions.md)) before switching. At startup with `all`, Mercury logs the vars it is passing that are neither declared nor provider credentials — names only, so a genuine outlier stands out:
+`all` exists because `claimed` breaks setups that rely on blind passthrough for anything other than provider keys — API keys consumed by skills (search, TTS, scrapers) and any credential you added by hand. **This default changed:** it was `all` in every release up to and including v0.18.2 (changed 2026-09-06). A deployment that fed the agent an unclaimed `MERCURY_*` var now stops delivering it, and the container side of that is silent — the variable is simply unset. Declare those vars in an extension (see [extensions.md](extensions.md)), or keep the old behaviour with `agent.env_passthrough: all` / `MERCURY_CONTAINER_ENV_PASSTHROUGH=all`.
+
+To make the change readable rather than silent, startup logs the unscoped vars in **both** modes — names only, so a genuine outlier stands out. Under the default they are the vars being withheld:
+
+```
+Container env passthrough: claimed — only extension-declared vars and model-provider credentials reach containers. […] withheld=MERCURY_SCRAPER_API_KEY, MERCURY_BILLING_API_KEY
+```
+
+and under an explicit override, the vars reaching every container:
 
 ```
-Container env passthrough: all — these vars reach every space's container and are scoped to nothing. […] vars=MERCURY_SCRAPER_API_KEY, MERCURY_BILLING_API_KEY
+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.
@@ -335,11 +461,13 @@ Which credential path applies depends on which shape you used:
   map, so no `*_API_KEY` variable is read for it. Its key must come from the
   provider entry — written as a **reference**, never a literal:
   `"apiKey": "$MYGATEWAY_API_KEY"` (`${VAR}` and `!some-command` also work).
-  Pass the secret itself as `MERCURY_MYGATEWAY_API_KEY` and it reaches the
-  container through the usual passthrough. This assumes the default
-  `agent.env_passthrough: all`; under `claimed`, only the provider variables
-  Mercury knows about are forwarded, and a custom provider's key is not among
-  them, so pi fails to resolve it.
+  Pass the secret itself as `MERCURY_MYGATEWAY_API_KEY` — but under the default
+  `agent.env_passthrough: claimed`, only the provider variables Mercury knows
+  about are forwarded, and a custom provider's key is not among them, so pi
+  fails to resolve it. Either declare it in an extension or set
+  `agent.env_passthrough: all`. `mercury preflight` catches this case: the
+  `credential` check resolves the reference through the same passthrough the
+  spawn uses, and reports `blocked` naming the mode.
 
 > ⚠️ **Never store a credential literally.** Mercury refuses to mount a
 > `models.json` that has a literal value in `apiKey`, in a credential-shaped

package/docs/container-lifecycle.md

@@ -197,6 +197,8 @@ The pi agent runs inside `bwrap`, which creates a minimal mount namespace with o
 
 **On a stock Linux host the default shape cannot run bwrap.** Docker's default seccomp profile blocks the user-namespace clone and Ubuntu's `docker-default` AppArmor profile independently blocks bwrap's mount step, so every turn fails with `bwrap: No permissions to create new namespace` (or `Creating new namespace failed: Operation not permitted`). On a stock modern host the kernel sysctls that message points at (`unprivileged_userns_clone`, `max_user_namespaces`) are not the blocker — both gates are Docker's; check them only if they are off their defaults. Mercury probes for this once at boot (`docker run --entrypoint bwrap …` with the real bwrap shape) and, if blocked, logs one `error` line naming the fix and refuses every spawn with the same diagnosis instead of a per-turn bwrap error. Escapes, narrowest first: `MERCURY_CONTAINER_RUNTIME=runsc` (gVisor — strongest sandbox, no relaxation needed), then `MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=1` (`--privileged`), then `MERCURY_DISABLE_BUBBLEWRAP=1` (no inner sandbox at all).
 
+`mercury preflight` runs the same probe on demand and reports it as `sandbox.bwrap` — one implementation, called by boot and by the CLI, so the two can never drift apart.
+
 Custom images must install `bubblewrap` for sandboxing to work.
 
 **runsc (gVisor) mode requires `--host-uds=open` on the runtime registration.** In runsc mode the agent container reaches the host API over a bind-mounted unix socket — the socket is mrctl's *only* transport there (`API_URL` is a deliberate dummy). gVisor refuses `connect()` to host unix sockets unless the daemon registers runsc with the flag:
@@ -214,6 +216,114 @@ Custom images must install `bubblewrap` for sandboxing to work.
 
 Without it, Mercury starts clean and containers run, but **every mrctl verb fails** (config, tasks, mutes, stop, capabilities — the whole host API surface) with a bare connect error inside the conversation. Mercury probes for this once at boot (a runsc container connect-tests the socket with the real spawn's mount shape) and, if blocked, logs one `error` line naming this fix. Applying it is zero-downtime: `runtimes` is a SIGHUP-reloadable daemon.json key, so edit the file and `kill -SIGHUP $(pidof dockerd)` — no daemon restart, no container kills.
 
+`mercury preflight` runs the same probe on demand as `sandbox.runsc-host-uds`, and `container.mrctl-roundtrip` proves the whole path end to end by running `mrctl whoami` inside a container on the production launch shape.
+
+## `mercury preflight`
+
+One command that answers *"can this box, with this image and this config,
+actually run a Mercury turn?"* — and says **why not**, one diagnosis per
+blocker, with the narrowest fix. Run it from the project directory the service
+runs in, the way every other `mercury` command is run.
+
+```bash
+mercury preflight                    # human report
+mercury preflight --json             # the report, for a caller to gate on
+mercury preflight --space football   # judge that space's pinned model leg
+mercury preflight --report /tmp/pf.json
+```
+
+| Exit | Meaning |
+|------|---------|
+| `0` | no blocker (warnings allowed) |
+| `1` | at least one check is `blocked` — a turn cannot run here |
+| `2` | usage or config error (bad `--space`, unwritable report, the shadow refusal) |
+
+Callers gate on the exit code and nothing else. A `warn` box answers messages
+while something is wrong; rolling an upgrade back over one would be wrong.
+
+| Check | Verdict class | What it proves |
+|-------|---------------|----------------|
+| `docker.daemon` | blocked | `docker info` answers; "not installed" and "daemon down" are distinguished |
+| `docker.image` | blocked | the configured image is present locally, and which derived tag a spawn would use |
+| `sandbox.bwrap` | blocked | `probeBwrapSandbox` — the boot probe, on demand |
+| `sandbox.runsc-host-uds` | blocked | `probeRunscHostUds` — the boot probe, on demand |
+| `image.contract` | blocked | every `container/Dockerfile` `COPY` target is in the image, and the version the build stamped into `/app/image-manifest.json` equals the host's |
+| `container.mrctl-roundtrip` | blocked | a container on the production launch shape runs `mrctl whoami` and comes back as the caller preflight asserted — by minted token where a caller-token key is configured, by identity header where none is (evidence `callerAuth`; see below). On runsc the host API socket is connect-tested first, so a stopped service blocks with the service remedy and no container is created |
+| `credential.first-leg` | blocked | the chain's first leg (or `--space`'s pinned leg) resolves a credential the way a spawn resolves it |
+| `host.pi` | warn | `pi` is on the host when napkin or longview is loaded |
+| `host.timezone` | warn | no active cron task carries `timezone: null` — a zoneless cron is parsed as UTC on every host, so the host's own zone is evidence, not the condition |
+| `host.swap` | warn | a host of ≤ 4 GiB has swap |
+| `extensions.load-report` | warn | every extension on disk is loaded, or skipped **with a reason** |
+
+**Absence denies.** A probe that could not run is `blocked`, never `pass` — a
+gate that reports "nothing proved" as health is the 2026-09-01 `/health` that
+stayed green while every container on the box was doomed. A check downstream of
+a blocked prerequisite is `skipped` with a named `because`, so the report shows
+one blocker rather than seven.
+
+**It costs no tokens and changes nothing.** The round trip is an `mrctl` call,
+not a model turn. Preflight never builds or pulls an image, never writes the
+extensions dir, never writes the database, and never sends to a person; its
+only writes are the report and the probe containers it removes. The database
+half is not free: the round trip goes through the real API middleware, which
+calls `resolveRole`, which upserts a member row on first contact. `preflight`
+is therefore a reserved *ephemeral caller* (`EPHEMERAL_CALLERS` in
+`src/core/permissions.ts`) that resolves as `member` without being written or
+seeded — deliberately not a system caller, which would hand the probe token
+system-level permissions. For the same caller the middleware also refuses to
+create the space it names (`ensureSpace` would insert it, and bump `updated_at`
+even when it exists) — so the round trip needs an existing space, and on a box
+whose spaces are not named `main` you pass `--space <id>`; without it the
+command exits 2 before minting anything. It loads
+extensions through the same helper boot uses, but read-only: boot creates the
+`node_modules/mercury-agent` package symlink, preflight only reads it. The one
+consequence worth knowing is that on a box where the service has **never**
+started, that link does not exist yet, so an extension importing
+`mercury-agent` is reported as a load-error the running service will not have —
+the check's own remedy says so. Probe containers carry `mercury.managed=true`,
+so a crash mid-probe leaves something the next boot's orphan sweep reaps.
+
+The report is written to `<dataDir>/preflight/<timestamp>.json` with a copy at
+`latest.json` (or to `--report <path>`). It is the evidence a deploy attaches;
+the terminal output is a convenience — `docs/live-testing.md` § 7 and rule 6
+of § 8 say why a gate whose report was not persisted did not pass, and where
+preflight stops ("can this box run a turn", never "is the scenario working"). Under `MERCURY_SHADOW=1` it runs against
+the shadow's own config and data dir, and the M1.2 refusal applies unchanged.
+
+**The round trip needs no `MERCURY_CALLER_TOKEN_KEY`, and says which identity
+it used.** Preflight mints its probe token in its own process, so a *configured*
+key is the only way the service can verify it: with none set, `caller-token.ts`
+falls back to a random key generated once **per process** and the two ends can
+never agree. The check therefore picks its auth mode from the config
+(`roundtripCallerAuth`, `src/preflight/checks/roundtrip.ts`) and reports it as
+`callerAuth` in the evidence:
+
+| `callerAuth` | When | What the pass proves |
+|---|---|---|
+| `token` | `MERCURY_CALLER_TOKEN_KEY` (or `caller_token_key`) is set | the whole production shape — transport, `API_SECRET`, the minted caller token, and the identity the host hands back |
+| `headers` | no key configured (the shipped default) | transport, `API_SECRET` and the identity — the token leg is **not** exercised, and the pass title says so |
+
+In `headers` mode the probe simply omits `CALLER_TOKEN`, so `mrctl` sends no
+`x-mercury-token` and the host resolves `x-mercury-caller` / `x-mercury-space`
+through the fallback it has always had for token-less callers. Nothing is
+relaxed: every request on either mode still has to carry
+`Authorization: Bearer <API_SECRET>`, and `authorizeApiSecret`
+(`src/core/auth.ts`) fails **closed** — 503 when the service has no secret
+configured, 401 on a missing or mismatched one — before any identity header is
+read. Setting the key is still worth doing, because it upgrades the check from
+`headers` to `token` and is required by anything that mints in one process and
+verifies in another; the real agent containers never needed it, since the
+service mints and verifies their tokens in one process. Before 2026-09-06 the
+absent key was a permanent blocker (`401 Invalid or expired caller token` on
+every run, with a remedy that sent the operator to compare a `.env` with
+itself) —
+`docs/debug/moderate/2026-09-06-preflight-roundtrip-cannot-pass-without-configured-caller-token-key.md`.
+
+**After changing the Dockerfile or bumping the version, `image.contract` blocks
+until the image is rebuilt** (`container/build.sh`, then restart so the derived
+image follows). That is the point: it is the "a restart does not redeploy the
+image" trap made visible instead of silent.
+
 ## Agent Image Preset
 
 Mercury publishes an image preset to GitHub Container Registry:
@@ -222,7 +332,47 @@ Mercury publishes an image preset to GitHub Container Registry:
 |--------|------|----------|
 | `ghcr.io/avishai-tsabari/mercury-agent:latest` | ~2.8GB | Full devcontainer: Bun, Node.js, Python, Go, git, build tools |
 
-Images are published on each release. Version-specific tags are also available (e.g., `:0.2.0`).
+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.
+
+> 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`
+> G-007.
+
+### Staying Current
+
+A floating tag used to mean "whatever this box pulled the first time":
+`ensureImage()` returned as soon as `docker image inspect` succeeded, so a host
+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 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
+registry host in its first path component, which is `mercury-agent:latest` and
+`mercury-agent-ext:<hash>` — and, deliberately, a bare Docker Hub name such as
+`someuser/mercury-agent:latest`: a false pull attempt on every local build is
+a worse daily cost than a missed refresh on a shape nothing here uses. Pin such
+an image by digest, or give it a registry host, to get refreshes. A refresh
+that fails warns and the service continues on the image it already has.
+
+Either way boot logs one `Agent image resolved` line carrying the reference,
+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:…
+```
+
+`imageVersion` is the image's `com.mercury.version` label (release-gate R0.1
+stamps it from the build arg); `mercury preflight`'s `image.contract` check
+reads the same version from `/app/image-manifest.json` inside the image.
 
 ### Building Locally
 

package/docs/context-architecture.md

@@ -48,8 +48,12 @@ The session boundary (`chat_state.min_message_id`) excludes messages older than
 ### System prompt layering (broadest → most specific)
 
 ```
-1. pi built-in prompt (Claude Code identity, tool definitions)
-   — or Mercury's override when OVERRIDE_PI_SYSTEM_PROMPT is set
+1. Mercury's own standalone prompt (identity, tool list, guidelines)
+   — the default; pi's built-in prompt is replaced via --system-prompt.
+   Set MERCURY_OVERRIDE_PI_SYSTEM_PROMPT=false to keep pi's built-in prompt
+   (Claude Code identity, tool definitions) and append instead — but see
+   docs/configuration.md: that mode is rejected under an Anthropic OAuth
+   credential.
 
 2. Mercury platform additions (buildMercuryAdditions)
    — identity, inbox/outbox, permissions, moderation, capabilities, memory guidance

package/docs/extensions.md

@@ -328,7 +328,9 @@ mercury.job("appointment-reminders", {
 });
 ```
 
-`to` resolves callerId-first: an exact space id, a raw WhatsApp caller id (phone JID or opaque LID — same normalization that keys DM auto-spaces), a platform-qualified id (`whatsapp:123@lid`), or a phone with leading `+`. It never creates spaces — sending to someone without an existing conversation fails.
+`to` resolves callerId-first: an exact space id; otherwise the space the recipient's existing DM conversation is linked to (with DM auto-spaces on, an admin's DM lands in `main`, and any DM can be re-linked by hand — the `conversations` table, not a naming convention, knows where a person is reachable); otherwise the derived DM auto-space (`dm-<id>`), which still delivers to the person's own conversation row when one exists unlinked. The conversation step matches WhatsApp and Telegram, whose DM rows are keyed by the person's id; on Discord and Slack a DM row is keyed by its channel id, so address the DM **channel** id — a user id resolves through neither the conversation lookup nor the derived space. Recipient ids are loose: a raw WhatsApp caller id (phone JID or opaque LID, with the learned LID↔phone alias tried too), a platform-qualified id (`whatsapp:123@lid`), or a phone with leading `+`. It never creates spaces — sending to someone with neither a linked conversation nor an auto-space fails.
+
+**Delivery is the conversation, not the space.** When `to` names a person, the message goes to that person's one conversation and no other — even when its space holds several. The space is how the person is found; it is not the audience, and a space that also holds a group never sees a message addressed to a person. That holds on both person-resolving steps: a person whose auto-space exists but whose conversation row Mercury has never seen is `unknown_recipient` rather than a send to the auto-space, because the auto-space may hold something other than their DM. (Resolving an exact space id is the caller explicitly asking for the space, and still reaches everything linked to it.) The result stays `{ spaceId }`: it says who was reached, not which thread received it.
 
 Failures throw `DirectSendError` with a `reason` you can branch on: `sender_not_ready` (adapters not up yet, or the context has no delivery path — e.g. connection status probes), `unknown_recipient` (no existing space matches), `invalid_text` (empty or over 4096 chars).
 
@@ -469,6 +471,12 @@ The skill is installed into the management space's own workspace on
 dir mounted into *every* container, which would advertise the capability to
 spaces that cannot use it.
 
+The description alone is not enough to make the model reach for the skill
+unprompted, so `before_container` also returns a management-space-only
+`systemPrompt` fragment (layer 3a) stating the fact that other spaces are
+readable from here — the same scoping check `workspace_init` uses, so no other
+space's agent ever sees it.
+
 ## Morning / Green Invoice invoicing (`morning`)
 
 `examples/extensions/morning/` issues tax documents through the