mercury-agent 0.24.1 → 0.24.2-beta.2

package/docs/goals/conversation-review/roadmap.md

@@ -0,0 +1,94 @@
+# Roadmap: Conversation Review
+
+**Goal**: [conversation-review](goal.md)
+**Last updated**: 2026-09-28
+
+## Milestones
+
+### Milestone 1: Daily judge on the local bot
+> On the local bot, a daily scan judges every exchange of the last 24 h and
+> writes a redacted report on the box. The owner gets a DM digest.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M1.1 | Read a window of exchanges per space from `state.db`, read-only | review-exchange-reader | — | backlog |
+| M1.2 | `redactIdentifiers` + fail-closed `assertNoIdentifiers` in core | redact-identifiers-with-gate | — | backlog |
+| M1.3 | `conversation-review` extension: daily job, batched no-tools judge, validated findings | conversation-review-daily-judge | M1.1 | blocked |
+| M1.4 | Report (`report.md` + `report.json`) on the box and the owner DM digest | conversation-review-report-and-digest | M1.2, M1.3 | blocked |
+
+**Checkpoint:** on the local bot, after deploying and enabling:
+
+1. In a test space, the owner provokes one bad answer: a question the bot answers
+   wrongly or refuses without reason. They trigger a scan with the extension's
+   run-now hook (or wait for 04:00).
+2. `~/whatsapp-bot/.../reviews/<date>-daily/report.md` exists and flags that
+   exchange with a kind, a scope, a target layer and the right message id.
+3. `grep -E` for a phone number, `@s.whatsapp.net`, `@lid` and the owner's name
+   in the report returns nothing.
+4. A DM arrives with the finding count, the top three findings and the report
+   path.
+5. The report's footer lists spaces and exchanges judged, anything skipped with
+   the reason, spawns, wall clock and cost. The journal shows the scan never
+   stalled a live reply.
+
+### Milestone 2: Both bots, into the repo
+> The Tagula bot runs the same scan on its release. `/f-review-intake` brings both
+> bots' reports into `docs/reviews/` and triages each finding against what is
+> already documented or landed before any of it becomes work (D-011).
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M2.1 | `scripts/review-intake.ts` + `/f-review-intake`: pull, re-gate, then verify → relate → decide per finding, owner approves, ledger | review-intake-to-repo | M1.4 | blocked |
+| M2.2 | Enable on Tagula: release, config, `include_clients` gate, tagula-agents runbook | conversation-review-on-tagula | M1.4 | blocked |
+
+**Checkpoint:** a daily report from each bot lands in `docs/reviews/`. The
+intake triage table then shows, each row citing the paths it matched:
+- at least one finding re-judged as fine and proposed as `reject`;
+- one proposed as `attach` to an existing open item;
+- one checked against a landed item, as `fixed-not-deployed` or `revisit`;
+- a finding raised again on a later day, under a different slug, reads
+  `duplicate` and follows the earlier decision.
+
+Only the rows the owner approved were applied, and every row is in
+`docs/reviews/ledger.json`.
+
+### Milestone 3: Weekly deep pass and a feedback loop
+> A weekly strong-model synthesis clusters recurring issues across spaces and
+> measures the daily judge's recall. The owner's verdicts on findings sharpen the
+> judge.
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| M3.1 | Weekly job: cluster 7 days of findings, space → global promotion, recall spot check | conversation-review-weekly-synthesis | M1.4 | blocked |
+| M3.2 | The M2.1 ledger feeds the judge: suppressed fingerprints and counter-examples from rejected findings go back to each bot; precision appears in the weekly report | review-verdict-feedback | M2.1, M3.1 | blocked |
+
+**Checkpoint:** the first weekly report lists at least one cluster that spans two
+or more spaces, and states the measured recall of the daily judge. After a week
+of intake verdicts, it also states precision, and a rejected false positive is
+not re-raised.
+
+### Future milestones (to be decomposed when M3 completes)
+- **Trace-aware analysis:** link a reply to its run trace (message id in the
+  trace name, the system prompt recorded) so a finding can cite the tool call
+  that failed. This builds on `trace-records-system-prompt`.
+- **Friction signals as extra evidence:** corrections, rephrasing, "you didn't
+  answer". Relates to `repeated-style-corrections-become-preferences`.
+- **Cross-bot clustering** at intake, and a view of trends over time.
+- **Proposal → rehearsal:** replay the flagged exchange against a proposed
+  profile change on the shadow bench (`rehearsal-bench`, `mercury smoke`) and
+  attach the before/after answer to the finding.
+- **Drafted fixes:** a finding becomes a pre-filled bug or idea doc, or a draft
+  `AGENTS.md` diff, still approved by a human.
+
+## Dependency Graph
+
+```
+M1.1 ─┐
+      ├→ M1.3 ─┐
+M1.2 ─┼────────┴→ M1.4 ─┬→ M2.1 ─┐
+      │                 ├→ M2.2  ├→ M3.2
+      │                 └→ M3.1 ─┘
+```
+
+M1.1 and M1.2 can run in parallel. M2.1, M2.2 and M3.1 can run in parallel once
+M1.4 lands.

