mercury-agent 0.16.3 → 0.17.0

package/README.md

@@ -417,10 +417,22 @@ Supported OAuth providers: Anthropic, GitHub Copilot, Google Gemini CLI, Antigra
 | `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) |
+| `MERCURY_CONTAINER_ALLOW_UNCONFINED` | `false` | Set `true` to accept the Docker Desktop sandbox relaxation (see note below) |
 | `MERCURY_AGENT_ID` | — | Unique ID for this assistant (required when running multiple assistants on the same Docker daemon) |
 
 > **Multiple assistants on the same machine:** Mercury builds a derived Docker image (`mercury-agent-ext:<hash>`) from the base image plus your extensions. When a new image is built, older tags in the same repo are pruned. If two assistants share a Docker daemon without distinct `MERCURY_AGENT_ID` values, they share the same image repo and **one will silently prune the other's image**, causing container launch failures. Set `MERCURY_AGENT_ID` to a unique value per project (e.g. in `.env`). Cloud console deployments set this automatically.
 
+> **Docker Desktop (macOS/Windows):** Mercury detects Docker Desktop and would
+> otherwise relax the sandbox automatically (`--security-opt seccomp=unconfined
+> --cap-add SYS_ADMIN`) so `bwrap` can nest. It now **refuses to do that
+> silently**: containers fail to start with a message naming the remedy.
+> Set `MERCURY_CONTAINER_ALLOW_UNCONFINED=true` (or `agent.allow_unconfined:
+> true` in `mercury.yaml`) to accept the trade knowingly — it is then logged at
+> `warn` on every spawn. **Upgrading an existing Docker Desktop install requires
+> this**, or every message gets a generic container failure. Linux hosts are
+> unaffected; `MERCURY_CONTAINER_RUNTIME=runsc` (gVisor) avoids the relaxation
+> entirely, and the flag is ignored when `container_bwrap_docker_compat` is set.
+
 > **Linux Docker Engine:** Mercury uses [bubblewrap](https://github.com/containers/bubblewrap) for in-container sandboxing. On Linux Docker Engine (not Docker Desktop), bwrap cannot mount `/proc` without extra privileges. Either set `container_bwrap_docker_compat: true` in `mercury.yaml` (adds `--privileged` to `docker run`), or install [gVisor](https://gvisor.dev/docs/user_guide/install/) and set `MERCURY_CONTAINER_RUNTIME=runsc` to skip bwrap entirely.
 
 **KB Distillation:**

package/container/Dockerfile

@@ -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/text/sanitize-text.ts /app/src/text/sanitize-text.ts
 COPY src/types.ts /app/src/types.ts
 COPY resources/ /app/resources/
 COPY examples/extensions/ /tmp/examples-extensions/

package/container/Dockerfile.base

@@ -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/text/sanitize-text.ts /app/src/text/sanitize-text.ts
 COPY src/types.ts /app/src/types.ts
 COPY resources/ /app/resources/
 COPY examples/extensions/ /tmp/examples-extensions/

package/docs/autopilot/config.yaml

@@ -0,0 +1,43 @@
+# Autopilot Configuration
+# Read by the orchestrator each iteration. See docs/templates/TEMPLATE-AUTOPILOT-CONFIG.yaml.
+
+gates:
+  max_iterations: 10
+  max_features_without_review: 3
+  max_retries_same_task: 3
+  iteration_timeout_minutes: 30
+
+risk:
+  sensitive_paths:                     # changes to these = immediate stop for review
+    - "**/auth/**"
+    - "**/migration*"
+    - "**/.env*"
+    - "**/schema*"
+    # Container spawn shape: sandbox flags, mounts, network, runtime selection.
+    # A wrong change here passes `bun run check` and is only observable in the
+    # running container — the check gate cannot verify it. Human-only.
+    - "src/agent/container-runner.ts"
+    - "src/agent/container-entry.ts"
+  auto_stop_risk_threshold: 8
+
+scope:
+  allowed_actions:
+    - implement_feature
+    - continue_feature
+    - fix_bug
+    - execute_refactor
+    - sync_docs
+  skip_slugs:                          # never touch autonomously
+    # Both are design decisions, not mechanical fixes, and neither is verifiable
+    # by the check suite. See docs/bugs/ for the filed reports.
+    - docker-desktop-sandbox-relaxation-silent   # fix = a product call: warn, or refuse and break Docker Desktop users
+    - container-egress-unrestricted              # architecture: needs a chosen proxy/allowlist shape
+    # attachment-ingest-type-gating — unblocked 2026-08-27 (warn-only decision
+    # recorded in the spec). Eligible once it is listed under ROADMAP Now/Next.
+
+planning:
+  allow_autonomous_planning: false
+
+notifications:
+  on_stop: console
+  decision_log: docs/autopilot/decision-log.md

package/docs/behavior-layers.md

@@ -29,6 +29,9 @@ the repo, after a pi upgrade.
      ## Run budget                        (tools-capable models only)
      ## Destructive Operations — Confirmation Required
      ## Presenting tool results           ("simple lists", "never show JSON/commands")
+     ## 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"
                                            — only for a caller holding prefs.set)
      reply-anchor sentence                (swipe-replies only)

package/docs/container-lifecycle.md

@@ -192,6 +192,7 @@ The pi agent runs inside `bwrap`, which creates a minimal mount namespace with o
 | Env Var | Purpose |
 |---------|---------|
 | `MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=1` | **Host only.** Adds `docker run --security-opt seccomp=unconfined --cap-add SYS_ADMIN` so `bwrap` can nest inside the agent container (e.g. Docker Desktop). Keeps bubblewrap on. |
+| `MERCURY_CONTAINER_ALLOW_UNCONFINED=true` | **Host only.** Accepts the *auto-detected* Docker Desktop relaxation (same flags as above). Defaults to `false`, so on Docker Desktop containers refuse to start until it is set — the relaxation is never applied without the operator seeing it. Logged at `warn` on every spawn once enabled. Ignored under `runsc` and when `BWRAP_DOCKER_COMPAT` is set. |
 | `MERCURY_DISABLE_BUBBLEWRAP=1` | Disable bubblewrap; run pi directly (last resort / debugging) |
 
 If you see `bwrap: Creating new namespace failed: Operation not permitted`, try **`MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=1`** first so you keep defense-in-depth. Only use `MERCURY_DISABLE_BUBBLEWRAP=1` if compat mode is not enough.

package/docs/extensions.md

@@ -397,6 +397,49 @@ mercury extensions list    # or: mercury ext list
 
 Shows all installed extensions (user + built-in) with features and descriptions.
 
+## Cross-Space Overview (`overview`)
+
+`examples/extensions/overview/` gives **one** designated space a read-only
+window onto the others — the only cross-space read an agent has. It is not a
+builtin: install it deliberately.
+
+```bash
+mercury add ./examples/extensions/overview
+MERCURY_MANAGEMENT_SPACE_ID=<space id>   # host-only; unset = every read denied
+```
+
+The agent calls it with `mrctl capability overview <action> '<json>'`:
+
+| Action | Body | Returns |
+|--------|------|---------|
+| `list` | — | every space with `messageCount`, `conversationCount`, `platforms`, `lastActivity` |
+| `recent` | `{spaceId, limit?}` | that space's latest messages, newest first |
+| `search` | `{q, spaceId?, limit?}` | substring matches; every space when `spaceId` is omitted |
+| `tasks` | `{spaceId?, limit?}` | scheduled tasks, one space or all |
+| `roles` | `{spaceId}` | role assignments |
+
+`limit` defaults to 20 and is capped at 100; message bodies — and a task's
+`prompt` and `lastError` — are truncated at 500 characters with
+`truncated: true`. Every action is a plain `SELECT` — there is no
+cross-space write, and `listMutes` is deliberately not exposed because it deletes
+expired rows.
+
+Three gates run before any action, in the handler, and they are the whole
+boundary:
+
+1. `MERCURY_MANAGEMENT_SPACE_ID` is set — **absence denies**.
+2. The caller's token-bound space id equals it, by exact string equality.
+3. The caller is a global admin (`config.admins` / `dmAutoSpaceAdminIds`).
+
+The `overview` permission checked by the capability route is **not** a scope:
+`admin` is granted every registered permission in its own space, so every space
+admin in the deployment passes it. Only the three gates above stop them.
+
+The skill is installed into the management space's own workspace on
+`workspace_init`, not via `mercury.skill()` — that copies into the global skills
+dir mounted into *every* container, which would advertise the capability to
+spaces that cannot use it.
+
 ## Examples
 
 See [`examples/extensions/`](../examples/extensions/) for complete, working extensions ranging from minimal (charts — CLI + skill) to full-featured (napkin — hooks, jobs, config, widgets, KB distillation).

package/docs/goals/football-reporter-profile/decisions.md

@@ -475,5 +475,41 @@
   implementing: `## Current State (as of …)` is not matched by the injector, so
   every note napkin had written for this space was reaching the model as a
   summary line with no facts —
