mercury-agent 0.16.0 → 0.16.2

package/docs/goals/whatsapp-bot-hardening/archive/handoff-2026-08-09.md

@@ -0,0 +1,588 @@
+> **ARCHIVED 2026-08-10 — fully executed. Do not plan from this file.**
+>
+> Every fix in §4 shipped (8 stories, 13 commits on
+> `fix/whatsapp-context-identity-and-docs`); §3's switchover is live; §5 steps
+> 1–5 are done; all of §6's open decisions were taken (see `decisions.md`
+> D-001…D-013). Kept as the **investigation record** — the root causes here were
+> verified against running code and live data, and the file:line references are
+> still the best map of *why* each fix looks the way it does.
+>
+> Two things in it are now **wrong**, corrected elsewhere:
+> - §1's tree table says the live bot is the npm-installed 0.8.12. It is not —
+>   the service has run from `~/mercury-src` since 2026-08-10 (D-001).
+> - §1 says `mercury auth status` is cwd-sensitive. Fixed 2026-08-10; see the
+>   roadmap's "The cwd trap" section.
+>
+> Live successor documents:
+> - `docs/goals/whatsapp-bot-hardening/roadmap.md` — status of everything here
+> - `docs/goals/whatsapp-bot-hardening/open-threads.md` — what is still open
+> - `docs/goals/whatsapp-bot-hardening/archive/*.md` — the 8 per-story specs,
+>   with retrospectives
+
+# Mercury WhatsApp Bot — Bug Fix & Feature Handoff
+
+**Written:** 2026-08-09 · **For:** a fresh Claude Code session picking up this work
+**Branch:** `fix/whatsapp-context-identity-and-docs` in `~/mercury-src` (WSL)
+**Status:** investigation complete, pinchtab commits merged, **no code fixes written yet**
+
+Read this top to bottom before touching anything. Every root cause below was verified
+against running code and live data — file:line references are to the **v0.9.0 tree in
+`~/mercury-src`**, not the currently-running build.
+
+---
+
+## 1. Environment — read this first
+
+There are **three different source trees** and they are not the same. Confusing them
+will waste your time.
+
+| Tree | Version | Role |
+|---|---|---|
+| `~/.nvm/versions/node/v24.19.0/lib/node_modules/mercury-agent` | 0.8.12 | **What is running right now** (systemd `mercury`) |
+| `~/mercury-src` | v0.9.0 + our branch | **The working repo — do all work here** |
+| `D:\Projects\whatsapp-bot\mercury` | 17c92c6 | Stale Windows clone. Will drift. Do not edit. |
+
+The live bot runs in **WSL Ubuntu**, project dir `~/whatsapp-bot` (systemd user unit
+`mercury`). This Claude session runs on **Windows**.
+
+**Operating rules (learned the hard way):**
+
+- Run commands via `wsl.exe -e bash -lc '<cmd>'` and pipe through `tr -d '\0'` —
+  output is otherwise NUL-interleaved and unreadable.
+- **Fix PATH on every invocation.** Even `bash -lc` resolves `npm`/`bun` to the
+  *Windows* binaries via PATH interop. Prefix with:
+  `export PATH=$HOME/.nvm/versions/node/v24.19.0/bin:$HOME/.bun/bin:$PATH`
+- **Edit files via the UNC path** `\\wsl.localhost\Ubuntu\home\guysaha\mercury-src\...`
+  with Read/Edit/Write. This works and beats heredocs.
+- **Never Read `~/whatsapp-bot/.env`** (live API keys). Edit it with `awk`/`sed` inside WSL.
+- `MERCURY_*` env vars in `.env` **silently override** `mercury.yaml` (`config.ts`).
+  Before debugging any config behaviour, dump the *effective* value, don't read the YAML.
+  Currently no media/log overrides are set, so YAML edits will take effect.
+- `mercury auth status` is **cwd-sensitive** — it reports "not logged in" unless you
+  `cd ~/whatsapp-bot` first.
+- Restart with `systemctl --user restart mercury`. **Never** run `mercury run` directly,
+  **never** kill by port (repo CLAUDE.md).
+- Which model actually served is only knowable from the DB, never the reply:
+  `SELECT model, provider FROM token_usage ORDER BY id DESC LIMIT 1`. No `sqlite3`
+  installed — use `bun -e` with `bun:sqlite`.
+
+---
+
+## 2. Current repo state
+
+Branch `fix/whatsapp-context-identity-and-docs`, based on `70a5ce3` (v0.9.0):
+
+```
+b12d7c0  refactor(web-browser): probe the pinchtab bridge port with curl
+1fee658  fix(web-browser): start the pinchtab daemon with the "server" subcommand
+7ae56c7  fix(container): disable core dumps in agent containers
+bfe5a33  fix(web-browser): bake the pinchtab domain allowlist into the agent image
+70a5ce3  (origin/main, v0.9.0)
+```
+
+**Nothing has been pushed.** Git identity is set *repo-locally* to
+`saharw01 <Saharw01@gmail.com>` to match existing commits.
+
+**Uncommitted, and it must go in the PR:** `~/mercury-src/.dockerignore` has a local
+edit adding `!examples/extensions` + `!examples/extensions/**`. This is a real build
+fix — `.dockerignore:15` ignores `examples/`, but `container/Dockerfile:118` does
+`COPY examples/extensions/ /tmp/examples-extensions/`, which copies nothing without the
+negation. **This exists in no commit on any branch or remote.** Commit it.
+
+### Why the pinchtab commits were merged
+
+All four were verified necessary (or harmless hardening) by testing the real binary,
+**not** by trusting commit messages:
+
+- `pinchtab server` — **real bug.** `pinchtab --help` documents `server` as "Starts the
+  full server"; bare `pinchtab` prints a banner and **exits 0**. The old
+  `nohup pinchtab &` never started a daemon.
+- `allowedDomains "*"` — **real bug.** pinchtab's TRUST.md documents the navigation
+  default as a "Local-only allowlist"; `idpi_domain_blocked` exists in the binary;
+  `idpi.enabled/strictMode/scanContent/wrapContent` are all `true` by default. Every
+  public URL was refused. ⚠️ **Security note for the PR:** `"*"` removes the domain
+  allowlist entirely. The injection guard genuinely stays on (verified), but this is a
+  deliberate widening of attack surface and should be described as such, not as a plain bugfix.
+- `--ulimit core=0` — **justified.** WSL2 `/proc/sys/kernel/core_pattern` is literally
+  `core` with no handler pipe, so segfaults dump into the CWD = bind-mounted workspace.
+  The "~300 MB per dump" figure is the author's observation, **not independently verified**.
+- curl port probe — **hardening, not a live fix.** Correctly labeled `refactor:`. The
+  branch's comment is honest that pi runs bash today so `/dev/tcp` works.
+
+**Critical:** all four were already hand-patched into the *running* installed package and
+the deployed extension. Switching the service to `~/mercury-src` **without** them would
+have silently regressed the browser extension.
+
+---
+
+## 3. Deployment switchover (do this before testing)
+
+Decision already made: **run the bot from the git checkout**, so fixes are
+version-controlled, testing is edit→restart, and `npm i -g` can't revert them.
+
+```bash
+# 1. Backup — a restart checkpoints the ~4 MB WAL, so grab all three files
+mkdir -p ~/mercury-backup-$(date +%s) && cp ~/whatsapp-bot/.mercury/state.db{,-wal,-shm} ~/mercury-backup-*/
+
+# 2. Deps + gate
+cd ~/mercury-src && bun install && bun run check
+
+# 3. Repoint the CLI, reinstall the service the documented way
+npm link                                    # makes `mercury` resolve to ~/mercury-src
+cd ~/whatsapp-bot && mercury service install --user
+
+# 4. Re-apply Restart=always (generator writes on-failure), then restart
+```
+
+**Gotchas:**
+- `service install` bakes `Environment=PATH=` from the install shell. Set PATH explicitly
+  or the unit won't find bun/node.
+- It also **reverts `Restart=always` → `Restart=on-failure`**. The live unit was
+  hand-changed to `always`; re-apply it after install.
+- A **db.ts migration runs on first 0.9.0 start** against the existing `state.db`.
+  That is the reason for step 1, not superstition.
+- The derived Docker image may rebuild (cached by content hash, version changed). It
+  builds in the background and doesn't block startup, but early replies may be slow.
+- **Leave the npm-installed 0.8.12 in place** as rollback: `npm unlink` + restore the
+  old unit gets you back in under a minute.
+
+---
+
+## 4. The fixes
+
+### Bug 1 — Ambient mode is dead code (highest impact)
+
+**Symptom:** the bot cannot see any group message it isn't tagged in.
+
+**Root cause.** `src/core/handler.ts:237-240`:
+
+```ts
+const shouldProcess = triggerResult.matched || (ingress.isReplyToBot && !isDM);
+if (!shouldProcess && !isCommand) return;   // ← returns here
+```
+
+The ambient-write branch lives in `src/core/runtime.ts:591-612`, inside `handleRawInput`,
+which is only reached via `processIngress` — **after** that early return. `ambient.enabled`
+defaults to true and works as designed; it gates code nothing reaches.
+
+**Evidence.** Across the whole DB there are exactly **2** ambient rows, both in space `19`,
+both `סהר ויצמן: /spaces…`. That's the tell: `isCommand` is the sole bypass, so only stray
+`/`-prefixed messages leak through. `greece2026` has **0**.
+`handler.ts` is byte-identical on origin/main — **upstream has not fixed this.**
+
+**Fix.**
+1. Extract `runtime.ts:591-612` into a public `recordAmbient(ingress: IngressMessage)` on
+   `MercuryCoreRuntime` (keep the group-only + `ambient.enabled` + non-DM guards).
+2. In `handler.ts:240`, replace the bare return:
+   ```ts
+   if (!shouldProcess && !isCommand) {
+     core.recordAmbient(ingress);
+     return;
+   }
+   ```
+   `ingress` is already built at line 221, so the data is in hand.
+3. **Cap the ambient context budget.** `db.ts:1047 getRecentTurns` fetches `turnCount * 5`
+   rows (`db.ts:1068`) and lets ambient share that window. Once ambient actually flows,
+   it will crowd out real turns. Give ambient its own bounded query — do **not** ship
+   step 2 without this.
+4. **Add an ambient retention TTL** to `storage-cleanup.ts`. Every group message is now a row.
+
+**Known side effect (pre-existing, not caused by this fix):** `bridge.normalize` runs at
+`handler.ts:221`, *before* the gate — so media from untriggered group messages is already
+being downloaded and then discarded. Fixing bug 1 doesn't add that cost.
+
+**Tests.**
+- Unit: `recordAmbient` writes for a group + `ambient.enabled` unset/true; writes nothing
+  for a DM; writes nothing when `ambient.enabled=false`.
+- Unit: handler calls `recordAmbient` exactly once for a non-triggered group message, and
+  **not** for a triggered one (no double-write).
+- Unit: ambient context query returns at most N rows and does not starve user/assistant turns.
+- Manual: send 3 untagged messages in a test group → assert 3 new `role='ambient'` rows;
+  then tag the bot and ask what was just said.
+
+---
+
+### Bug 2 — Sender misidentification + member memory
+
+**Symptom:** the bot attributes past messages to the wrong person.
+
+**Root cause A (primary).** Stored messages carry **no author**. `runtime.ts:1573` writes
+`addMessage(spaceId, "user", finalPrompt, …)`, and the `messages` table has no author
+column (`id, space_id, role, content, attachments, run_meta, reply_to_id, created_at,
+updated_at`). At render time `agent/container-entry.ts:598` emits `<user>…</user>` with no
+name. The **only** identity anywhere in the prompt is `<caller id=… name=… role=…/>` at
+`container-entry.ts:634` — the *current* speaker.
+
+So in a group the model sees a flat run of unattributed turns plus one name. Attributing
+the whole history to that person is the only reading the prompt supports. This is not a
+model glitch.
+
+**Root cause B.** Quoted-reply senders resolve to raw LIDs. `buildReplyContext`
+(`adapters/whatsapp.ts:82`) looks names up in `pushNames` (`whatsapp.ts:169`) — an
+**in-memory** map, empty after every restart — and canonicalizes sync-only (no async LID
+lookup). Real row currently in the greece2026 DB:
+`<reply_to name="136043810578453" jid="136043810578453@lid" …>`
+
+**Good news:** the identity data already exists and is clean. `space_roles.display_name`
+is fully populated, correctly keyed by canonical phone JID (26 members), e.g.
+`whatsapp:972500000000@s.whatsapp.net → "Member Name"`. Nothing uses it for context.
+
+**Fix.**
+1. Migration: add `author_id` / `author_name` to `messages`; populate at `addMessage`.
+2. Render `<user name="…" id="…">` in `buildHistoryXml`; put the author on ambient entries
+   too (ambient already prefixes `Name: text` at `runtime.ts:604` — promote it to an attribute).
+3. Back `pushNames` with the DB: seed from `space_roles.display_name` at startup, write
+   through per message. Fixes `<reply_to>` across restarts.
+4. Use the **async** `canonicalizeJid` for quoted participants so unknown LIDs resolve.
+
+**Member memory feature.** Build on the existing episodic plumbing rather than a new
+subsystem: per-space `knowledge/members/<id>.md`, injected like `<active_episodes>`
+(`container-entry.ts:513`), written by the agent with the `write` tool it already has.
+Pair it with a `<members>` block generated from `space_roles` — identity stays **hard**
+(id → name from the DB, not guessable), characteristics stay **soft** (accumulating notes).
+No schema migration for the notes half; naturally per-space.
+
+**Tests.**
+- Migration: runs idempotently on the existing DB; existing rows get NULL authors and
+  still render.
+- Unit: history XML for messages from two different users renders two distinct names.
+- Unit: `buildReplyContext` resolves a known LID via the alias store + `display_name`,
+  and degrades gracefully to the bare jid when unknown.
+- Unit: `pushNames` survives a simulated restart (seeded from DB).
+- Manual: two people talk in a group, then a third asks "who said X?" — verify correct attribution.
+
+---
+
+### Bug 3 — 50 MB docx rejected, silently
+
+**Symptom:** a large docx sent to the greece space was never readable; Google Drive worked.
+
+**Root cause.** `mercury.yaml:74` sets `max_size_mb: 10`. `adapters/whatsapp-media.ts:165`
+(and `:284` for the quoted-reply retry) skips anything larger **before** downloading.
+
+**Evidence (host journal, 2026-08-09):**
+```
+15:43:57 [WARN] Skipping large media file  type=document sizeBytes=51585024 maxBytes=10485760
+15:51:53 [WARN] Skipping large media file  type=document sizeBytes=58117658 maxBytes=10485760
+```
+Seven attempts, all rejected — including the reply path, which is why replying to the file
+didn't help.
+
+**The worse half is the silence.** `runtime.ts` only surfaces "could not use your
+attachment" when the message has **no text at all**. The file had a caption, so the agent
+was told nothing and invented a wrong explanation ("WhatsApp isn't handing me that .docx"),
+sending the user chasing a non-existent bug.
+
+**Fix.**
+1. Raise `media.max_size_mb` to **64**. (Verified `MERCURY_MEDIA_MAX_SIZE_MB` is unset, so
+   the YAML edit will take effect.)
+2. **Always** inject a system note when an attachment is dropped and why, regardless of
+   whether text was present. `src/core/media-gate.ts` already has exactly this pattern
+   (`promptNote`) — copy it.
+3. Optional: for oversize *documents*, download → extract text → discard the binary, so
+   huge files stay readable without being stored.
+
+**Tests.**
+- Unit: an over-limit attachment with a caption still produces a `promptNote`.
+- Unit: note text distinguishes "too large" from "media disabled" from "download failed".
+- Manual: send a ~50 MB docx → it downloads and is readable. Send a ~200 MB file → the bot
+  says *why* it can't read it.
+
+---
+
+### Bug 4 — Cannot create a document
+
+**Symptom:** asked to make a doc, the bot attached HTML + markdown and told the user to
+convert manually.
+
+**Root cause.** No document-writing capability exists. Installed extensions are
+`napkin, pdf, voice-transcribe, web-browser`. The container (`container/Dockerfile`) has
+python3 + pip, node and bun, but **no `python-docx` and no `pandoc`**.
+
+Egress already works — the HTML attachment proves it. The only missing piece is
+*producing* a `.docx`.
+
+**Fix.** A `docs` extension modeled directly on the `pdf` one (which is just `index.ts` +
+a skill dir; its `install` string is compiled into the derived image by
+`extensions/image-builder.ts`, which groups apt/pip/npm installs):
+
+```ts
+mercury.cli({
+  name: "docs",
+  install: "apt-get update && apt-get install -y --no-install-recommends pandoc && "
+         + "python3 -m pip install --break-system-packages python-docx openpyxl odfpy && "
+         + "rm -rf /var/lib/apt/lists/*",
+});
+mercury.permission({ defaultRoles: ["admin", "member"] });
+mercury.skill("./skill");
+```
+
+Plus a `SKILL.md` teaching it to build the `.docx` and drop it in `outbox/`. Real Word
+files, no Google account. *(Actual Google Docs **links** would be a separate Workspace
+extension + OAuth — out of scope.)*
+
+**Tests.**
+- Image build succeeds and `python3 -c "import docx"` works in the derived image.
+- Manual: "make me a doc with X" → a `.docx` arrives in WhatsApp and opens in Word/Docs.
+- Manual: verify a member (not just admin) can trigger it.
+
+---
+
+### Bug 5 — Slash commands imply cross-space reach they don't have
+
+**Symptom:** commands look like they can affect other spaces, e.g. `spaces delete <id>`.
+
+**Root cause — the two surfaces disagree, and the dangerous one silently ignores its argument.**
+
+| Surface | Behaviour |
+|---|---|
+| Chat `/spaces delete <id>` (`runtime.ts:911-933`) | **Honors the id.** Validates the target, stores `pending_delete_id`, deletes that space on confirm. Correct. |
+| `mrctl spaces delete <id>` (`cli/mrctl.ts:384`) | **Silently ignores the argument** — always `DELETE /api/spaces/current`. Deletes the space you're in. |
+
+`cli/mrctl.ts:384` is literally `print(await api("DELETE", "/api/spaces/current"))`; `args[2]`
+is never read. It is the **only** mrctl subcommand that ignores an argument — every other
+one reads `args[2]`. The usage line at `cli/mrctl.ts:85` (`mrctl spaces list|name|delete`)
+shows no args at all, so an agent that has watched users type `/spaces delete <id>` will
+naturally type the same thing at `mrctl` and destroy the current space.
+
+The **API itself is correctly designed** — `core/routes/spaces.ts` deliberately exposes only
+`/current` and has no `/:id` route, scoping every mutation to the caller's own space via
+`getAuth(c).spaceId`. Do **not** "fix" this by adding a `/:id` route; that would remove a
+real security boundary.
+
+**Second, compounding bug — the confirmation can never match on a WhatsApp reply.**
+`handlePendingSpaceDelete` (`runtime.ts:953`) tests `text === "yes"`, where text is
+`message.text.trim().toLowerCase()`. But the WhatsApp adapter **appends a `<reply_to …>`
+block** to the text (`adapters/whatsapp.ts:609`). The confirmation prompt literally says
+"Reply *yes* to confirm" — and replying makes the match fail. Worse, `runtime.ts:981-982`
+clears the pending state **before** evaluating the match, so the correct target is silently
+discarded and the message falls through to the LLM. Typing bare `yes` (not as a reply) is
+currently the only working confirmation.
+
+*(This composition destroyed the `baduk` space on 2026-08-07: 559 messages, 5 tasks,
+14 roles. Recovered from the SQLite WAL.)*
+
+**Fix.**
+1. `cli/mrctl.ts:384` — **reject the argument loudly** rather than ignoring it:
+   ```
+   Error: `mrctl spaces delete` only deletes the CURRENT space and takes no argument.
+   To delete a different space, use the chat command `/spaces delete <id>` as an admin.
+   ```
+2. `cli/mrctl.ts:85` — usage becomes `mrctl spaces list|name [<name>]|delete` with an
+   explicit "(current space only)" note.
+3. `resources/skills/spaces/SKILL.md` — state plainly that `mrctl` is current-space-only
+   and that cross-space deletion is chat-admin-only. *(The skill is already honest; make it emphatic.)*
+4. **Normalize confirmation text before matching.** Strip the `<reply_to …>…</reply_to>`
+   block (and any appended context) before the `yes`/`no` comparison. Best done as a shared
+   helper so every future confirmation flow benefits.
+5. **Reorder `handlePendingSpaceDelete`:** only clear pending state on an actual match,
+   an explicit `no`, or expiry — never on an unrecognized message. A stray message must
+   not silently cancel a pending delete.
+6. Consider requiring the confirmation to echo the target id (`yes cmp-opus`) for
+   cross-space deletes.
+
+**Tests.**
+- Unit: `mrctl spaces delete foo` exits non-zero with the explanatory error and issues **no**
+  HTTP request.
+- Unit: `mrctl spaces delete` (no arg) still works.
+- Unit: confirmation matches `yes` when a `<reply_to>` block is appended (**this is the
+  regression test for the baduk incident**).
+- Unit: an unrelated message does **not** clear pending state; `no` and expiry do.
+- Unit: deleting space A from space B deletes A, not B.
+- Manual: in a throwaway space, `/spaces delete <other-id>` → **reply** "yes" → verify the
+  named space died and the current one survived.
+
+---
+
+### Bug 6 — Command-surface audit: five more defects of the same family
+
+A full audit of every `/` command found that `spaces delete` was not an isolated slip.
+Ordered by severity.
+
+#### 6a. `/stop`, `/compact`, `/clear` silently do nothing (HIGH)
+
+`SLASH_COMMANDS` (`core/commands.ts:15-67`) contains only `help, model, spaces, pause,
+resume`. `stop/compact/clear` live in a **separate** `CHAT_COMMANDS` map
+(`core/router.ts:39-43`) which is matched against the *whole prompt*:
+
+```ts
+const cmdWord = prompt.toLowerCase().trim();
+if (cmdWord in CHAT_COMMANDS) { … }
+```
+
+`stop` matches. **`/stop` does not** — `cmdWord` is `"/stop"`, slash included. It fails the
+slash-command check too (not in `SLASH_COMMANDS`), falls through both, and is sent to the
+model as an ordinary prompt.
+
+So typing `/stop` on a runaway agent **queues another model run instead of aborting one** —
+the exact opposite of the intent, on the emergency-brake command. `/help` lists these under
+*"Bare commands (no slash needed)"*, which reads as "slash optional", not "slash breaks it".
+
+**Fix:** strip a leading `/` before the `CHAT_COMMANDS` lookup (or register them as leaf
+entries in `SLASH_COMMANDS`), and reword the help line to say the slash form works.
+
+#### 6b. Slash commands in groups silently require the trigger word (HIGH)
+
+`routeInput` runs `matchTrigger` at `router.ts:105-106` and returns `ignore` **before** the
+slash parse at `:115`. In a group, a bare `/spaces list` is therefore ignored outright — you
+must write `Wiz /spaces list`.
+
+Meanwhile `handler.ts:236-240` has an `isCommand = text.startsWith("/")` bypass that lets
+`/`-prefixed messages skip the trigger gate — but `routeInput` re-applies it and drops them.
+**The bypass accomplishes nothing** except routing the command into ambient storage.
+
+**Confirmed by live data.** The only two ambient rows in the entire DB are
+`סהר ויצמן: /spaces` and `סהר ויצמן: /spaces delete cmp-opus` — both typed untagged in the
+baduk group, both silently ignored and filed as chat instead of executed.
+
+> **This corrects the incident account in Bug 5.** Those chat commands never ran. The
+> baduk deletion must have come from the agent invoking `mrctl spaces delete <id>`, which
+> ignores its argument and destroys the current space. **That makes the `mrctl` fix (5.1)
+> the load-bearing one**, not the confirmation fix — prioritize accordingly.
+
+**Fix:** honor slash commands without the trigger in groups (matching the handler's evident
+intent), gated so an unknown `/foo` still falls through to ambient rather than becoming a
+command. Otherwise delete the dead bypass and document the requirement.
+
+#### 6c. `/spaces unlink` is an unrecoverable self-lockout in groups (HIGH)
+
+`resolveConversation` (`core/conversation.ts:127`) ends with:
+
+```ts
+if (!autoSpace?.enabled || kind !== "dm") return null;
+```
+
+For a **group**, once unlinked, resolution returns `null`, and `handler.ts:190-197` drops
+every message — **including slash commands**, because that gate sits upstream of
+`routeInput` entirely.
+
+The command's own success text says *"link it to a space with `/spaces switch`"*. That is
+**impossible**: the message will never be routed. Recovery requires the dashboard, the API,
+or a direct DB edit. DMs self-heal via auto-space; groups do not.
+
+**Same failure mode reachable without any command:** `onGroupRemoval` (`main.ts`) unlinks
+the conversation when the bot is removed from a group. Re-adding the bot leaves it
+**permanently deaf** — the conversation is still unlinked and every message is dropped.
+
+**Fix:** keep an unlinked conversation eligible for *link-restoring commands only*
+(`/spaces switch`, `/spaces list`) instead of dropping everything; correct the message text;
+and re-link (or prompt to re-link) on group re-join.
+
+#### 6d. Chat and CLI permission gates disagree (MEDIUM, security-relevant)
+
+| Path | Gate |
+|---|---|
+| Chat `/spaces …` | `SEEDED_ADMIN_COMMANDS` (`router.ts:33`) → **only the seeded admin from config** |
+| `mrctl spaces …` / API | `checkPerm(c, "spaces.delete")` → and `getDefaultPermissions` (`permissions.ts:208-210`) grants **every space `admin` all permissions** |
+
+A promoted space admin is denied `/spaces delete` in chat, but the agent acting on their
+behalf can call `mrctl spaces delete` and destroy the current space. The tighter chat gate
+is bypassable via the CLI.
+
+Members are unaffected — `DEFAULT_MEMBER_PERMISSIONS` (`permissions.ts:192-197`) is only
+`prompt, prefs.get, media.receive, media.send`.
+
+**Fix:** align the two deliberately — either loosen chat to `admin`, or put
+`spaces.delete` behind a seeded-admin-only tier on the API side too. Decide which; don't
+leave them divergent.
+
+#### 6e. `/resume <arg>` ignores its argument; `/help pause` fails (LOW)
+
+- `executeResumeCommand(spaceId, _callerId)` never receives `verb`, so `/resume now` and
+  `/resume 5m` silently behave as bare `/resume`. Same class as `spaces delete`, but with no
+  destructive effect. Reject unknown args for consistency.
+- The `pause` entry (`commands.ts:59-62`) has no `verbs` array, so `formatCategoryHelp`
+  returns null and **`/help pause` answers "No help available for '/pause'."** — even though
+  `/pause` takes a duration. `parsePauseDuration` accepts only `^(\d+)(m|h)$` (no days, no
+  seconds), which is documented nowhere.
+
+#### Redundancy assessment
+
+| Command | Verdict |
+|---|---|
+| `/model active` | **Redundant.** `/model list` already marks the active leg with `← active`. Two commands, one fact. Drop it. |
+| `/compact` vs `/clear` | **Near-identical and undifferentiated.** Both take `MAX(id)` for the space and write a boundary (`db.ts:913` vs `:936`); one sets `session_boundary`, the other `clear_boundary`. Help text ("reset the session context window" vs "clear context for this message") does not let a chat user choose correctly. Merge, or rewrite both descriptions to state the actual difference. |
+| `/help <cat>` vs `/<cat>` | Duplicate paths into `formatCategoryHelp`. Harmless — keep. |
+| `/spaces unlink` | **Recommend removing from chat entirely** (see 6c). It is a one-way door whose only advertised recovery path cannot work. |
+| Everything else | Earns its place. |
+
+**Tests for Bug 6.**
+- Unit: `/stop`, `/compact`, `/clear` route to `type: "command"`; assert they do **not**
+  reach the assistant path (regression for 6a).
+- Unit: a bare `/spaces list` in a group resolves as a command, not ambient (6b).
+- Unit: an unknown `/foo` in a group still falls through to ambient, not a command (6b).
+- Unit: after `unlinkConversation`, `/spaces switch <id>` is still routed and re-links;
+  an ordinary message is still dropped (6c).
+- Unit: a space `admin` (not seeded) gets the same answer from the chat and CLI paths (6d).
+- Unit: `/resume extra` errors rather than silently succeeding; `/help pause` returns real
+  help (6e).
+- Manual: in a throwaway group, unlink then re-link entirely from chat.
+
+---
+
+## 5. When the fixes are done
+
+1. **Gate:** `cd ~/mercury-src && bun run check` (typecheck + lint + tests) must be green.
+2. **Deploy:** section 3 switchover, then `systemctl --user restart mercury`.
+3. **Verify with debug logging on.** Set `log_level: debug` in `mercury.yaml` for the test
+   window. The lines that matter only exist at debug level:
+   - `Incoming message` (`handler.ts:151`) — proves untriggered messages arrive
+   - `Message ignored: conversation not linked to a space` (`handler.ts:191`)
+   - `WhatsApp identity canonicalized` (`whatsapp.ts`) — bug 2
+   - `WhatsApp skipping backlog message` — rules out the reconnect filter
+
+   ⚠️ **Turn debug back off afterwards.** It logs message-content previews into journald —
+   real chat content from a family/friends group sitting in system logs.
+4. **Confirm with data, not vibes:**
+   ```sql
+   SELECT space_id, role, COUNT(*) FROM messages GROUP BY space_id, role;
+   ```
+   Ambient rows for `greece2026` must be > 0 and growing.
+5. **Housekeeping:** delete the stray `~/.mercury/state.db` (147 KB, created by running a
+   mercury command from `$HOME` instead of the project dir — the cwd-scoping trap that makes
+   `auth status` misreport). Verify it isn't the live DB first.
+6. **PR:** one PR from `fix/whatsapp-context-identity-and-docs` → `main`, with a section per
+   change. Must call out:
+   - the four pinchtab commits as **upstreaming an already-live hotfix**, with the
+     `allowedDomains "*"` security tradeoff stated plainly
+   - the `.dockerignore` build fix (exists in no commit anywhere)
+   - the `messages` schema migration and its backfill behaviour
+   - the ambient volume/retention implications
+   - the baduk incident as motivation for the bug-5 regression tests
+   - **behaviour changes in the command surface** (bug 6): `/stop` now aborts instead of
+     prompting, slash commands work untagged in groups, `/spaces unlink` removed or made
+     recoverable, `/model active` dropped. These change what existing users' muscle memory
+     does — list them explicitly rather than burying them in the diff.
+7. **Also decide before pushing:** the 4 pinchtab commits still live only on the D: clone's
+   `fix/pinchtab-browser-startup` branch. Either push that branch too or accept that the
+   cherry-picks supersede it.
+
+---
+
+## 6. Open decisions
+
+| Decision | Recommendation |
+|---|---|
+| Media cap size | 64 MB |
+| Member notes: workspace files vs DB table | Workspace files (`knowledge/members/<id>.md`) — reuses existing plumbing, no migration |
+| Tighten `allowedDomains` from `"*"` | Worth doing eventually; out of scope for this PR, but say so in the PR |
+| Require echoing target id on cross-space delete | Recommended |
+| Slash commands without the trigger word in groups (6b) | **Allow** — matches the handler's evident intent; keep unknown `/foo` falling through to ambient |
+| Align chat vs CLI permission gates (6d) | Pick one deliberately. Leaning: keep `/spaces` seeded-admin-only and lift `spaces.delete` out of the blanket `admin` grant |
+| Drop `/model active` (redundant) | Yes |
+| Merge `/compact` and `/clear` | Don't merge blind — first document the real difference, then decide |
+| Remove `/spaces unlink` from chat | Recommended — one-way door with an impossible recovery path |
+
+## 7. Suggested order
+
+1. **Bugs 1 + 2 together** — same code path, and ambient without attribution produces a wall
+   of anonymous text that could make misidentification *worse*. Bundle the ambient fix, the
+   author columns, and the context cap.
+2. **Bug 5.1 (`mrctl spaces delete` argument) + 6a + 6c** — the three that can destroy data
+   or lock you out. 5.1 is the one that actually killed baduk (see 6b); 6a means the
+   emergency brake doesn't work; 6c is unrecoverable without DB access. All are small.
+3. **Rest of bug 5 + 6b, 6d** — confirmation matching, trigger-gating, permission alignment.
+4. **Bug 3** — config + prompt-note plumbing.
+5. **Bug 4** — new extension, no core changes.
+6. **6e + redundancy cleanup** — cosmetic; fold into the PR last.
+7. **Member memory** — mostly prompt + skill work once attribution lands.