package/docs/goals/rehearsal-bench/roadmap.md

@@ -48,7 +48,7 @@ matrix in §2 or edits it; `ops-preflight` refuses the exact command of
 | M1.1 | `shadow: boolean` config (`MERCURY_SHADOW`), absent = live: no adapter constructed, `consoleUrl` unset, dashboard banner + `shadow=1` on every log line; negative tests for each branch | shadow-mode-flag | — | **done** 2026-09-02 — [spec](../../archive/rehearsal/2026-09-02-shadow-mode-flag.md), PR #68 |
 | M1.2 | `mercury shadow snapshot`: `VACUUM INTO` + copy of `spaces/ global/ extensions/ model-capabilities.yaml` into `~/mercury-shadow/<ts>/`, `SNAPSHOT.json` (source commit, live HEAD, time), `current` symlink, shadow `.env` derived by a script (copy + override lines, never printed) and a `mercury.yaml` with `runtime.data_dir` and `server.port` rewritten; the `.env` writer emits `MERCURY_SHADOW=1` (only `true`/`1` enable the mode) and the shadow **refuses to start** when `runtime.data_dir` is not under `~/mercury-shadow/` — the flag alone protects people, not the live DB (M1.1 review, 2026-09-02) | shadow-snapshot | M1.1 | **shipped** 2026-09-03 — [spec](../../archive/rehearsal/2026-09-03-shadow-snapshot.md), PR #71, deployed 2026-09-03. `mercury shadow snapshot\|prune`, `src/ops/shadow-root.ts` + `src/ops/shadow-snapshot.ts`; the data-dir refusal closes the M1.1 residual |
 | M1.3 | `mercury shadow up|down|status|logs`: transient user unit via `systemd-run --user --unit mercury-shadow`, `--src` defaults to `~/mercury-src`; `down` prints the run cost from the shadow's `token_usage`; refuses `up` when the live `mercury` unit is not the only thing on 8787 or when the snapshot is older than `--max-age`. **From M1.2's plan:** the unit must set `HOME` (the data-dir guard refuses on an empty home), and `up` must record its snapshot path so `shadow prune` skips the running one. **Added 2026-09-03 (D-011, D-012):** (a) *prerequisite, first commit of the story* — every container the runner creates (agent, probes) carries a `mercury.instance=<id>` label derived from the data dir, and `cleanupOrphans` **always** filters on it — no id, no sweep; negative test deletes the filter and watches a foreign container get listed; (b) `--src` also accepts an installed package (`mercury-agent` under npm, run as root with `XDG_RUNTIME_DIR=/run/user/0`), so the same command works on a fleet box; (c) `up` refuses below `--min-free-mem` / `--min-free-disk`, while `task_runs` has an unfinished row, or while a cron is due within the run window; never builds an image (missing derived image → refuse, name the tag); binds 8788 to loopback | shadow-service | M1.2 | **done** 2026-09-07 — [spec](../../archive/rehearsal/2026-09-07-shadow-service.md). **Three corrections found in the code while building it:** the roadmap's "refuse while `task_runs` has an unfinished row" could not be written as specified (`finished_at` is NOT NULL and rows are written at completion, so the table never shows a run in progress) — it is a *running container* carrying the live instance id instead; "binds 8788 to loopback" was **dropped**, because under `runc` agent containers reach the host API over TCP at `host.docker.internal:<port>` and a loopback bind would break agent runs in the shadow only (a bind-host option is B-2, live and shadow alike); and the label had to cover a fourth container site, `preflight/probe-container.ts` |
