mercury-agent 0.17.0 → 0.18.1

package/README.md

@@ -167,6 +167,7 @@ Install extensions from the dashboard (**Features** page), the CLI, or during se
 ```bash
 # From the CLI
 mercury add web-browser         # Web browsing & search (uses Brave Search, no API key needed)
+mercury add web-search          # Brave Search API + site search skill (key stays on the host)
 mercury add napkin              # Obsidian-style knowledge vault
 
 # Or pick a profile that bundles what you need
@@ -267,6 +268,12 @@ mercury conversations
 mercury conversations --unlinked
 mercury link <conversation-id> <space-id>
 
+# backups (state.db snapshots — also taken automatically by the running service)
+mercury backup create      # verified VACUUM INTO snapshot in <dataDir>/backups/
+mercury backup list
+mercury backup verify [snapshot]   # quick_check a snapshot (default: newest)
+mercury restore <snapshot> # verify + restore to a fresh path (never overwrites)
+
 # extensions
 mercury add ./path/to/extension
 mercury add npm:<package>
@@ -430,10 +437,11 @@ Supported OAuth providers: Anthropic, GitHub Copilot, Google Gemini CLI, Antigra
 > 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.
+> unaffected; `MERCURY_CONTAINER_RUNTIME=runsc` (or `agent.container_runtime:
+> runsc` in `mercury.yaml`; 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.
+> **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` (or `agent.container_runtime: runsc` in `mercury.yaml`) to skip bwrap entirely.
 
 **KB Distillation:**
 

package/docs/autopilot/config.yaml

@@ -31,7 +31,11 @@ scope:
     # 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
+    # container-egress-unrestricted moved to docs/ideas/ on 2026-09-01 -- the
+    # two-container split it proposed was ruled out by investigation. Its one
+    # remaining code-shaped piece is env-passthrough-defaults-to-all, below.
+    - env-passthrough-defaults-to-all            # breaking default change: needs the owner'''s go-ahead and a week of startup-log evidence first
+    - linux-default-sandbox-path-broken-on-modern-docker  # product call on the relaxation shape; unverifiable by the check suite (container spawn flags)
     # attachment-ingest-type-gating — unblocked 2026-08-27 (warn-only decision
     # recorded in the spec). Eligible once it is listed under ROADMAP Now/Next.
 

package/docs/configuration.md

@@ -85,6 +85,58 @@ Per-space: `mrctl config set ambient.enabled false` disables capture entirely (t
 
 You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
 
+## State database backups
+
+`state.db` is snapshotted by the storage sweep via `VACUUM INTO
+<dataDir>/backups/state-<timestamp>.db`. Every snapshot is verified
+(`PRAGMA quick_check`) before it counts; a crash mid-snapshot leaves only a
+`.partial` file that is never mistaken for a backup and is swept later.
+
+- **`MERCURY_BACKUP_INTERVAL_HOURS`** (default `12`) — a new snapshot is taken
+  once the newest one is at least this old.
+- **`MERCURY_BACKUP_RETENTION_COUNT`** (default `7`) — snapshots kept; older
+  ones are pruned by the same sweep.
+
+`mercury backup create | list | verify` manages snapshots by hand;
+`mercury restore <snapshot>` verifies a snapshot and writes it to a **fresh
+path only** (default `<dataDir>/state.restored-<timestamp>.db`) — it never
+overwrites the live database, and prints the manual swap-in steps.
+
+`mercury doctor` **fails** when no snapshot at most 24 h old exists (a missing
+backups directory included), and warns when the data dir sits on a
+9p/virtiofs/CIFS filesystem (a `.mercury/` under `/mnt/c` in WSL2, or a VM
+shared folder) — SQLite WAL locking is unreliable there.
+
+The database itself refuses to open when `quick_check` fails — loudly, with a
+typed error, never auto-repaired. The fix is `mercury restore`.
+
+## Shadow mode (`MERCURY_SHADOW`)
+
+**`MERCURY_SHADOW`** (default off; accepts only `1` or `true`,
+case-insensitively — every other spelling, `yes` and `on` included, means
+live) turns a process into a *rehearsal shadow*: it constructs no platform
+adapter, makes no console billing call, delivers no task output, marks every
+log line and the dashboard, and reports `shadow: true` on `/health`.
+
+**A shadow refuses to start unless its data dir is inside
+`<home>/mercury-shadow/`.** The flag keeps a shadow away from people; this
+keeps it away from live *state*. Without it, `MERCURY_SHADOW=1` started in
+the live project directory would construct no adapter and touch no session
+while running a **second scheduler against the live database** — every due
+task fires twice and SQLite gets a second writer.
+
+The check runs in `loadConfig()`, so every entry point inherits it, and it
+denies on absence at each input: no home directory (a systemd unit with no
+`HOME`), a relative data dir, a `..` segment, the shadow root itself, a path
+outside the root, or an existing directory whose `realpath` escapes the root.
+It compares path *segments*, never string prefixes, so `mercury-shadowy` is
+not inside `mercury-shadow`. A live process (`MERCURY_SHADOW` unset) is never
+checked and runs exactly the code it ran before.
+
+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.
+
 ## Container env passthrough (`agent.env_passthrough`)
 
 Controls which host `MERCURY_*` variables reach agent containers:
@@ -94,7 +146,7 @@ agent:
   env_passthrough: all       # all (default) | claimed
 ```
 
-- **`all`** — every `MERCURY_*` var except a fixed blocklist is passed into the container with the prefix stripped (`MERCURY_BRAVE_API_KEY` → `BRAVE_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.
+- **`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.
@@ -104,7 +156,7 @@ 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:
 
 ```
-Container env passthrough: all — these vars reach every space's container and are scoped to nothing. […] vars=MERCURY_BRAVE_API_KEY, MERCURY_BILLING_API_KEY
+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
 ```
 
 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.

package/docs/container-lifecycle.md

@@ -191,14 +191,29 @@ 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_CONTAINER_BWRAP_DOCKER_COMPAT=1` | **Host only.** Runs the agent container `--privileged` — Docker's widest grant (every capability, no seccomp, no AppArmor, all devices) — so `bwrap` can nest inside it. Keeps bubblewrap on, but the outer isolation layer is gone. Prefer `MERCURY_CONTAINER_RUNTIME=runsc`. |
+| `MERCURY_CONTAINER_ALLOW_UNCONFINED=true` | **Host only.** Accepts the *auto-detected* Docker Desktop relaxation (`seccomp=unconfined`, `apparmor=unconfined`, `--cap-add SYS_ADMIN` — narrower than `--privileged`). 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.
+**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).
 
 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:
+
+```json
+{
+  "runtimes": {
+    "runsc": {
+      "path": "/usr/bin/runsc",
+      "runtimeArgs": ["--host-uds=open"]
+    }
+  }
+}
+```
+
+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.
+
 ## Agent Image Preset
 
 Mercury publishes an image preset to GitHub Container Registry:

package/docs/extensions.md

@@ -160,6 +160,7 @@ mercury.on("workspace_init", async (event, ctx) => {
 | `workspace_init` | Space workspace created/ensured | No |
 | `before_container` | About to spawn container | Yes |
 | `after_container` | Container finished | Yes |
+| `delivery` | Reply stored, attachments final | No |
 
 Both `workspace_init` and `before_container` events include:
 - `workspace` — absolute host path (for file operations on the host)
@@ -198,6 +199,34 @@ mercury.on("after_container", async (event, ctx) => {
 });
 ```
 
+#### `delivery` — what the user actually received
+
+```typescript
+mercury.on("delivery", async (event, ctx) => {
+  // event.files    — exactly what the adapter will attach
+  // event.withheld — what the media gate stripped
+  // event.userMessageId / event.assistantMessageId — both rows exist
+});
+```
+
+Use this, not `after_container`, whenever a hook needs to know **what was
+delivered**. `after_container` fires *before* the media send gate and can still
+rewrite the reply, so its file list is a proposal: a handler reading it cannot
+tell whether the recipient was actually shown those files. `delivery` fires
+after the gate and after the assistant row is written.
+
+It is non-mutating — by the time it runs, the reply has been decided — and it
+does not fire on paths where nothing reaches the user: a suppressed reply, or a
+scheduler no-op. Handler errors are logged and isolated, so a failing handler
+costs a log line and never the reply.
+
+`event.withheld` exists so a handler can tell "withheld" from "never produced".
+Never treat a withheld file as delivered: the gate replaces the file array
+rather than annotating it, so this is the only place that distinction survives.
+
+The `archive` extension is the worked example
+([`examples/extensions/archive/`](../examples/extensions/archive/)).
+
 ### `mercury.job(name, def)`
 
 Register a background job that runs on the host.
@@ -440,6 +469,50 @@ 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.
 
+## Morning / Green Invoice invoicing (`morning`)
+
+`examples/extensions/morning/` issues tax documents through the
+[Morning](https://morning.co) API. Second `mercury.capability()` adopter after
+yahoo-mail, and the case that justifies rung 4: these credentials create legally
+binding documents against a real business, so they never enter a container.
+
+```bash
+mercury add ./examples/extensions/morning
+MERCURY_MORNING_CLIENT_ID=...      # hostOnly
+MERCURY_MORNING_CLIENT_SECRET=...  # hostOnly
+mrctl config set morning.environment sandbox   # or production; sandbox is the default
+```
+
+The agent calls it with `mrctl capability morning <action> '<json>'`:
+
+| Action | Body | Returns |
+|--------|------|---------|
+| `client-search` | `{name?, email?, page?, pageSize?}` | paginated clients |
+| `client-create` | `{name, taxId?, emails?, …}` | the new client |
+| `document-types` | `{lang?}` | `[{id, name}]`, localised |
+| `document-preview` | the document body | `{file, issueToken}` — base64 PDF, nothing created |
+| `document-create` | the same body **plus `issueToken`** | `{id, number, url}` |
+| `document-search` | `{fromDate?, toDate?, type?, …}` | paginated documents |
+| `document-links` | `{id}` | `{origin, he, en}` |
+
+Two properties are enforced in the broker rather than requested in the skill:
+
+- **Preview before issue.** `document-create` refuses without a single-use
+  `issueToken` minted by `document-preview` of the *identical* payload. The
+  token is bound to the payload hash, the environment, the space and the caller,
+  so a changed amount, a sandbox-previewed document presented against
+  production, another person's preview, or a retry after a successful create are
+  each refused. A prompt instruction is not a control when the model may be the
+  thing under attack.
+- **`sensitive: true`.** In a group-linked space the runtime then requires
+  `security.sensitive_connections_allowed` plus per-caller confirmation. Set that
+  key or the space refuses every turn — the symptom otherwise reads as a broken
+  extension.
+
+Slice 1 is invoices. Expenses are deferred: `POST /expenses` requires an
+`accountingClassification` whose lookup endpoint is absent from the published
+spec, and an uploaded file becomes a draft with no API to approve 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,7 +475,7 @@
   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/debug/major/2026-08-31-episode-current-state-heading-suffix-drops-body.md`.
+  `docs/debug/major/08-2026/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)
@@ -513,3 +513,106 @@
 - **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)
+
+## D-021: The daily article is an article, not a page of bins (decided 2026-09-01)
+- **Category:** article contract / design (extends [D-005](#d-005-keep-telegraph-make-the-summary-fuller-and-redesign-the-article-itself-decided-2026-08-20), [D-010](#d-010-the-chat-summary-is-author-supplied-by-the-same-run-not-a-second-model-call); refines [D-013](#d-013-tone-is-editorial-and-scan-length-is-per-item-decided-2026-08-20))
+- **Decided:** The owner opened the 2026-09-01 page on a phone (RTL fine) and
+  ruled the design wrong: *"it still looks too much like an itinerary and not
+  an article."* Eight prototype pages were published and compared on the phone
+  the same evening; prototype **C5** is the target shape. Five rulings:
+  1. **Images are in**, but only when the image is good and relevant, and it
+     must not take over the page. C2 (one wide banner) beat C1 (none); C4/C5
+     (a press photo) beat both.
+  2. **Side-by-side is dropped** — a platform limit, not a preference.
+     Telegraph strips every attribute except `src` and unwraps a `div`, so an
+     image beside text is impossible; footprint is controlled by aspect ratio
+     only (a 4.5:1 banner is ~85 px tall on a phone, a portrait ~430 px).
+  3. **Press photos are allowed**, hotlinked from the cited source and credited
+     in the caption. `telegra.ph/upload` answers 400, so hotlinking is the only
+     path anyway.
+  4. **The long source list goes.** Short bracketed links inline —
+     `([וואלה](url))` — plus **one** italic footer line naming every outlet
+     read. The footer line stays.
+  5. **Stay on Telegraph.** A richer target (real CSS, images beside text,
+     cards) is possible through `longview`'s `targets/` seam but needs a host
+     and is a separate project.
+
+  And four image rules, learned by publishing a wrong one (C4's hero showed
+  Anthony Gordon under a caption, written from assumption, naming Álvarez):
+  the image URL is the cited article's `og:image`; the caption is the source's
+  own caption, translated, never re-described — it lives in the article HTML,
+  not the RSS; no caption at the source means no image; the photo sits in the
+  section whose story it depicts, not automatically at the top (C5 is C4 with
+  only that changed). Wikimedia Commons is not a substitute: wide and relevant
+  are mutually exclusive there.
+
+  Two consequences the owner confirmed on 2026-09-01 when the story was
+  planned: the per-article "first three blocks get similar length" measure no
+  longer applies — the lead story leads, and the coverage balance in
+  `AGENTS.md` § תפקיד is a rule about coverage over time; and the
+  `DD.MM.YYYY · N מקורות` dateline goes, replaced by Telegraph's own
+  author-and-date block under the headline (`author_name`, empty on every page
+  published so far, is free article furniture).
+- **Alternatives considered:**
+  - *Typography only, words unchanged (prototype A).* Better, and most of it
+    needs no code — `>>`, `---` and numbered lists are already in the
+    renderer. Not enough on its own: the bins are the tell, not the type.
+  - *Keep the eight blocks and drop only the empty ones.* Rejected: the same
+    headings in the same order every day is what reads as generated, whether
+    or not a bin is empty.
+  - *Images beside text via `h3`/`h4` level or `div` wrappers.* Measured
+    impossible (rule 2). Heading level is not a lever either: `h3` is 28 px,
+    `h4` 24 px, both sans-bold.
+  - *Commons images.* Every wide result is a stadium panorama, every usable
+    player photo a portrait, nothing of *yesterday's* match.
+- **Reasoning:** the contract shipped by M1.2 is followed correctly — every
+  element renders — and the page still reads as a log because the contract
+  itself is a list of bins. The fix is the contract, and since M3.1 the
+  contract is countable, so the lint, its data file and its fixtures move in
+  the same change or the check goes green for the wrong reason.
+- **Revisit if:** the model gets captions wrong in practice (then `longview`
+  fetches `og:image` and the caption host-side instead of the run emitting
+  them), or a private target with real CSS gets a host (then ruling 5).
+- **Used by:** daily-article-design-follow-up (M1.3), football-reporter
+  profile (`tasks/daily-article.md`, `AGENTS.md` § שתיקה, `config.yaml`
+  `longview.byline`), football-reporter-fixture-harness (M3.1 lint
+  `article-structure` / `article-image`)
+
+## D-022: M2.2 is closed as accepted by construction, with two revisit triggers (decided 2026-09-01)
+- **Category:** scope / sequencing (closes [D-015](#d-015-m22-is-deferred-until-after-m31-not-dropped-decided-2026-08-21); keeps [D-006](#d-006-scheduled-research-runs-post-from-the-primary-model-leg-or-not-at-all) as the standing rule)
+- **Decided:** `scheduled-task-model-leg-policy` (M2.2) is **closed**, not
+  built. The property it was written for — a scheduled research run posts from
+  the primary leg or not at all — has held by construction since the
+  2026-08-20 pin: every space carries a `model.active` row, the runtime turns
+  it into a one-element chain, a leg failure is a task error that retries and
+  reports to the admin and posts nothing, and the M3.2 ledger records the
+  model of every run. The backlog doc moves to `docs/ideas/` with its design
+  intact, re-labelled as what the same column is really worth: **per-task
+  model choice** (the article on one leg, verify runs on another — the Opus
+  A/B that was never started), with the safety property as a side effect.
+- **Revisit triggers (either reopens it, as a prerequisite, not an option):**
+  1. anyone clears a `model.active` pin, or a `/model reset` verb is built —
+     the fix the `model-switch-disables-fallback` bug asks for. That verb must
+     not ship before a scheduled-run guard exists; the bug doc now says so.
+  2. the ledger records a scheduled run on a non-primary leg.
+- **Alternatives considered:**
+  - *Build it as designed* (nullable `tasks.model_policy`, `primary_only`, a
+    `skipped` status, one truncation site). Sound, about a session of work,
+    and it buys nothing while the pin policy stands. Rejected for now, not on
+    merit.
+  - *Keep it deferred a third time.* Rejected: D-015's own revisit condition
+    (M3.1 in hand) has been met and the doc's open question — is this worth
+    its cost while every space is pinned — had gone unanswered since
+    2026-08-20. A story that cannot be scheduled or dropped is noise on the
+    roadmap.
+  - *Re-cut it as per-task model choice now.* Not rejected — parked as the
+    idea, to be planned on its own merits if the article A/B is wanted.
+- **Reasoning:** the pin was a deliberate choice ("Opus-only, no fallback,
+  all legs switchable", 2026-08-20), not an accident to be guarded against.
+  The cost argument for re-opening died with the digest-replay fix
+  (M2 checkpoint, 2026-08-31). What remained was a guarantee against a future
+  the owner has not asked for, and that future has a clear trigger. 300-plus
+  scheduled runs since the pin, zero on a non-primary leg.
+- **Used by:** football-reporter-profile roadmap (M2.2 row),
+  `docs/bugs/model-switch-disables-fallback.md` (the reset-verb constraint),
+  `docs/ideas/scheduled-task-model-leg-policy.md`