-  `docs/bugs/episode-current-state-heading-suffix-drops-body.md`.
+  `docs/debug/major/2026-08-31-episode-current-state-heading-suffix-drops-body.md`.
 - **Used by:** reporter-notebook (M2.3, re-cut), football-reporter-fixture-harness (provenance source = `episodes/`), napkin (distill addendum)
+
+## D-020: Live tuning is adopted into the repo, not reverted — and scans carry a fixed club emoji (decided 2026-08-31)
+- **Category:** layer placement / process (refines [D-003](#d-003-layer-placement-for-football), [D-013](#d-013-tone-is-editorial-and-scan-length-is-per-item-decided-2026-08-20))
+- **Decided:** (1) When the owner edits the live `AGENTS.md` on the box while
+  the bot is running, the repo **adopts** the live text (copy live → repo,
+  read the whole file for the contradiction the edit introduced, fix that in
+  the repo, `apply`) — it never reverts it with `apply`. The live file is the
+  owner's most recent editorial judgement and the repo's job is to record it;
+  `check` failing is the signal to reconcile, not to overwrite. (2) The
+  2026-08-27 edits are now the standard: every scan item opens with one fixed
+  club emoji (😈 United, 🔵 Barcelona, ⚪ Real, 🔴 Hapoel TA, 💛 Beitar,
+  🟢 Maccabi Haifa; none for an item outside those six, none invented), items
+  are grouped under one club heading when several concern one club, an item
+  is ≤ 200 characters including its `(source, dd/mm)`, items are separated by
+  a blank line, the displayed date is `dd/mm` while the year is still verified
+  in the source, and the article stays at zero emoji.
+- **Alternatives considered:**
+  - *Revert the box to the repo with `apply`.* Rejected: the edits are the
+    owner's, dated, and were running for four days; the repo was the stale
+    copy.
+  - *Keep "0 emoji in scheduled output" as decided at the M1 checkpoint.*
+    Rejected by the owner's edit: a fixed per-club marker is a format element
+    (it tells a phone reader which club before the sentence), not decoration.
+    M3.1's emoji lint becomes an **allowlist** (exactly one of the six, at line
+    start, scan only) rather than a zero count.
+- **Reasoning:** `check` on 2026-08-31 reported one difference — `AGENTS.md`
+  — whose diff was purely additive owner tuning from 2026-08-27 15:39. The
+  same file's `## סגנון` still said "scan and article: zero", so the adoption
+  also fixed the in-file contradiction the guide's §4.5 warns about. The
+  fourth bullet the owner added ("no English working sentence as a first
+  line") is a prose rule over a host defect and did not hold (four leaks after
+  it); it stays in the file as documentation of intent but the fix is
+  `docs/bugs/narration-in-same-text-block-leaks-into-reply.md`.
+- **Revisit if:** live edits become frequent — then the right tool is a
+  profile PR flow from the box (edit → `dump` → commit), not a rule.
+- **Used by:** football-reporter profile (`AGENTS.md`), football-reporter-fixture-harness (M3.1 lint spec)

package/docs/goals/football-reporter-profile/roadmap.md

@@ -1,7 +1,7 @@
 # Roadmap: Football Reporter Profile
 
 **Goal**: [football-reporter-profile](goal.md)
-**Last updated**: 2026-08-25 (M2.4 shipped — `persona.exclusive` and permission-gated platform sections; deploy pending an image rebuild)
+**Last updated**: 2026-08-31 (M2.1/M2.3/M2.4 live; the M2 cost failure is diagnosed, fixed and verified on the live bot — verify-run prefix 118 K → 50.6 K, projection ≈ $5.4/day, ledger confirmation due 09-01 → 09-03; live `AGENTS.md` tuning adopted per D-020)
 
 > Sequence chosen by the owner on 2026-08-20: (1) profile + one editorial
 > layer → (2) deterministic feed → (3) proof of quality, with a parallel bug
@@ -55,11 +55,11 @@ the group's reaction to the first two articles is recorded in the goal's notes.
 
 | ID | Story | Slug | Depends on | Status |
 |----|-------|------|------------|--------|
-| M2.1 | Feed Watch — host-side poller, digest into the article, verify one-shots (existing spec, absorbed) | feed-watch | M1.1 | done (merged `e07b239` 2026-08-21; **deploy not yet run** — runbook in `pending-verification.md`) |
+| M2.1 | Feed Watch — host-side poller, digest into the article, verify one-shots (existing spec, absorbed) | feed-watch | M1.1 | done (merged `e07b239` 2026-08-21; **live since 2026-08-25 17:16 UTC**, enabled by the owner from chat — the runbook's 19 checks were never walked; cost evidence below) |
 | M2.2 | Scheduled task model-leg policy: primary-or-skip for research runs (F2) | scheduled-task-model-leg-policy | — | deferred until after M3.1 (D-015) |
-| M2.3 | Reporter notebook, re-cut 2026-08-21 (D-019): topic notes are napkin-shaped **episodes** the profile seeds once and napkin maintains nightly, written in-turn before posting; seeded `MEMORY.md` for standing facts; priorities tie-break in `AGENTS.md`; `workspace_seed` in `space-profile`; per-space distillation addendum in napkin; member perms and stale-note hygiene (audit R1/R6/R7, D-016, D-019) | reporter-notebook | M1.1 | done (merged 2026-08-22; **deploy not yet run** — runbook in `pending-verification.md`) |
-| M2.4 | One voice per space: `persona.exclusive` drops the global character and global `AGENTS.md` for a space that owns its standard; platform-prompt capability paragraphs gated on the caller's permissions (audit R2, D-017) | one-voice-per-space | — | done (merged 2026-08-25; **deploy not yet run** — needs an agent image rebuild, runbook in `pending-verification.md`) |
-| M2.5 | Chat window holds conversation, not procedure (scheduled prompts out of the turn count, no halving on swipe-reply); silence is a legal chat reply (audit R3/R4, D-018) | chat-window-and-silence | — | backlog (host) |
+| M2.3 | Reporter notebook, re-cut 2026-08-21 (D-019): topic notes are napkin-shaped **episodes** the profile seeds once and napkin maintains nightly, written in-turn before posting; seeded `MEMORY.md` for standing facts; priorities tie-break in `AGENTS.md`; `workspace_seed` in `space-profile`; per-space distillation addendum in napkin; member perms and stale-note hygiene (audit R1/R6/R7, D-016, D-019) | reporter-notebook | M1.1 | done (merged 2026-08-22; **deployed 2026-08-22 23:07 IDT**; 19 episode notes on the box by 08-31, `MEMORY.md` written by the bot — 7 of 10 evidence checks still unticked in `pending-verification.md`) |
+| M2.4 | One voice per space: `persona.exclusive` drops the global character and global `AGENTS.md` for a space that owns its standard; platform-prompt capability paragraphs gated on the caller's permissions (audit R2, D-017) | one-voice-per-space | — | done (merged 2026-08-25; **deployed 2026-08-25 16:44 IDT** with the image rebuild; `persona.exclusive=true` live; 6 behaviour checks still unticked) |
+| M2.5 | Chat window holds conversation, not procedure (scheduled prompts out of the turn count, no halving on swipe-reply); silence is a legal chat reply (audit R3/R4, D-018) | chat-window-and-silence | — | done (merged 2026-08-31; live checks queued in `pending-verification.md` §M2.5, deploy-gated) |
 
 > **Revisit 2026-08-21 — napkin works now** (`docs/notes/napkin-revisit-2026-08-21.md`). **Approved by the owner the same day ([D-019](decisions.md)):** M2.3 re-cut so the topic notes are napkin-maintained episodes under `knowledge/episodes/` (the only injected dir) that the profile seeds once, plus a per-space distillation addendum. Nothing removed; M2.4/M2.5/M3.x unchanged. Idea parked: `docs/ideas/napkin-member-notes.md`.
 
@@ -91,6 +91,58 @@ and a member run's system prompt carries no preference-management paragraph; a
 swipe-reply follow-up sees the bot's own post from the previous evening; a
 "don't answer" message in `main` gets no reply.
 
+> **Checkpoint evidence, read from the box 2026-08-31** (ledger `task_runs`,
+> `space_config`, `messages`; nothing gated, everything reported per D-008):
+>
+> - **Passed:** task 28 and `tasks/scan.md` are gone; verify one-shots produce
+>   either a sourced item line or `NO_UPDATE` (08-31 sample: 5 posted / 6
+>   no_update); the 09:00 article runs daily with the digest (`last_status=ok`,
+>   608-char summary on 08-31); `persona.exclusive=true` is live and the image
+>   carries `callerMay`; every run since 08-25 is single-leg (no fallback
+>   possible under the pin).
+> - **Failed:** the **cost direction**. 46–48 runs/day, ~70 % `no_update`,
+>   **$14–20/day** for the space (08-26 → 08-30) against "well under
+>   ~$5.30/day" and a pre-M2 baseline of ~$3/day.
+>   **Diagnosis corrected 2026-08-31 (second read, from `token_usage` and the
+>   traces, not `task_runs`):** the standard + notebook is *not* the cost — a
+>   verify run on that prefix was ~37 K tokens / $0.09 on 08-25. Since 08-26
+>   every run cache-writes ~121 K tokens / $0.30, because the daily article's
+>   expanded 103 KB digest is persisted and replayed through the history
+>   window — `docs/debug/major/2026-08-31-feed-watch-digest-persisted-and-replayed.md`, on the
+>   bug track below. Cost law: `cost/day ≈ runs × prefix tokens × $2.50/M`.
+>   Fix order: host persists the pre-append prompt (removes the replay) →
+>   digest without links + a cap (the article's own prefix) → profile levers
+>   `max_per_hour` 1, `batch_minutes` 15, `exclude` mined from `NO_UPDATE`
+>   replies (the run count). Expected after the first two: ~$4.5/day at
+>   today's run count, ~$2.5–3 with the levers.
+>   **All three shipped and were verified on the live bot 2026-08-31** (`fad12f9`,
+>   `81d022e`; two on-demand article runs against the test group rather than
+>   waiting for 09:00). The article turn is 105,482 → 4,322 chars, the digest
+>   block 36.0 KB for a *larger* window, and a verify run's first-round prefix
+>   **118 K → 50.6 K**. Projection ≈ $5.4/day; the ledger over 09-01 → 09-03 is
+>   what closes the spend check. `exclude` mining was **not** done — the run
+>   count is already capped at 1/hour and the prefix is the bigger factor.
+>   Correction to the measurement method, worth more than the number: the
+>   comparable prefix is the **first round's** `cacheWrite` from the trace, not
+>   `token_usage.cache_write_tokens`, which sums every round and so makes a
+>   16-round article look more expensive than a 1-round `NO_UPDATE`. **The "per-task cheaper leg"
+>   rationale for re-opening M2.2 does not survive this** — decide M2.2 on
+>   safety after the bug is fixed, not on cost before it. Second-order levers
+>   filed as ideas: `isolated-verify-task-runs.md`, `cross-run-prompt-caching.md`.
+>   The ledger that hid this for six days is its own bug:
+>   `task-runs-ledger-input-tokens-is-uncached-sliver.md`.
+> - **Changed under us:** the space's `model.active` is `claude-sonnet-5`
+>   since 2026-08-24 (owner's `/model switch`), so "zero posts from a
+>   non-primary leg" is true only because there is no fallback; the primary is
+>   no longer Opus. Sonnet narrates: 10 of 121 replies since 08-22 open with an
+>   English working sentence (`docs/bugs/narration-in-same-text-block-leaks-into-reply.md`).
+> - **Not evidenced:** the trace checks (topic note read on a factual
+>   question, no `AGENTS.md` mount for the exclusive space during a run), the
+>   swipe-reply continuity and the "don't answer" silence — all need a person
+>   watching a run; still open in `pending-verification.md`.
+> - **Drift:** the owner tuned the live `AGENTS.md` on 08-27; adopted into the
+>   repo 08-31 ([D-020](decisions.md)).
+
 > **Extended 2026-08-21 ([D-016](decisions.md)–[D-018](decisions.md)).** The
 > 2026-08-21 audit (`docs/notes/football-audit-2026-08-21.md`) traced both
 > owner-reported failures — a hallucinated name and a joke refused as a
@@ -146,6 +198,12 @@ is filed the same way, never fixed inside the story.
 | — | `model-switch-disables-fallback.md` | moderate | M4.1 |
 | audit-2 C9 | `feed-watch-seen-ttl-not-refreshed.md` | moderate | M4.1 (fix **before** the feed-watch deploy) |
 | audit-2 C10 | `feed-watch-runas-non-user-principal.md` | moderate | M4.1 (fix **before** the feed-watch deploy) |
+| M2 checkpoint | `feed-watch-digest-persisted-and-replayed.md` | major | **DONE** 2026-08-31 — fixed, deployed, verified on the live bot (`fad12f9` + `81d022e`). M2.2 is now unblocked and must be decided on *safety*, not cost |
+| M2 checkpoint | `task-runs-ledger-input-tokens-is-uncached-sliver.md` | minor | **DONE** 2026-08-31 — `cache_read_tokens`/`cache_write_tokens`/`prompt_prefix_tokens`/`rounds` on the row, one derived `billedPromptTokens` for every reader, dashboard shows Prefix · Rounds · Billed. Deployed with an image rebuild (`src/types.ts` is baked); audited 2026-08-31 against raw traces and a smoke run (298). Post-mortem in `docs/debug/minor/` |
+| M2.3 checkpoint | `episode-current-state-over-budget.md` | moderate | **Re-ranked 2026-08-31** — only ONE episode is injected per run, not all: 1-12% of the prompt (barcelona 11.6 KB worst case), not the "24 KB every run" filed. Still worth the pruning rule for note *quality*; it is not the cost lever it was filed as |
+| — | `football-group-went-silent-under-the-feed.md` | minor | posting budget for a test group; stale `space_roles` tidy |
+| — | `episode-current-state-heading-suffix-drops-body.md` | major (latent) | **DONE** 2026-08-31 (`b18e9ca`, deployed with a rebuild) — does not reproduce today: every live note carries an HTML-comment workaround telling the distiller to keep the heading bare. Fixed at the parser so one rewrite cannot silently return it |
+| M2 follow-on | `history-window-dominates-the-run-prefix.md` | major | **NEW** 2026-08-31 — `<history>` is 65–81% of every prompt (~68 KB, near-constant across runs). The largest remaining prefix term by a wide margin, and never a bug — a default meeting an unusual space. **Read M2.5's architecture first**: this may be evidence for that story rather than a separate fix |
 
 The two `feed-watch-*` rows come from the 2026-08-21 audit's second pass
 (`docs/notes/football-audit-2026-08-21.md` §3.1): a `seen` TTL that counts

package/docs/permissions.md

@@ -210,6 +210,21 @@ Permissions are **per-space**:
 - Custom role permissions are space-specific
 - No global roles (except seeded admins, which apply on first interaction per space)
 
+### An extension permission is not a scope
+
+`admin` is granted **all** permissions — built-in *and* extension-registered — in
+its own space. So a permission registered by an extension gates members, and
+nothing more: every space admin in the deployment passes `checkPerm(<ext>)`
+automatically, including for a capability meant for one space only.
+
+An extension that must be restricted to particular spaces or particular callers
+has to enforce that inside its own handler. The `overview` extension
+(`examples/extensions/overview/`, see [extensions.md](extensions.md#cross-space-overview-overview))
+is the worked example: it reads other spaces' messages, and its real boundary is
+three in-handler checks — a host-only `MERCURY_MANAGEMENT_SPACE_ID` env var
+(absence denies), exact equality against the caller's token-bound space id, and
+`isGlobalAdmin`. Its `defaultRoles: []` keeps members out and does nothing else.
+
 ## API
 
 ### `resolveRole(db, spaceId, platformUserId, seededAdmins)`