-| M1.4 | `mercury shadow diff [--space <id>]`: live snapshot vs shadow now — `space_config` / `space_preferences` / `tasks` / `space_roles` / `mutes` rows with `updated_by` before→after, `messages` added (count + first lines), workspace tree by hash (`MEMORY.md`, `knowledge/**`, `AGENTS.md`), `extension_state` keys. Output is the report a migration rehearsal is judged on | shadow-diff | M1.2 | backlog |
+| M1.4 | `mercury shadow diff [--space <id>]`: live snapshot vs shadow now — `space_config` / `space_preferences` / `tasks` / `space_roles` / `mutes` rows with `updated_by` before→after, `messages` added (count + first lines), workspace tree by hash (`MEMORY.md`, `knowledge/**`, `AGENTS.md`), `extension_state` keys. Output is the report a migration rehearsal is judged on | shadow-diff | M1.2 | **done 2026-10-01** ([archive](../../archive/rehearsal/2026-10-01-shadow-diff.md)) — `diffShadow` in `src/ops/shadow-diff.ts` is the library call M3.2 / M4.1 reuse |
 | M1.5 | `longview` gains a `file` target and shadow mode forces it; the transcript shows the page path. `capability` route refuses non-`readOnly` actions in shadow mode | longview-file-target | M1.1 | backlog |
 | M1.3b | **Shadow admin list is chosen, never inherited** (added 2026-09-13, D-015, from bug `shadow-env-keys-does-not-override-mercury-admins`): `shadow snapshot --admins <id,…>` (default empty) is what `renderShadowEnv` writes as `MERCURY_ADMINS`; `SNAPSHOT.json.shadow.adminCount` records the count, `snapshot`/`up`/`status` print it (never the ids); `up` refuses a snapshot whose manifest records no count. Landed with the shadow-up hardening track (B1 of the 2026-09-12 bench-and-gate round), which also closed: the live project read from the unit's `WorkingDirectory` / `SNAPSHOT.json` (never cwd, disagreement refuses), the cron gate's third state (unknown denies, none allows), `mercury run` on `process.execPath` + the unit `PATH` composed from the live unit / `--path` (never the shell's), and the CLI tests' scoped user bus | shadow-admins | M1.3 | **done** 2026-09-13 — post-mortems under `docs/debug/{moderate,minor}/2026-09-1{2,3}-shadow-*` and `…-mercury-run-spawns-a-bare-bun-…` |
 | M1.3c | **Shadow-own model credential** (added 2026-09-15, from bug `shadow-snapshot-auth-json-goes-stale-when-the-live-bot-rotates-its-refresh-token`): the snapshot stops copying `global/auth.json`; `up` points `MERCURY_AUTH_PATH` at a shadow-only file the owner logs in to once (`mercury auth login` against the shadow root), so the shadow never holds the live refresh token — neither dies when the other rotates. D-016's principle ("a shadow answers to no live credential") extended from the API secrets to the model credential. The `Bun.serve` 10 s stream death on `/api/shadow/simulate` (bug `shadow-simulate-stream-dies-at-bun-serve-10s-idle-timeout`) — the other reason a bench run needs a person watching — is **not** this story's: it is fixed directly as plan `bugs-0915` S1 (corrected 2026-09-15), and the bug's shape (a) mitigation (`up` re-copies the live credential, `--dry-run` gates on it) ships as `bugs-0915` S4; this story owns shape (c) | shadow-own-credential | M1.3 | backlog |

package/docs/goals/space-links/decisions.md

@@ -0,0 +1,443 @@
+# Decisions: Space Links
+
+**Goal**: [space-links](goal.md)
+
+> Revised 2026-09-26 at checkpoint 1. The owner rejected the first draft's
+> closed capability catalogue: *"from a management space [we should be able] to
+> change any setting, read any message in any other space, and in general to
+> have any control we would have if we were an admin in the target space. The
+> target space context must not be affected at all by this, but the source space
+> context can fill with data from the target space when required (not always)."*
+> D-005 is rewritten, D-011 to D-014 are new, and D-003, D-004, D-006, D-008 and
+> D-009 are amended to match.
+>
+> Revised again 2026-09-26 (second round of checkpoint 1). The owner dropped
+> transitivity: *"should we give up transitivity? maybe it just complicates
+> things and can cause problems. any link should be easily visible and
+> editable."* D-003 is rewritten. The owner also asked to summarize a client
+> space's day, test the output it would give a client, and edit its profile,
+> all from one management space, with no conversation linked to each client and
+> no leak from management into the client. D-015 and D-016 are new.
+
+## D-001: No new stack; SQLite tables in `Db.migrate()`, Hono routes, `mrctl` subcommand
+- **Category:** tech-stack
+- **Decided:**
+  - Two new tables, `space_links` and `space_link_audit`, added to the
+    `CREATE TABLE IF NOT EXISTS` block in `src/storage/db.ts`.
+  - One route module, `src/core/routes/links.ts`, mounted at `/links`, plus one
+    change to the auth middleware in `src/core/api.ts` (D-011).
+  - One `mrctl links` subcommand group and one global `mrctl --space` flag.
+  - No new dependency.
+- **Alternatives considered:**
+  - Links as `space_config` keys: no directed edge, no audit, and a
+    per-space key cannot express the target side.
+  - A links extension, the way `overview` is an extension: it would put the
+    authorization boundary in extension code that any space can disable or
+    shadow.
+- **Reasoning:** Cross-space authorization is core. The `character` route
+  (b3c1841) and `mrctl model` (0bbb63a) are recent, working templates for exactly
+  this shape.
+- **Revisit if:** links need to span two Mercury instances. That would need an
+  inter-host transport, which is out of scope. Owner, 2026-09-28: "for now we
+  will only handle links between spaces on the same bot. The management space
+  will be on the Tagula bot. Links between bots on separate servers is deferred
+  for later." Parked as `docs/ideas/cross-bot-space-links.md`.
+- **Used by:** all stories
+
+## D-002: A link is one directed edge `holder → target`; "two-sided" is two edges
+- **Category:** architecture
+- **Decided:**
+  - Each `space_links` row is one directed edge. The **holder** side gains the
+    edge's access level over the **target** side.
+  - `mrctl links create A B --both` writes two rows, A→B and B→A, with the same
+    level, in one transaction.
+  - Asymmetric pairs are two separate `create` calls.
+  - The optional conversation filter (`target_conversation_id`) narrows the
+    **target** end only.
+- **Alternatives considered:**
+  - One row with a `bidirectional` flag: cannot express the asymmetric case
+    (management administers a client space; the client sees nothing back).
+  - `none | a→b | b→a | both` per axis on one row, as the idea doc proposed:
+    every check would need to know which end is "a".
+- **Reasoning:**
+  - Every check becomes the same question: is there an edge from the holder to
+    the target (or to `*`), and at what level?
+  - The direction words are fixed as **holder** and **target**, never "from/to"
+    or "a/b". Data flows target→holder; access points holder→target.
+- **Revisit if:** a real case needs one revoke to take out both halves of a pair
+  atomically often enough to warrant a `pair_id`.
+- **Used by:** all stories
+
+## D-003: Links are not transitive; only a direct edge (or `*`) grants access
+- **Category:** architecture
+- **Decided:**
+  - The holder reaches a target only through an active edge
+    `holder → target` or `holder → *`. B's own links give A nothing.
+  - When several direct edges match (a `*` edge and a specific one, or a
+    filtered and an unfiltered one), the **strongest** level wins.
+  - Computed on every call. Never materialized, never cached.
+- **Alternatives considered:**
+  - Transitive, weakest edge on a path wins, best path wins (this decision's
+    first version, from the intake answer "links are transitive"). The owner
+    withdrew it on 2026-09-26: "maybe it just complicates things and can cause
+    problems. any link should be easily visible and editable."
+  - A per-edge `transitive` flag. It keeps every problem of transitivity for
+    the edges that set it.
+- **Reasoning:**
+  - Every access that exists is one row in `mrctl links list`, and changing or
+    revoking it is one command on that row. With transitivity, an access could
+    exist on no row at all, and a link created for one purpose (X→mgmt) could
+    silently hand X the reach of mgmt's wildcard.
+  - The owner's case needs no chain: one management space with a `*` edge, or
+    one edge per client.
+  - The resolver becomes one SELECT with no loop, no hop cap and no path to
+    audit.
+- **Revisit if:** a real case needs A to reach C through B, and writing the
+  A→C row is worse than what transitivity would cost. Nothing in the goal needs
+  it today.
+- **Used by:** space-link-graph-and-grant-resolver and every story that checks a
+  grant
+
+## D-004: One resolver, literal arguments; the caller's own role in the holder still bounds them
+- **Category:** pattern
+- **Decided:**
+  - Every link-mediated request goes through
+    `resolveLinkGrant(db, holderSpaceId, targetSpaceId)` in
+    `src/core/space-links.ts`, called from exactly one place: the act-as step of
+    the auth middleware (D-011). No route calls it on its own.
+  - The holder is always `auth.spaceId` from the verified caller token. The
+    target is the explicit `x-mercury-act-as` value.
+  - The caller must hold `links.act` in the **holder** (default: admin). A caller
+    who is not an admin (or `system`) in the holder is capped at `read` in the
+    target, whatever the link says.
+- **Alternatives considered:**
+  - A parameterised `checkPerm(c, perm, targetSpace)` sprinkled per route. Every
+    route would need its own cross-space branch, and they would drift.
+- **Reasoning:**
+  - One implementation, one call site: read, control, send and files cannot
+    disagree about what a link allows.
+  - A link never turns a member of the management space into an admin of a
+    client space.
+- **Revisit if:** never, without a security review.
+- **Used by:** all stories
+
+## D-005: A link carries an access level: `read` or `admin`
+- **Category:** scope
+- **Decided:**
+  - Each edge carries one level. Absent, unknown or unparsable denies.
+
+    | Level | In the target, the holder may… |
+    |---|---|
+    | `read` | Everything an admin can **see** and nothing they can change: search messages, list conversations and tasks, get config, prefs, roles, permissions, mutes and the model chain, and (M2) list and read workspace files, including `MEMORY.md` and the knowledge vault. Enforced per route: each `ACT_AS_ROUTES` entry is marked `read` or `admin`, and a `read` grant reaches only the `read` entries (D-011). |
+    | `admin` | Exactly what the target's `admin` role may do (`getRolePermissions(db, target, "admin")`): prefs, config, tasks, roles and permissions, mutes, model switch, rename, stop, compact, clear, send, and (M2) write workspace files and run extension actions. |
+
+  - What stays out, and why:
+    - **The Bot Character.** It is not per-space. A global admin already edits it
+      from any space with `mrctl character`, so there is nothing for a link to
+      grant.
+    - **Creating or changing links.** Global admin only (D-006). An `admin`
+      link into B does not let the holder link B to anything.
+    - **Anything global-admin-only** (`/character`, `/broadcast`, the `?all`
+      views). These check `callerId`, not the space, so a link cannot reach them.
+- **Alternatives considered:**
+  - The first draft's closed nine-capability catalogue (`read.messages`,
+    `control.prefs`, …). Rejected by the owner on 2026-09-26: it left out roles,
+    memory and knowledge, and made "act as an admin there" into nine separate
+    grants plus a per-route implementation of each.
+  - A link naming a target role (`--as member`). Role names and permissions are
+    per-space and editable, so the minimum rule of D-003 would have to compare
+    permission sets across spaces. Two fixed levels keep the rule total.
+- **Reasoning:** The owner's requirement is literally "whatever an admin of the
+  target could do". Reusing the target's own admin permission set means there is
+  no second list to keep in step with the permission system. `read` exists
+  because peer spaces (the 2026-09-24 TV-shortlist case) need to look without
+  being able to touch.
+- **Revisit if:** a real case needs a middle level (for example "may change
+  prefs but not roles"). A third level slots between the two; it never widens
+  either.
+- **Used by:** all stories
+
+## D-006: Only a global admin creates, updates or revokes; target-side admins can always see inbound reach
+- **Category:** architecture
+- **Decided:**
+  - `create`, `update` and `revoke` are gated on `isGlobalAdmin(callerId)`, the
+    same as `routes/character.ts`.
+  - `list`, `inspect` and `audit` need the new `links.list` permission (default:
+    admin) in the caller's space. They show:
+    - edges where the caller's space is holder or target;
+    - the **inbound** reach (every space with a direct or `*` edge to this one,
+      and at what level) and the outbound reach.
+  - Acting across a link needs `links.act` (default: admin) in the holder (D-004).
+- **Alternatives considered:**
+  - A space admin on both ends consents. Rejected by the owner on 2026-09-26.
+- **Reasoning:**
+  - Creating a link grants access to someone else's conversations.
+  - Asymmetric visibility is acceptable; unaccountable visibility is not.
+- **Revisit if:** customer-operated deployments need a space admin to create
+  links inside their own tenancy.
+- **Used by:** mrctl-links-admin-commands, act-as-linked-space
+
+## D-007: Disclosure is recorded, not enforced
+- **Category:** scope
+- **Decided:**
+  - `space_links.disclosure` is a free-text field set at create or update with
+    `--disclosure "<how and when the target side was told>"`.
+  - It is shown by `list` and `inspect`. Nothing is posted to the target side
+    automatically (which D-012 would forbid anyway).
+- **Alternatives considered:**
+  - A required automatic notice.
+  - Leaving disclosure out entirely.
+- **Reasoning:** Owner decision, 2026-09-26. Recording it keeps the question
+  visible without deciding it in code.
+- **Revisit if:** a customer deployment or a legal review requires notice. The
+  field is then the natural gate.
+- **Used by:** space-link-graph-and-grant-resolver, mrctl-links-admin-commands
+
+## D-008: Every link-mediated request is audited in its own table
+- **Category:** architecture
+- **Decided:**
+  - `space_link_audit` gets one row per:
+    - `create`, `update`, `revoke` of a link;
+    - act-as request (D-011), successful or refused after the grant check, with
+      method, route, a redacted body summary, response status, and the id of
+      the edge that granted it.
+  - Rows survive `revoke` and `deleteSpace`.
+  - The audit table is host bookkeeping. It is never part of any space's prompt
+    (D-012).
+- **Alternatives considered:**
+  - Logger lines only. The journal rotates and cannot be queried by the target's
+    admin.
+  - Per-route before/after capture. Twelve route modules would each need it; the
+    request body plus status is uniform and answers "who did what". Before/after
+    is added only where the route already returns it.
+- **Reasoning:** The target's admin must be able to answer "who read or changed
+  what in my space". Today there is no config-change audit anywhere.
+- **Revisit if:** audit volume from read requests becomes material. In that case,
+  aggregate reads per run.
+- **Used by:** all stories
+
+## D-009: `overview` stays as it is for now; it becomes a wildcard `read` link later
+- **Category:** scope
+- **Decided:**
+  - The `overview` extension keeps its management-space gate during this goal.
+  - With D-013, "management holds `read` over `*`" is exactly what `overview`
+    does. Porting it is a follow-up after M1 is live, not part of this goal.
+- **Reasoning:** Migrating a working, live-verified capability inside the same
+  goal is risk without payoff.
+- **Revisit if:** M1 ships. File the port as an idea then.
+- **Used by:** —
+
+## D-010: Naming: "space link", table `space_links`, verb group `links`
+- **Category:** pattern
+- **Decided:**
+  - In prose the new concept is always a **space link**.
+  - Code uses `SpaceLink` / `space_links` / `mrctl links` / `mrctl --space`.
+  - The existing "conversation linked to a space" (`conversations.space_id`,
+    `/spaces link`) is unchanged.
+- **Alternatives considered:**
+  - "Bridge" is taken by `src/bridges/`. "Relation" is a word nobody uses when
+    they talk about the feature.
+- **Reasoning:** The owner and every idea doc already say "link". The collision
+  is managed by always qualifying the word.
+- **Revisit if:** users confuse `/spaces link` with `mrctl links` in practice.
+- **Used by:** all stories
+
+## D-011: Acting in a linked space is one middleware step, not a route per feature
+- **Category:** architecture
+- **Decided:**
+  - `mrctl --space <target> <any command>` sends `x-mercury-act-as: <target>`.
+  - The auth middleware in `src/core/api.ts`, after it has verified the caller
+    in the holder, runs the act-as step once:
+    1. `links.act` in the holder, or 403;
+    2. the target exists (`getSpace`, never `ensureSpace`), else the same 403;
+    3. the method and route are on the `ACT_AS_ROUTES` allowlist, each entry
+       marked `read` or `admin`, else 400;
+    4. `resolveLinkGrant(holder, target)` grants a level, else 403; a `read`
+       grant on an entry marked `admin` is also 403;
+    5. the auth context becomes `{ callerId, spaceId: target, role, via }`,
+       where `role` is always `admin` and `via` carries the holder, the level
+       and the granting edge id;
+    6. one audit row is written after the handler returns.
+  - Every existing route (`/messages`, `/prefs`, `/config`, `/tasks`, `/roles`,
+    `/permissions`, `/mutes`, `/model`, `/conversations`, `/spaces/current`,
+    `/control`, `/send`) then works against the target **unchanged**, because
+    they already read `auth.spaceId` and `checkPerm`.
+- **Alternatives considered:**
+  - A `links read`, `links prefs`, … verb per capability (the first draft). Each
+    one re-implements an existing route and they drift.
+- **Reasoning:** "Anything an admin of the target could do" is the existing API
+  surface evaluated in the target. Swapping the space once, at the boundary,
+  gets all of it with one check.
+- **Revisit if:** a route needs to know it is being called across a link beyond
+  what `auth.via` tells it.
+- **Used by:** act-as-linked-space, link-workspace-files, link-extension-actions
+
+## D-012: The target's context is never touched by a link; the holder's fills only on demand
+- **Category:** architecture
+- **Decided:**
+  - **Target side.** A link, and any read through it, leaves the target
+    byte-identical: no prompt block, no notice, no row in `messages` or `members`,
+    no container spawned. The act-as step never calls `resolveRole` on the
+    target, because that upserts a member row.
+  - What *does* change the target is only an explicit admin action the holder
+    asked for (a preference set, a task created, a message sent, a session
+    cleared). That is the point of `admin`, and each is audited.
+  - **Holder side.** Nothing about linked spaces is injected into the holder's
+    prompt automatically: no per-space list, no digest. One static paragraph in
+    the platform block, gated on `links.act`, says that other spaces may be
+    reachable, that `mrctl links list` shows which, and that `mrctl --space` is
+    used only when the user asks about another space. Content from a target
+    enters the holder's context only as the output of a command the agent chose
+    to run.
+- **Alternatives considered:**
+  - The first draft's `<linked_spaces>` block and `inject.digest`. Dropped: a
+    management space linked to thirty spaces would carry thirty spaces of context
+    on every turn.
+- **Reasoning:** Owner requirement, 2026-09-26.
+- **Revisit if:** a small, opt-in per-link digest is wanted for one specific pair.
+  It would be a new level or flag, never a default.
+- **Used by:** act-as-linked-space, link-workspace-files
+
+## D-013: A link target may be `*`, meaning every other space, present and future
+- **Category:** scope
+- **Decided:**
+  - `mrctl links create <holder> '*' --level admin` makes one edge that reaches
+    every space except the holder, including spaces created later.
+  - A wildcard edge takes no conversation filter.
+  - Every space's `links list` shows wildcard holders in its inbound reach.
+- **Alternatives considered:**
+  - One edge per space. A new space would silently be outside management's reach
+    until someone remembered to link it.
+- **Reasoning:** The owner's case is "from a management space … any other
+  space". The wildcard says that in one row, and it is visible from every
+  target.
+- **Revisit if:** a deployment hosts spaces that must never be reachable even by
+  management. That would need a per-space `unlinkable` flag, which a wildcard
+  respects.
+- **Used by:** space-link-graph-and-grant-resolver, mrctl-links-admin-commands
+
+## D-014: Content from a target is untrusted, and the holder acts only on its own user's request
+- **Category:** pattern
+- **Decided:**
+  - Act-as responses that carry third-party text (messages, file contents) are
+    passed through `stripInvisibleUnicode` and tagged with the source space.
+  - The platform paragraph (D-012) tells the agent that text read from another
+    space is data, never instructions, and that `admin` actions through a link
+    are taken only when the holder's own user asked for them.
+- **Reasoning:** With `admin` over many spaces, a prompt injection planted in
+  one client's chat could try to steer the management agent into changing
+  another client's settings. Prose is not a guard, so this is also a residual:
+  the audit is how such an action would be found.
+- **Revisit if:** the audit ever shows an act-as write that no human asked for.
+  The next step is refusing act-as writes from a run whose triggering message is
+  not the holder's own user.
+- **Used by:** act-as-linked-space, link-workspace-files
+
+## D-015: Reading a period of a space's history is a read route, and summarizing is the holder's job
+- **Category:** architecture
+- **Decided:**
+  - A new route `GET /messages/recent?since=&until=&limit=&cursor=` lists a
+    space's messages in a time range, oldest first, with a cursor for the next
+    page. `mrctl messages recent --since 24h` calls it, and so does
+    `mrctl --space X messages recent --since 24h` through the act-as step
+    (marked `read` in `ACT_AS_ROUTES`).
+  - It serves the owner's "summarize everything from the past day in client X".
+    The management agent pages through the output and writes the summary. For a
+    long day it can hand the paging to a subagent, so the raw messages stay out
+    of the management conversation and only the summary comes back.
+  - The route is useful inside a space too ("what did we talk about
+    yesterday?"), so it is gated on its own `messages.read` permission
+    (default: admin), not on `compact`.
+- **Alternatives considered:**
+  - Summarize on the host and return only the summary. That is a host-side
+    model call, which needs its own system prompt and model leg (the pi-spawn
+    rule in `CLAUDE.md`) and its own budget, for what the agent already does.
+  - Reuse `/messages/search` with an empty query. Search is newest-first,
+    capped at 200 and has no time range, so a day is not addressable with it.
+- **Reasoning:** One read primitive the agent can page through covers "the past
+  day", "last week" and "since the last summary", and it adds nothing to the
+  holder's context until it is called (D-012).
+- **Revisit if:** summaries of very busy spaces keep exhausting the holder's
+  context even with a subagent. A host-side digest per space per day would then
+  be the next step.
+- **Used by:** messages-recent-range, act-as-linked-space
+
+## D-016: Asking as another space is one turn of that space's agent on a throwaway copy of its state
+- **Category:** architecture
+- **Decided:**
+  - `mrctl --space X ask "<message>" [--as member|admin]` runs one agent
+    turn **as space X would run it**: X's `AGENTS.md`, preferences, memory,
+    character, model, history and tools. The reply comes back to the holder as
+    command output. No conversation of X is involved and nothing is sent to
+    anyone.
+  - It serves two requests with one mechanism:
+    - **testing**: "how would X answer 'what are your opening hours?'";
+    - **delegating**: "act as if you're in X and search for leads for a story
+      about aliens". The turn really runs X's search with X's instructions and
+      tools, so the answer is the one X's bot would give, not the management
+      agent's imitation of it.
+  - The management agent passes the reply on as it came back, labelled with the
+    space. It does not rewrite it in its own voice (D-017).
+  - Read-only tools (web search, fetch, reading X's files) work in the turn.
+    Only writes and sends are held back, below.
+  - The turn runs on a **throwaway copy**: a temporary copy of X's workspace
+    and session, deleted after the turn. X's `messages`, session, `MEMORY.md`,
+    tasks and preferences are unchanged afterwards, whatever the turn tried.
+  - Inside the turn every `mrctl` write and every outbound send is
+    refused, and the refusals are listed in the output ("would have
+    sent", "would have set"). Extensions that act on an outside account (gws,
+    yahoo-mail, tradestation) get no credentials in the turn.
+  - The only input from the management space is the message itself. The
+    turn never sees the management conversation, and the management
+    agent sees only the reply and the refusal list.
+  - Nothing is kept in X by default: leads found by a delegated search are not
+    added to X's memory or files. Whether a `--keep` option should let the
+    turn's results persist in X is open (it would put the request into X's
+    record, which D-012 otherwise forbids).
+  - `ask` is marked `admin` in `ACT_AS_ROUTES`. It changes nothing, but it
+    runs X's agent and spends tokens on X's model leg.
+- **Alternatives considered:**
+  - A test conversation linked to each client space. That is what the owner
+    asked to avoid, and a turn there does write to X's history and session.
+  - The rehearsal-bench shadow (`docs/goals/rehearsal-bench/`). It has full
+    fidelity (real ingress, triggers, a copy of the whole data dir), but it is
+    a second service started by an operator from a shell. It stays the tool for
+    testing a deploy or a trigger. `ask` is the everyday tool from chat.
+  - The management agent imitating X after reading X's `AGENTS.md`. It would
+    run on management's model, prompt and tools, so the answer would not be
+    X's, which is what the owner asked for ("genuinely give a response as if
+    the bot in that space was asked it").
+- **Reasoning:** "Test the output it would give a client" and "act as if you're
+  in X" both need X's real context and tools and must leave X untouched. A copy
+  that is thrown away gives both, and the refusals make the "would have done"
+  side visible without doing it.
+- **Revisit if:** an `ask` reply differs from the live reply to the same
+  message in a way that matters. The likely cause is ingress (triggers,
+  mentions), and the answer is the shadow, not a more faithful `ask`.
+- **Used by:** link-ask-as-space
+
+## D-017: The owner speaks plain language; the agent picks the command
+- **Category:** pattern
+- **Decided:**
+  - `mrctl --space`, `messages recent` and `ask` are the agent's tools, not the
+    owner's interface. The owner says "what leads did you find in Phishkin's
+    space in the last 48 hours?" or "act as if you're in Phishkin's space and
+    …", and the agent chooses the command.
+  - The routing rules live in the one platform paragraph gated on `links.act`
+    (D-012): resolve a named space with `mrctl links list` (tolerating
+    misspellings, asking when two match); answer "what happened in X" from X's
+    record, stating the space and period covered; answer "act as X" with
+    `ask` and pass the reply on unchanged.
+  - Every milestone checkpoint is run with plain-language messages only, and
+    the trace is read to confirm which command the agent chose.
+- **Alternatives considered:**
+  - A chat slash command per operation. The owner asked for plain language.
+  - Injecting the list of reachable spaces into the prompt so names resolve
+    without a call. Rejected by D-012: it grows with every linked space.
+- **Reasoning:** An accurate answer to "what did X find" depends on reading X's
+  record, not on the management agent's recollection; the paragraph tells it
+  where each kind of record lives.
+- **Revisit if:** live checks show the agent answering about another space
+  without running a command (guessing), or picking the wrong space. The next
+  step is a skill with worked examples.
+- **Used by:** act-as-linked-space, messages-recent-range, link-ask-as-space